# Rayfin — instructions for coding agents

You are reading the machine-readable entry point for the official Rayfin documentation.
Rayfin is a TypeScript backend platform: you define entities as decorated TypeScript
classes and Rayfin generates the database schema, REST and GraphQL APIs, and type-safe
clients, then runs them on Microsoft Fabric with auth, functions, blob storage, and static
hosting built in.

## How to read these docs

- **Every** documentation route has a raw Markdown mirror: append `.md` to the URL.
  `https://rayfin.ai/docs/data/querying` -> `https://rayfin.ai/docs/data/querying.md`
- [`/llms.txt`](https://rayfin.ai/llms.txt) — index of every page with descriptions, plus the
  size of every bulk download so you can budget a fetch.
- [`/docs/reference/agent-rules`](https://rayfin.ai/docs/reference/agent-rules) — the condensed do/don't list. **Read this before generating Rayfin code.**

Every mirror carries `sdk_version`, `cli_version` and `last_updated` in its frontmatter.
Check them before copying a snippet: API shapes differ between SDK releases, and mixing
them produces code that does not compile.

## Bulk downloads

Prefer a section bundle over the full corpus unless you genuinely need everything.

- [`/llms-full.txt`](https://rayfin.ai/llms-full.txt) — the entire documentation set in one file.
- [`/llms-full/auth.txt`](https://rayfin.ai/llms-full/auth.txt)
- [`/llms-full/connectors.txt`](https://rayfin.ai/llms-full/connectors.txt)
- [`/llms-full/data.txt`](https://rayfin.ai/llms-full/data.txt)
- [`/llms-full/deploy.txt`](https://rayfin.ai/llms-full/deploy.txt)
- [`/llms-full/docs.txt`](https://rayfin.ai/llms-full/docs.txt)
- [`/llms-full/functions.txt`](https://rayfin.ai/llms-full/functions.txt)
- [`/llms-full/hosting.txt`](https://rayfin.ai/llms-full/hosting.txt)
- [`/llms-full/recipes.txt`](https://rayfin.ai/llms-full/recipes.txt)
- [`/llms-full/reference.txt`](https://rayfin.ai/llms-full/reference.txt)
- [`/llms-full/start.txt`](https://rayfin.ai/llms-full/start.txt)
- [`/llms-full/storage.txt`](https://rayfin.ai/llms-full/storage.txt)

## Before you write any Rayfin code

Read [`https://rayfin.ai/docs/reference/agent-rules.md`](https://rayfin.ai/docs/reference/agent-rules.md) and
[`https://rayfin.ai/docs/reference/known-limitations.md`](https://rayfin.ai/docs/reference/known-limitations.md).
Rayfin has platform constraints (text length caps on MSSQL, no many-to-many, foreign key
naming rules) that silently break deployments if ignored.

## All pages

- [Rayfin](https://rayfin.ai/docs.md): Define your data model in TypeScript. Rayfin generates the database and type-safe APIs, then runs them on Microsoft Fabric — with auth, functions, storage, and hosting built in.
- [Auth](https://rayfin.ai/docs/auth.md): Sign users in with Fabric SSO — Rayfin's managed sessions, per-user data isolation, and one client API for every deployed app.
- [Delegated access](https://rayfin.ai/docs/auth/delegated-access.md): Understand how Fabric SSO, function connections, connectors, and entity permissions use the signed-in user's identity.
- [Fabric SSO](https://rayfin.ai/docs/auth/fabric-sso.md): Sign users in with their Microsoft Entra identity through the Fabric portal — enable it in rayfin.yml, install the provider package, and call ensureSignedInWithFabric.
- [React integration](https://rayfin.ai/docs/auth/react.md): An auth context, a useAuth hook, and route guarding for React apps built on the Rayfin auth client with Fabric SSO.
- [Sessions](https://rayfin.ai/docs/auth/sessions.md): How Rayfin's opaque session object works — subscribe with onSessionChange, gate UI on isAuthenticated, and let Rayfin manage tokens for you.
- [Connectors](https://rayfin.ai/docs/connectors.md): Read and write existing Microsoft Fabric data — warehouses, SQL databases, Lakehouse SQL endpoints, semantic models, and KQL databases — from a Rayfin app.
- [Adding a connector](https://rayfin.ai/docs/connectors/adding.md): Discover Fabric sources, add a connector to rayfin.yml, install its pinned packages, and manage connector entries safely.
- [Connector authentication](https://rayfin.ai/docs/connectors/auth.md): Configure connector auth.type values, validation rules, and caller identity for delegated and application connector access.
- [Wiring connectors into your app](https://rayfin.ai/docs/connectors/client-setup.md): Configure ConnectorsRayfinClient with connector schemas, runtime hooks, and browser-safe schema imports.
- [Generating entity files](https://rayfin.ai/docs/connectors/entity-generation.md): Generate Category A connector entity files from metadata.json, including keys, relationships, permissions, aggregate schema, and apply steps.
- [KQL databases](https://rayfin.ai/docs/connectors/kusto.md): Run KQL queries and Kusto management commands against a Fabric KQL Database from a Rayfin app.
- [Semantic models](https://rayfin.ai/docs/connectors/semantic-models.md): Run DAX against a Fabric semantic model from a Rayfin app and handle typed table results, row limits, and connector diagnostics.
- [Fabric SQL sources](https://rayfin.ai/docs/connectors/sql-sources.md): Read and write Fabric SQL connector entities from Rayfin apps, including query chains, by-key reads, mutations, defaults, and troubleshooting.
- [Data](https://rayfin.ai/docs/data.md): Model entities once as decorated TypeScript classes and get a database schema, GraphQL API, type-safe client, permissions, and validation from the same source.
- [Aggregations](https://rayfin.ai/docs/data/aggregations.md): Compute sums, averages, minimums, maximums, and counts over your entities with groupBy() and aggregate(), including grand totals and having filters.
- [Field types](https://rayfin.ai/docs/data/field-types.md): Complete reference for Rayfin's field decorators — @uuid, @text, @int, @decimal, @boolean, @date, @email, @set, and @blob — and the options each accepts.
- [Schema changes](https://rayfin.ai/docs/data/migrations.md): Apply Rayfin entity changes to the database with rayfin up and rayfin up db apply, and verify the schema actually reached the server.
- [Modeling entities](https://rayfin.ai/docs/data/modeling.md): Define Rayfin entities as decorated TypeScript classes in rayfin/data/ and register them in schema.ts to get a database table and a typed API.
- [Creating, updating, deleting](https://rayfin.ai/docs/data/mutations.md): Create, update, and delete Rayfin records through the type-safe client, and set relationship fields correctly in mutations.
- [Permissions and row-level security](https://rayfin.ai/docs/data/permissions.md): Secure Rayfin entities with @role, @anonymous, and @authenticated, including row-level policies, field visibility, action-specific rules, and multi-tenant scoping.
- [Querying](https://rayfin.ai/docs/data/querying.md): Read Rayfin entities with the type-safe select/where/orderBy/execute chain, including filtering, sorting, and cursor pagination.
- [Relationships](https://rayfin.ai/docs/data/relationships.md): Model one-to-many associations between Rayfin entities with @one and @many, and work around the lack of native many-to-many support.
- [Seeding data](https://rayfin.ai/docs/data/seeding.md): Populate @anonymous() Rayfin entities with RayfinServerClient in a Node.js script — @authenticated() entities have no scripted seeding path today.
- [Validation](https://rayfin.ai/docs/data/validation.md): Generate a Standard Schema validator directly from a Rayfin entity to validate form input without a separate validation library.
- [Deploy](https://rayfin.ai/docs/deploy.md): Deploy a Rayfin project to a managed Fabric app with the rayfin up CLI workflow, then manage secrets, environments, and billing.
- [Environments and configuration](https://rayfin.ai/docs/deploy/environments.md): Every environment variable file, prefix, and resolution rule Rayfin tooling reads, from frontend-visible variables to interpolation in rayfin.yml.
- [Fabric apps](https://rayfin.ai/docs/deploy/fabric-apps.md): What a managed Fabric app is, its prerequisites and child services, and how to create and manage one from the Microsoft Fabric portal.
- [Capacity and billing](https://rayfin.ai/docs/deploy/pricing.md): How Fabric capacity billing works for a deployed Rayfin app, and which operations consume Capacity Units and which do not.
- [Deploying with rayfin up](https://rayfin.ai/docs/deploy/rayfin-up.md): Deploy a Rayfin project to Microsoft Fabric with rayfin up, covering login, useful flags, deployment metadata, and redeploys.
- [Secrets](https://rayfin.ai/docs/deploy/secrets.md): Set API keys and tokens on a deployed Fabric app with rayfin secret set, so they stay server-side and never reach client code.
- [Deployment troubleshooting](https://rayfin.ai/docs/deploy/troubleshooting.md): Symptom-to-fix reference for the most common failures when deploying a Rayfin project to Microsoft Fabric.
- [Functions](https://rayfin.ai/docs/functions.md): Run server-side TypeScript in Rayfin — when to use functions instead of client-side data access, and how to enable and scaffold them.
- [Calling functions from your app](https://rayfin.ai/docs/functions/calling-functions.md): Invoke Rayfin functions from the frontend with a type-safe FunctionClient — client.functions.<name>.invoke() and error handling.
- [Connections](https://rayfin.ai/docs/functions/connections.md): Connect a Rayfin function to external services with delegated auth — AudienceType values, the ctx.getToken() pattern, and SQL/Key Vault/OneLake examples.
- [Deploying functions](https://rayfin.ai/docs/functions/deploying.md): How Rayfin functions ship to Fabric with rayfin up, and how to deploy just the functions project with rayfin up functions deploy.
- [Writing a function](https://rayfin.ai/docs/functions/writing-functions.md): The rayfin/functions project layout, registering functions with udf.func in function_app.ts, typed data access, and the auto-generated types.ts schema.
- [Static content hosting](https://rayfin.ai/docs/hosting.md): Deploy your built frontend alongside your Rayfin backend with staticHosting in rayfin.yml — configuration, deployment, limits, and troubleshooting.
- [Redirect URIs](https://rayfin.ai/docs/hosting/redirect-uris.md): Configure allowedRedirectUris in rayfin.yml for auth callbacks and the Fabric SSO handoff, and understand what rayfin up appends automatically.
- [Recipes](https://rayfin.ai/docs/recipes.md): End-to-end walkthroughs that combine Rayfin's data, auth, and deployment features into complete application patterns.
- [Testing a Rayfin app](https://rayfin.ai/docs/recipes/testing.md): Test a Rayfin app's data and auth logic in Vitest without a live backend, using a swappable auth service and an in-memory fallback.
- [Build a todo app](https://rayfin.ai/docs/recipes/todo-app.md): Build a Fabric-authenticated todo app end to end, from a per-user data model through a React UI to a deploy on Microsoft Fabric.
- [Reference overview](https://rayfin.ai/docs/reference.md): Landing page for the complete Rayfin reference — CLI commands, configuration schema, SDK packages, rules for coding agents, known limitations, deprecations, and troubleshooting.
- [Rules for coding agents](https://rayfin.ai/docs/reference/agent-rules.md): The condensed set of rules and anti-patterns for writing Rayfin code — read this before generating entities, queries, permissions, or deployment commands.
- [CLI](https://rayfin.ai/docs/reference/cli.md): Overview of the rayfin CLI — installation, the typical scaffold-to-deploy workflow, and an index of every command page in this reference.
- [Ai-files](https://rayfin.ai/docs/reference/cli/ai-files.md): rayfin init ai-files install and status manage AGENTS.md, .mcp.json, and the Rayfin skill — flags, conflict resolution, exit codes, and the drift nudge in rayfin up.
- [Connector](https://rayfin.ai/docs/reference/cli/connector.md): rayfin connector manages external Fabric sources, from discovery and registration through inspection and invocation.
- [Docs](https://rayfin.ai/docs/reference/cli/docs.md): rayfin docs search, get, list, discover, and catalog show — query version-locked Rayfin documentation from the terminal when the MCP server isn't available.
- [Env](https://rayfin.ai/docs/reference/cli/env.md): rayfin env emits a framework-specific .env.local from rayfin/.env — flags, auto-detection, and why scaffolded projects run it in predev and prebuild.
- [rayfin functions](https://rayfin.ai/docs/reference/cli/functions.md): rayfin functions init scaffolds a serverless TypeScript Functions project under rayfin/functions/ that shares entity types with your Rayfin data model.
- [Init](https://rayfin.ai/docs/reference/cli/init.md): Scaffold a new Rayfin project with npm create, add Rayfin to an existing one with rayfin init, or reconfigure an existing project's services.
- [CLI installation](https://rayfin.ai/docs/reference/cli/installation.md): Install the Rayfin CLI as a project dev dependency, globally, or run it ad hoc with npx — plus how to verify the install and update it.
- [Login](https://rayfin.ai/docs/reference/cli/login.md): Authenticate the CLI with Entra ID for Fabric operations — rayfin login, login status, logout, service principal auth, and where tokens are stored.
- [Secret](https://rayfin.ai/docs/reference/cli/secret.md): rayfin secret set and secret list manage secrets on a deployed Rayfin item — masked interactive input, names/timestamps only, no bulk .env import.
- [Telemetry](https://rayfin.ai/docs/reference/cli/telemetry.md): What the Rayfin CLI collects, what it explicitly does not, and how to opt out with RAYFIN_TELEMETRY_OPTOUT.
- [Templates](https://rayfin.ai/docs/reference/cli/templates.md): Where Rayfin project templates come from — built-in, git, and local sources, registering your own template sources, and authoring a template.
- [Up](https://rayfin.ai/docs/reference/cli/up.md): rayfin up deploys to Microsoft Fabric and applies pending schema migrations in one step — plus every up subcommand for status, schema, and static hosting.
- [Configuration](https://rayfin.ai/docs/reference/config.md): Landing page for Rayfin configuration reference — rayfin.yml schema, the exhaustive environment variable table, and ${VAR} interpolation syntax.
- [Environment variable interpolation](https://rayfin.ai/docs/reference/config/env-interpolation.md): The ${VAR} and ${VAR:-default} syntax Rayfin supports inside rayfin.yml — usage, .env file location, resolution priority, type coercion, and error handling.
- [Environment variables](https://rayfin.ai/docs/reference/config/environment-variables.md): The canonical, exhaustive reference for every environment variable the Rayfin CLI and runtime read or write — frontend, tooling, feature flags, and file locations.
- [rayfin.yml reference](https://rayfin.ai/docs/reference/config/rayfin-yml.md): The complete rayfin.yml schema, key by key — id, services.auth, services.data, services.storage, services.staticHosting, services.functions, and connectors.
- [Deprecation warnings](https://rayfin.ai/docs/reference/deprecations.md): How to silence Rayfin's deprecation warnings in application code, in Node.js scripts, and in browser apps.
- [Errors and troubleshooting](https://rayfin.ai/docs/reference/errors.md): A symptom-to-fix index of the errors Rayfin builders hit most — deployment, schema apply, secrets, static hosting, and Fabric auth.
- [Known limitations](https://rayfin.ai/docs/reference/known-limitations.md): Current constraints in the Rayfin data client, Data API Builder, relationships, auth, and schema apply — organized by area, each with a workaround.
- [SDK](https://rayfin.ai/docs/reference/sdk.md): Which @microsoft/rayfin-* package to install for each capability, how they depend on each other, and version notes for the whole family.
- [@microsoft/rayfin-auth](https://rayfin.ai/docs/reference/sdk/rayfin-auth.md): The Auth client surface — signOut, session management, and the OpaqueSession shape — with exact signatures from the SDK.
- [@microsoft/rayfin-auth-provider-fabric](https://rayfin.ai/docs/reference/sdk/rayfin-auth-provider-fabric.md): Fabric brokered authentication for Rayfin apps — ensureSignedInWithFabric, the embedded and popup flows, and the origins each one works from.
- [@microsoft/rayfin-client](https://rayfin.ai/docs/reference/sdk/rayfin-client.md): RayfinClient construction, configuration options, and the client.data, client.auth, and client.functions facades, with exact signatures from the SDK.
- [@microsoft/rayfin-connector-fabric-graphql](https://rayfin.ai/docs/reference/sdk/rayfin-connector-fabric-graphql.md): Type-only marker APIs for Category A Fabric SQL connectors that expose typed entity CRUD through client.connectors.
- [@microsoft/rayfin-connector-fabric-semanticmodel](https://rayfin.ai/docs/reference/sdk/rayfin-connector-fabric-semanticmodel.md): Marker, runtime, direct execution, URL parsing, Arrow decoding, and normalized result APIs for Fabric semantic model connectors.
- [@microsoft/rayfin-connector-kusto](https://rayfin.ai/docs/reference/sdk/rayfin-connector-kusto.md): Marker, runtime, config, raw response, and normalization APIs for Fabric KQL Database connectors.
- [@microsoft/rayfin-connectors](https://rayfin.ai/docs/reference/sdk/rayfin-connectors.md): Connector runtime APIs for mounting typed Fabric SQL, semantic model, and KQL Database connectors on the Rayfin client.
- [@microsoft/rayfin-core](https://rayfin.ai/docs/reference/sdk/rayfin-core.md): Complete decorator reference for @microsoft/rayfin-core — entities, field types, relationships, and permissions that generate Data API Builder configuration.
- [@microsoft/rayfin-data](https://rayfin.ai/docs/reference/sdk/rayfin-data.md): The fluent GraphQL query and mutation API behind client.data — select, where, orderBy, pagination, and CRUD methods with exact signatures.
- [@microsoft/rayfin-functions](https://rayfin.ai/docs/reference/sdk/rayfin-functions.md): FunctionClient, the FunctionsSchema type, and client.functions.<name>.invoke() for calling serverless functions from the Rayfin SDK.
- [@microsoft/rayfin-lib](https://rayfin.ai/docs/reference/sdk/rayfin-lib.md): The shared ApiClient, error classes, and small utilities every other Rayfin SDK package builds on — an internal dependency most builders never import directly.
- [@microsoft/rayfin-storage](https://rayfin.ai/docs/reference/sdk/rayfin-storage.md): Type-safe blob storage client for Rayfin — what it's for and how to model storage folders today, pending a version-locked API reference.
- [Deploy to Fabric](https://rayfin.ai/docs/start/deploy-to-fabric.md): Enable Fabric apps in your tenant, create one in the Fabric portal, and deploy your project with rayfin login and rayfin up.
- [Installation](https://rayfin.ai/docs/start/installation.md): Install Node.js 20+ and the GitHub CLI on Windows, macOS, or Linux, then verify and update the Rayfin CLI.
- [Project structure](https://rayfin.ai/docs/start/project-structure.md): The rayfin/ folder layout — rayfin.yml, entities under rayfin/data/, schema.ts, generated files, and how the frontend picks up backend config.
- [Quickstart](https://rayfin.ai/docs/start/quickstart.md): Scaffold a Rayfin project, deploy it to Microsoft Fabric, and run the frontend locally — from nothing to a running app in four commands.
- [Storage](https://rayfin.ai/docs/storage.md): What's documented so far about Rayfin's blob storage — the @blob() decorator, storage permissions, and the storage service flag in rayfin.yml.