@microsoft/rayfin-guide 1.35.0-alpha.1412 → 1.35.0-alpha.1541

package/assets/docs/app-backend/deployment-pipelines.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 46
+---
+
+# Fabric Deployment Pipelines
+
+Microsoft Fabric's **Deployment Pipelines** feature promotes an AppBackend between dev/test/prod-style workspace stages without rebuilding it — the same pre-built artifact moves forward as-is.
+This page covers what that means for a Rayfin app and how to check whether yours is ready for it.
+
+## What actually moves
+
+An AppBackend's exported definition is a portable package of pre-built artifacts, not source code:
+
+```text
+MyAppBackend.AppBackend/
+├── .platform            Fabric-managed item metadata
+├── rayfin.yml            Services config (auth, data, storage, staticHosting) — promotes as-is
+├── dab-config.json       Pre-generated DAB entity schema — promotes as-is (dialect-locked)
+└── static-app.zip        Compiled SPA bundle — promotes as-is (byte-identical across stages)
+```
+
+### `rayfin.config.json` — generated per stage, not promoted
+
+When you deploy with `rayfin up`, the CLI writes a `rayfin.config.json` file into `StaticAssets/` alongside the compiled SPA, containing that stage's API URL, publishable key, and Fabric item metadata.
+`resolveRayfinConfig()` reads this file automatically at runtime when it's present, and falls back to whatever `apiUrl`/`publishableKey` defaults you pass in — typically your `VITE_RAYFIN_*` env vars — when it's not, which is the local-dev case before you've ever run `rayfin up`.
+
+This is exactly why `rayfin.config.json` is **deliberately excluded** from the exported definition above: Fabric regenerates it fresh in the target workspace on every Import, using that stage's own API URL, publishable key, and item metadata, so a stale Dev config can never leak into Prod as your app moves through the pipeline.
+
+## Read your backend config with `resolveRayfinConfig()`
+
+Because the compiled SPA bundle moves unchanged between stages, resolve your backend URL and key through `resolveRayfinConfig()` before constructing `RayfinClient` / `RayfinServerClient`, rather than constructing the client from your env vars directly.
+Your `VITE_RAYFIN_API_URL` / `VITE_RAYFIN_PUBLISHABLE_KEY` env vars still belong in your app — `rayfin dev` depends on them — just pass them into `resolveRayfinConfig()` as defaults instead of using them to build the client yourself:
+
+```ts
+import { RayfinClient, resolveRayfinConfig } from '@microsoft/rayfin-client';
+
+const resolved = await resolveRayfinConfig({
+  apiUrl: import.meta.env.VITE_RAYFIN_API_URL,
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+});
+const client = new RayfinClient<Schema>({ ...resolved, authStorage: true });
+```
+
+`resolveRayfinConfig()` prefers `rayfin.config.json` when it's present — every deployed stage — and falls back to the `apiUrl`/`publishableKey` defaults you pass in only when the file is absent, which is the local-dev case. Constructing the client directly from build-time values, skipping `resolveRayfinConfig()`, bakes in whatever you pass and never checks for `rayfin.config.json`, so a promoted bundle would keep pointing at the source environment's backend.
+
+For your backend URL and key alone, call `resolveRayfinConfig()`, not `loadRayfinConfig()` directly — `loadRayfinConfig()` is the lower-level primitive `resolveRayfinConfig()` calls internally to fetch `rayfin.config.json`, and `resolveRayfinConfig()` is the one that overlays the result over your defaults and returns what you should construct the client with.
+If your app also needs Fabric coordinates for its auth broker, pass them alongside `apiUrl`/`publishableKey` in `resolveRayfinConfig()`'s defaults — see [Fabric auth coordinates](#fabric-auth-coordinates-need-clientruntimeconfig) below.
+
+If you're not sure whether your app already resolves config before constructing the client, check for direct construction:
+
+```bash
+grep -rn "new RayfinClient(\|new RayfinServerClient(" src/
+```
+
+Any match there should be preceded by a `resolveRayfinConfig()` call, with its result spread into the constructor as shown above — your existing `VITE_RAYFIN_*` reads can stay, just pass them in as `resolveRayfinConfig()`'s defaults instead of using them to construct the client directly.
+
+## Fabric auth coordinates need `client.runtimeConfig`
+
+If your app embeds in Fabric and drives its own auth flow against the Fabric secure-embed broker, `resolveRayfinConfig()`'s `apiUrl`/`publishableKey` alone aren't enough — your auth wiring also needs the Fabric coordinates (`workspaceId`, `itemId`, `portalUrl`) from the same `rayfin.config.json`.
+
+`client.runtimeConfig` is a single `RayfinRuntimeConfig` bag holding every value `rayfin.config.json` can supply (`apiUrl`, `publishableKey`, `workspaceId`, `itemId`, `portalUrl`, `tenantId`) — all fields optional, since neither the remote config nor your defaults are guaranteed to provide every one. Pass your build-time `VITE_FABRIC_*` values into `resolveRayfinConfig()`'s defaults alongside `apiUrl`/`publishableKey`, and read the resolved coordinates off `client.runtimeConfig` after construction:
+
+```ts
+const resolved = await resolveRayfinConfig({
+  apiUrl: import.meta.env.VITE_RAYFIN_API_URL,
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+  workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
+  itemId: import.meta.env.VITE_FABRIC_ITEM_ID,
+  portalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
+});
+const client = new RayfinClient<Schema>({ ...resolved, authStorage: true });
+
+const { workspaceId, itemId, portalUrl } = client.runtimeConfig ?? {};
+```
+
+`resolveRayfinConfig()` resolves `runtimeConfig` from the same `rayfin.config.json` fetch it already makes for `apiUrl`/`publishableKey`, overlaying remote values over your defaults per-field — no extra request. `resolveFabricConfig()`, which made its own independent fetch for just the Fabric fields, has been removed as redundant — always resolve through `client.runtimeConfig` instead.
+
+Reading `workspaceId`/`itemId`/`portalUrl` directly from `VITE_FABRIC_*` env vars — without going through `client.runtimeConfig` — bakes in whatever stage the bundle was *built* in.
+Since deployment pipelines promote the same compiled bundle across stages without rebuilding, that mismatch only shows up after a promotion: your API calls correctly hit the new stage's backend (via `resolveRayfinConfig()`'s `rayfin.config.json` read), but your auth broker still points at the *old* stage's workspace/item, because it never read from the runtime config at all.
+
+If you're not sure whether your app resolves Fabric coordinates this way, check for direct reads of `VITE_FABRIC_*` that don't go through `runtimeConfig`/`client.runtimeConfig`:
+
+```bash
+grep -rn "VITE_FABRIC_" src/
+```
+
+Any match not passed through `runtimeConfig`/`client.runtimeConfig` should be updated as shown above.
+
+## Out of scope today
+
+- **Functions** (`rayfin/functions/`) — not covered by this pattern yet.
+- **Secrets** — a separate concern from config-file promotion.
+- **Source-code / Git integration** — Deployment Pipelines move built artifacts, not source. [Git integration](https://learn.microsoft.com/en-us/fabric/cicd/git-integration/intro-to-git-integration) is a related but distinct Fabric feature for source-controlling item definitions.
+
+## Related Fabric platform concepts
+
+These are Fabric platform features, not something the Rayfin CLI/SDK controls — see Fabric's own [CI/CD documentation](https://learn.microsoft.com/en-us/fabric/cicd/) for depth:
+
+- **Git integration** — links a workspace to a Git branch for source control of Fabric item definitions.
+- **Deployment pipelines** — promotes items between dev/test/prod-style workspace stages; the feature this page covers.
+- **Variable libraries** — Fabric-managed, stage-scoped values usable across items; not currently wired to `rayfin.config.json` generation, but conceptually related.

package/assets/docs/cli/connectors/add.md

@@ -10,7 +10,7 @@ npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id
 
 `connector add` declares a connector in `rayfin/rayfin.yml` and scaffolds its supporting files.
 
-The CLI verifies the Fabric item, derives a connector `name` from the item's display name (override with `--name`), writes the entry to `rayfin.yml`, scaffolds `rayfin/connectors/<name>/schema.ts`, and runs schema discovery. `rayfin/connectors/<name>/metadata.json` is written so a subset of entities can be generated later.
+The CLI verifies the Fabric item, derives a connector `name` from the item's display name (override with `--name`), writes the entry to `rayfin.yml`, and scaffolds `rayfin/connectors/<name>/schema.ts`. For Category A connectors it also runs schema discovery and writes `rayfin/connectors/<name>/metadata.json` so a subset of entities can be generated later.
 
 If you do not already know the workspace and item IDs, run [`connector search`](./search.md) first — its `--json` output includes a ready-to-run `addCommand` for each result.
 
@@ -58,15 +58,39 @@ Rules:
 
 ## Category B connectors
 
-For `kusto` and `fabric-semanticmodel`, `connector add` writes the `rayfin.yml` entry but there are no GraphQL entities to discover, so no entity files are generated and no row-level security applies:
+For `kusto` and `fabric-semanticmodel`, `connector add` writes the `rayfin.yml` entry and generates a complete typed `schema.ts`, but there are no GraphQL entities to discover, so no entity files are generated and no row-level security applies:
 
-- `executeQuery` is the only allowed operation.
+- `fabric-semanticmodel` allows `executeQuery`; `kusto` allows `executeQuery` and `executeCommand`. Check `rayfin connector types --json` for the current set.
 - `auth.type` must be `delegated`.
 - The connector is pinned to an adapter version.
 - There is no `metadata.json` entity list to generate from.
 
 After adding, exercise the connector with [`connector invoke`](./invoke.md) rather than writing entity code.
 
+## Installing the packages
+
+`connector add` scaffolds files but installs nothing, and the generated `schema.ts` imports packages a fresh app does not declare.
+On success the command prints the exact, version-pinned install to run:
+
+```text
+📦 Install the packages this connector needs:
+   npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha
+```
+
+Run it verbatim.
+**Do not drop the version.** Connector packages ship in lockstep with the CLI, but their npm `latest` and `preview` tags lag the published release, so an unversioned install resolves to an older connector that hard-pins its own `@microsoft/rayfin-data` — leaving two Rayfin version lines in one app.
+
+With `--json`, the same information is available under `install`:
+
+```json
+{
+  "install": {
+    "packages": ["@microsoft/rayfin-connector-kusto@1.35.0-alpha"],
+    "command": "npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha"
+  }
+}
+```
+
 ## Related commands
 
 ```bash

package/assets/docs/cli/connectors/category-a-entities.md

@@ -0,0 +1,675 @@
+---
+sidebar_position: 8
+---
+
+# Category A — GraphQL entity connectors
+
+Reference for `fabric-sqlanalytics` (Lakehouse SQL endpoint), `fabric-warehouse`, and `fabric-sqldatabase`.
+These types surface Fabric SQL as typed entities with read/create/update/delete operations and `@role` row-level security.
+
+For `kusto` and `fabric-semanticmodel`, read [Category B](./category-b-function-bridge.md) instead — none of this page applies to them.
+
+This page picks up after the connector has been added and its `operations:` narrowed.
+Add and scope the connector first: `rayfin connector add --type <type> --workspace-id <ws> --item-id <item> [--operations read,update]`.
+
+## Generate entity files — you, not the CLI
+
+`rayfin connector add` writes `rayfin/connectors/<name>/metadata.json` and a placeholder `schema.ts`, then stops.
+The per-table entity `.ts` files are produced by **you** by reading `metadata.json` and following the [Entity generation contract](#entity-generation-contract).
+The CLI does not emit them.
+
+What to do, in order:
+
+1. Read `rayfin/connectors/<name>/metadata.json` (shape: `SchemaMetadata` — see the [metadata.json reference](#metadatajson-reference)).
+2. Pick the tables in scope.
+   - **Full set** — every table under `schemas[].tables[]`.
+   - **Subset** — only the tables the user named. Filter `schemas[].tables[]` by `tableName` before generating.
+3. For each surviving table, write a file at `rayfin/connectors/<name>/<EntityName>.ts` following the [Entity generation contract](#entity-generation-contract) exactly.
+4. Overwrite the placeholder `rayfin/connectors/<name>/schema.ts` with the [aggregate schema](#aggregate-connector-schema).
+5. Surface every warning the contract emits (no-FK-metadata notes, unknown SQL types). Do not drop them silently.
+
+When the user asks for a refresh ("regenerate everything"), re-do the same flow against the existing `metadata.json`.
+Only re-run `rayfin connector remove` and `rayfin connector add` when the *source schema* changed and you need fresh metadata.
+
+## Scope `@role(...)` on entities
+
+The YAML `operations:` controls which actions reach the source.
+The entity-level `@role(...)` decorator controls which roles can perform which actions on that entity.
+
+The entity's `actions` list **must be a subset** of the YAML `operations:` for that connector.
+The host's settings validator does not catch the mismatch today — DAB will fail at `rayfin up connector apply` time.
+Always narrow YAML first, then add `@role(...)` to entities.
+
+Example: a `fabric-warehouse` connector with `operations: [read, update]` and an `Order` entity locked to read-only:
+
+```ts
+import { entity, int, text, decimal, Source } from '@microsoft/rayfin-core/experimental';
+import { role } from '@microsoft/rayfin-core';
+
+@role('authenticated', ['read'])
+@entity()
+export class Order extends Source({ schema: 'dbo', table: 'Order', primaryKey: ['orderId'] }) {
+  @int({ column: 'OrderID' }) orderId!: number;
+  @text() customerEmail!: string;
+  @decimal({ precision: 18, scale: 2 }) total!: number;
+}
+```
+
+Legal `actions`: `'read' | 'create' | 'update' | 'delete' | '*'`.
+Stack multiple `@role(...)` decorators to give different roles different actions on the same entity.
+
+## Row-level policies
+
+Use a `policy` callback on `@role(...)` for row-level security.
+Policies use the typed `claims` / `item` DSL — never raw SQL strings.
+
+```ts
+@role('authenticated', ['read', 'update'], {
+  policy: (claims, item) => claims.sub.eq(item.owner_id),
+})
+@entity()
+export class Todo extends Source({ schema: 'dbo', table: 'Todo', primaryKey: ['id'] }) {
+  @uuid() id!: string;
+  @uuid() owner_id!: string;
+  @text() body?: string;
+}
+```
+
+DSL surface: `claims.sub | email | role`, `item.<columnName>`, `.eq(...)`, `.and(...)`, `.or(...)`.
+Use any claim the same way — for example `claims.email.eq(item.user_email)`.
+`RoleDeclarationOptions` also accepts `include` and `exclude` arrays for field-level allow/block lists.
+
+When to prompt the user: inspect `metadata.json` for columns named `owner_id`, `user_id`, `tenant_id`, `created_by`.
+If you see one, ask whether that column should restrict rows so each authenticated user only sees their own.
+
+## Aggregate connector schema
+
+Install the connector packages first.
+`rayfin connector add` scaffolds files but installs nothing, and the aggregate `schema.ts` imports two packages a fresh app does not yet declare.
+
+`connector add` prints the exact command to run — copy it from that output, or rebuild it from the `packages` array in `rayfin connector types --json`, which carries both the package names and the version:
+
+```bash
+# Shape only. Use the version connector add printed, not this one.
+npm install @microsoft/rayfin-connector-fabric-graphql@1.35.0-alpha @microsoft/rayfin-connectors@1.35.0-alpha
+```
+
+**Always pin the version.** Connector packages ship in lockstep with the CLI, but their npm `latest` and `preview` tags lag behind.
+An unversioned `npm install` resolves to an older release that hard-pins its own `@microsoft/rayfin-data`, leaving two Rayfin version lines in one app.
+
+- `@microsoft/rayfin-connector-fabric-graphql` — provides `GraphQLBackedConnector`. Not a dependency of `@microsoft/rayfin-client`, so it is always missing on a fresh app.
+- `@microsoft/rayfin-connectors` — provides `ConnectorConfig`. It ships transitively under `@microsoft/rayfin-client`, but declare it directly so strict resolvers (pnpm) do not treat it as a phantom dependency.
+
+Even though both imports are `import type`, TypeScript still needs the packages present at compile time.
+
+The aggregate `rayfin/connectors/<name>/schema.ts` is what the app imports from.
+The CLI leaves a placeholder there; overwrite it so it exports **three** things:
+
+1. **Entity re-exports** — re-export every entity class you generated for this connector, **as types** (`export type { ... }`).
+2. **`<Name>Schema` (type)** — a `GraphQLBackedConnector<TSchema, typeof connectorConfig>` marker.
+   `TSchema` maps each in-scope entity name to its class via `typeof`; the second argument is `typeof connectorConfig`, from which the marker derives both the CRUD operation union and the dialect.
+   This is what makes `client.connectors.<name>.<Entity>.select(...)` strongly typed and gates CRUD methods to the declared operations at compile time.
+3. **`connectorConfig` (value)** — a `ConnectorConfig` carrying the runtime `connector` type, the same `operations` allow-list, and an **`entities` map** keyed exactly as in `TSchema` and covering every entity there.
+   The runtime routes on `connector`, gates CRUD verbs by `operations`, and uses `entities` as the default selection so a read or write without an explicit `select` returns the full row.
+   Give the entries as **string arrays** of entity property names, not entity classes — see below.
+   Only the class form carries relationship cardinality, so a relationship `select` against the array form throws `ENTITIES_REQUIRED_FOR_RELATIONSHIP_SELECT`.
+
+`GraphQLBackedConnector<TSchema, typeof connectorConfig>` **is** the published typed marker for Category A connectors.
+Never invent per-type names like `FabricWarehouse` or `FabricSqlAnalytics` — they do not exist.
+
+### Import entities as types, never as values
+
+This file is imported by browser code, because the app client reads `connectorConfig` from it.
+A value import pulls the decorated entity classes into the browser bundle with it.
+
+That breaks the app. `vite build` still exits 0, type-check passes, lint passes, and deploy succeeds, but the bundler lowers the decorators into an invalid class expression (`var Order = @Source({...})`), the emitted bundle fails to parse, and the page renders blank with `Uncaught SyntaxError: Invalid or unexpected token`.
+Entity classes are build-time declarations consumed by DAB config generation. They have no business in a browser bundle.
+
+Every entity reference in this file is a `typeof` lookup, which is pure type information, so `import type` and `export type` are sufficient:
+
+```ts
+import type { Order } from './Order.js';   // correct
+import { Order } from './Order.js';        // wrong — ships the decorated class
+```
+
+The same applies to the re-exports. Use `export type { Order }`, not `export { Order }`.
+
+This is also why `entities` takes column names rather than classes.
+
+### Single source of truth for operations
+
+For one connector, the `connectorConfig.operations` array and the YAML `operations:` must describe the same verb set — that pair is the connector-wide ceiling.
+Each entity's `@role(...)` actions stay a **subset** of it, so a read-only entity keeps `['read']` on a read/update connector.
+Narrow YAML first, mirror it into `connectorConfig.operations`, then grant each entity only the verbs it actually needs.
+Never widen a decorator to match the connector's full verb set.
+
+### Subset rule
+
+In subset mode, include in `TSchema` only the entities you actually generated.
+Never reference an entity class you did not generate — the `typeof` lookup and its import would dangle.
+
+```ts
+// rayfin/connectors/inventory/schema.ts
+import type { GraphQLBackedConnector } from '@microsoft/rayfin-connector-fabric-graphql';
+import type { ConnectorConfig } from '@microsoft/rayfin-connectors';
+
+import type { Order } from './Order.js';
+import type { Customer } from './Customer.js';
+
+export type { Order } from './Order.js';
+export type { Customer } from './Customer.js';
+
+// Use `as const satisfies` (not a `: ConnectorConfig` annotation) so the
+// `connector` and `operations` literals survive — the marker reads them to
+// derive the permitted operations and the dialect.
+export const connectorConfig = {
+  connector: 'fabric-warehouse',
+  operations: ['read', 'update'],
+  entities: {
+    Order: ['orderId', 'customerId', 'total', 'placedUtc'],
+    Customer: ['customerId', 'email'],
+  },
+} as const satisfies ConnectorConfig;
+
+export type InventorySchema = GraphQLBackedConnector<
+  { Order: typeof Order; Customer: typeof Customer },
+  typeof connectorConfig
+>;
+```
+
+The pattern scales to any number of entities under any names — add one `import type` line, one `export type` line, and one `TSchema` key per entity.
+
+The `<Name>Schema` name is the PascalCase connector name plus `Schema` (connector `inventory` → `InventorySchema`).
+For a read-only Lakehouse (`fabric-sqlanalytics`), `operations` is `['read']`.
+
+### The `entities` map
+
+`connectorConfig.entities` gives the runtime each entity's field names, and it is what makes a call without an explicit `select` work:
+
+- Reads — `findMany(filter?)`, `findFirst(filter?)` and `findByKey` use it as the default selection to return the full row.
+- Writes on `fabric-sqldatabase` — `create` / `update` / `delete` use it to read the row back, including server-generated columns the caller never sent.
+
+**Omitting it is not optional.** Without it, every no-selection read throws `SELECTION_REQUIRED`, on every dialect.
+
+Give the names as **string arrays**, and list every entity in `TSchema`.
+The map also accepts entity classes, but do not use that form here: it puts the decorated classes back in the browser bundle and reintroduces the blank page above.
+
+**Use the entity's property names, not the database column names.**
+These are the names on the generated class — the same keys that appear in the row type — not the `columnName` values in `metadata.json`.
+For `@uuid({ column: 'ProductID' }) productId!: string`, the entry is `productId`.
+The one exception is a field that declares `graphqlName`, in which case use that name.
+Include every scalar field and leave relationship fields out, since those need nested sub-selections.
+
+**Relationship selects need the class form.**
+Cardinality (`@one` versus `@many`) lives in the decorator metadata, which a name array cannot carry, so selecting a relationship path against the array form throws `ENTITIES_REQUIRED_FOR_RELATIONSHIP_SELECT`.
+Scalar reads and writes are unaffected.
+If an app needs relationship selects in browser code, select the foreign key scalar and fetch the related entity separately, or move that query server-side where the class can be imported.
+
+## Wire connectors into the app client
+
+Declaring and deploying a connector does not make it callable from app code.
+Expose it through a `ConnectorsRayfinClient` so it shows up as `client.connectors.<name>`.
+
+`ConnectorsRayfinClient` is experimental — import it only from the `@microsoft/rayfin-client/experimental` subpath, never the stable `@microsoft/rayfin-client` entry.
+
+The connector key must be identical in three places: the `name` in `rayfin.yml`, the property in `AppConnectorsSchema`, and the property in the `connectors` option.
+
+```ts
+import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+import { ProductDbSchema, connectorConfig as productDbConfig } from '../../rayfin/connectors/productDb/schema';
+import { InventorySchema, connectorConfig as inventoryConfig } from '../../rayfin/connectors/inventory/schema';
+
+type AppConnectorsSchema = {
+  productDb: ProductDbSchema;
+  inventory: InventorySchema;
+};
+
+export function getRayfinClient() {
+  // Type params are <DataSchema, FunctionsSchema, ConnectorsSchema> — set the
+  // unused slots to Record<string, never>, or pass real schema types if the app
+  // also has a data model / functions.
+  return new ConnectorsRayfinClient<Record<string, never>, Record<string, never>, AppConnectorsSchema>({
+    baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
+    publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+    authStorage: true,
+    connectors: {
+      productDb: productDbConfig,
+      inventory: inventoryConfig,
+    },
+  });
+}
+```
+
+Verify by type-checking the project (`tsc --noEmit` or the app build).
+A mismatch between a connector key in `AppConnectorsSchema` and the `connectors` option surfaces there.
+
+## Reading and writing connector entities
+
+Each entity is reached through `client.connectors.<name>.<Entity>`.
+What the surface exposes depends on the connector's `operations:` (which gate the verbs) and the connector type/dialect (which shapes what writes return).
+
+### Reads
+
+Reads work identically on Lakehouse, Warehouse, and SQL Database — only writes differ.
+
+```ts
+// Query chain: select -> where -> orderBy -> execute
+const orders = await client.connectors.inventory.Order
+  .select(['orderId', 'customerEmail', 'total'])
+  .where({ total: { gt: 100 } })
+  .orderBy({ total: 'desc' })
+  .execute();
+
+// By-key read. Pass a key OBJECT (all parts of the composite PK) AND a
+// required scalar-only `select`. The result is Pick<Row, selected> | null.
+const order = await client.connectors.inventory.Order.findByKey(
+  { orderId: 'o-1' },
+  ['orderId', 'customerEmail', 'total'],
+);
+
+const lineItem = await client.connectors.sales.OrderItem.findByKey(
+  { orderId: 'o-1', productId: 'p-9' }, // both parts of the composite PK required
+  ['orderId', 'productId', 'quantity'],
+);
+```
+
+`findByKey` takes the key object and a **required** `select` of scalar columns, returning `Pick<Row, selected> | null`.
+Relationships cannot be selected via `findByKey` — read them through the query chain.
+A composite key requires all its parts in the key object; omitting one is a compile error.
+
+### Reading related columns
+
+`select` can pull columns from a related entity — a `@one` (forward FK) or `@many` (reverse FK) navigation field — by naming them as a **dotted path**.
+The builder expands each path into the nested selection the server expects and unwraps the response so the related rows sit inline on the result.
+
+```ts
+const products = await client.connectors.inventory.Product
+  .select(['name', 'category.name', 'orderItems.quantity'])
+  .where({ stock: { gt: 0 } })
+  .execute();
+
+products[0].category.name;          // @one  — related row inline
+products[0].orderItems[0].quantity; // @many — related rows inline (unwrapped)
+
+// Paths nest to arbitrary depth, hopping across entities.
+await client.connectors.inventory.Product
+  .select(['name', 'orderItems.order.customerEmail'])
+  .execute();
+```
+
+- Name related columns as a dotted path (`category.name`), never the bare relationship (`category`) — a navigation field is not a selectable leaf and is a compile error.
+- Each path is validated segment-by-segment against the schema, so a wrong hop (`category.nope`) fails to compile; depth is unbounded.
+- `findByKey` cannot select relationships — it is scalar-only.
+
+Self-referencing foreign keys generate an entity and a DAB relationship, but the client cannot query across one.
+Do not select a dotted path over a self-relationship.
+
+### Writes
+
+`create` / `update` / `delete` exist only when the connector's `operations:` and the entity `@role(...)` allow them, and what they return is fixed by the connector's dialect:
+
+| Connector type | Dialect | `create`/`update`/`delete` return | Notes |
+| --- | --- | --- | --- |
+| `fabric-sqlanalytics` (Lakehouse) | — | **not available** | Read-only at the host; only `select`/`findByKey`/query chain exist. Writes are a compile error. |
+| `fabric-sqldatabase` (SQL Database) | row-returning | the **full entity row** | Reads the whole row back after the write — every column, including server-generated ones the caller did not send. Needs the [`entities` map](#the-entities-map). |
+| `fabric-warehouse` (Warehouse) | no `OUTPUT` clause | `DbOperationResult { result: string }` | DWSQL cannot read the row back, so mutations resolve to a status object. On success `result` is `"success"`; a failed write throws a GraphQL error. |
+
+```ts
+// SQL Database — mutation returns the full row, with every server-generated
+// column filled in by the database.
+const created = await client.connectors.orders.Order.create({
+  quantity: 3,          // supply only the columns you own…
+  unitPrice: 19.99,
+});
+created.id;             // server-assigned identity — returned, though never sent
+created.createdUtc;     // server default (SYSUTCDATETIME()) — returned
+created.lineTotal;      // computed (quantity * unitPrice) — returned
+
+// Warehouse — mutation returns DbOperationResult, NOT the row
+const result = await client.connectors.inventory.Order.update(
+  { orderId: 'o-1' },          // key object (all composite parts)
+  { total: 250 },              // partial update
+);
+result.result;                 // "success" — status string, not the row
+
+// Delete by key (both dialects) — full composite key required
+await client.connectors.sales.OrderItem.delete({ orderId: 'o-1', productId: 'p-9' });
+
+// Lakehouse — writes do not exist
+client.connectors.analytics.Sales.create({ /* ... */ }); // compile error: read-only
+```
+
+**Server-generated columns.**
+These are the columns marked `AutoGenerated<T>` on the entity: `IDENTITY`, any `DEFAULT`, and computed (`AS (...)`) columns.
+They are optional on `create` / `update` and come back populated in the returned row.
+Most cannot be written: passing an `IDENTITY` or computed value is rejected by the database, and rowversion / temporal columns are server-maintained.
+The one exception is a plain `DEFAULT` column — omit it to get the default, or pass a value to override it.
+
+By-key `update`/`delete` take the same full key object as `findByKey`.
+A keyless entity (`primaryKey` omitted or `[]`) exposes no `findByKey` / `update` / `delete` at all — it is read-only regardless of the connector type.
+
+### Quick decision guide
+
+- **Lakehouse (`fabric-sqlanalytics`)** — reads only. Model entities, `select`, `findByKey`, query chain. No `@role` write actions.
+- **SQL Database (`fabric-sqldatabase`)** — full CRUD; mutations hand back the full row, so you can render the created/updated record directly.
+- **Warehouse (`fabric-warehouse`)** — full CRUD; mutations hand back a `DbOperationResult`, so re-query with `findByKey`/`select` if you need the persisted values.
+
+For aggregation, `groupBy`, or year/quarter/month time-bucketing, search the docs (`rayfin docs search`).
+
+## Worked example — a use case on specific entities
+
+The user already ran `rayfin connector add` for a `fabric-warehouse` connector named `sales` and says *"I just need users to read and update orders and their line items."*
+
+- **Scope and narrow.** Operations are `read`, `update`; set `operations:` on the `sales` entry to just those.
+- **Generate the subset.** Filter `metadata.json` to `Order` and `OrderItem`, write both per the contract. Drop any `@one(() => Customer, ...)` to an out-of-scope table (no dangling import).
+- **Roles and aggregate.** `@role('authenticated', ['read', 'update'])` on both; aggregate `SalesSchema = GraphQLBackedConnector<{ Order: typeof Order; OrderItem: typeof OrderItem }, typeof connectorConfig>`, with both entities imported and re-exported as **types**, and `connectorConfig` declared `as const satisfies ConnectorConfig` with `operations: ['read', 'update']`.
+- **Wire and verify.** Add `sales` to `AppConnectorsSchema` and the `connectors` option. Type-check: `client.connectors.sales.Order.create(...)` is now a compile error — the proof the scope took effect. Deploy with `rayfin up`.
+
+## Entity generation contract
+
+When you generate `rayfin/connectors/<name>/<EntityName>.ts` from `metadata.json`, follow these rules end-to-end.
+`metadata.json` is the only source of truth for physical keys and relationships — never infer either from column names, values, naming conventions, or table shape.
+The CLI itself does not emit entity files.
+
+### 1. File name and class name
+
+- `className = pascalCase(table.tableName)` (for example `product_category` → `ProductCategory`).
+- **Pluralization is allowed, but must be idempotent — never double-pluralize.**
+  Pluralizing a singular table name is fine (`Order` → `Orders`, `Category` → `Categories`).
+  But first check whether the name is already plural: if the source table is already plural (`Orders`, `Categories`, `sales_line_items`), keep it exactly as-is — do not add another plural suffix.
+  Whatever name you settle on, the `@entity` name and the `client.connectors.<name>.<Entity>` access path must stay consistent with it.
+- File name is `<className>.ts`. One file per table; no nesting.
+- **Cross-connector uniqueness — disambiguate only on collision.**
+  GraphQL type names are global across every connector in the app: two connectors that each produce an entity with the same name collide at `rayfin up connector apply` time even when they point at different physical tables.
+  Before finalizing a name, scan every other `rayfin/connectors/*/` directory and the entities you have already generated for the current connector for a matching class / `@entity` name.
+  If — and only if — the base name is already taken, prefix it with the connector's source database name (PascalCased, from `metadata.json` `source`): `Product` → `SalesDbProduct`.
+  Disambiguation is required even when the colliding entities refer to the same physical source table.
+  If that database name is itself shared across the colliding connectors, fall back to the PascalCased connector name (the `rayfin.yml` `name`, which the host guarantees unique).
+  Never rename a name that does not collide, and never blanket-prefix every entity.
+  When you rename an entity, use the disambiguated name everywhere: the class name, the file name, the `@entity` name, the `TSchema` key and re-export, and the `client.connectors.<name>.<Entity>` access path.
+  Surface a one-line note to the user for each rename.
+
+### 2. Primary keys from metadata
+
+When `table.primaryKeyColumns` is present and non-empty, declare exactly those columns on `Source(...)`, using each column's TypeScript property name and preserving `table.primaryKeyColumns` (`ORDINAL_POSITION`) order.
+This rule applies to single-column and composite keys.
+Keep one property per key column and preserve each SQL column name with `column:` when it differs.
+
+```ts
+export class OrderItem extends Source({
+  schema: 'dbo',
+  table: 'OrderItem',
+  primaryKey: ['orderId', 'productId'],
+}) {
+  @uuid({ column: 'OrderID' }) orderId!: string;
+  @uuid({ column: 'ProductID' }) productId!: string;
+  @int() quantity!: number;
+}
+```
+
+Every key part is then required in the by-key methods (`findByKey`/`update`/`delete`).
+
+When `primaryKeyColumns` is absent or empty, emit `primaryKey: []`.
+The entity is keyless and exposes no `findByKey`/`update`/`delete` methods.
+Do not choose a column as a synthetic key, including columns named `id`, columns that appear unique in sampled data, or the first non-nullable column.
+
+Lakehouse SQL endpoints commonly omit PK metadata.
+For `fabric-sqlanalytics`, this means generating a read-only, keyless entity unless `primaryKeyColumns` is actually present in `metadata.json`.
+Never add a logical PK on the agent's own initiative; a Builder may deliberately declare one later when they know the source's logical uniqueness contract.
+
+### 3. Key-field validation
+
+- Resolve every `primaryKeyColumns` entry against `table.columns` by exact SQL column name before converting it to a TypeScript property name.
+- Preserve the metadata order for composite keys.
+- A key column must be non-nullable. If metadata names a nullable or missing column, do not guess a replacement; stop generation for that table and report the inconsistency.
+- An empty table or a table without PK metadata is keyless.
+
+The key's property name and datatype come from the matching column metadata; the PK is not renamed to `id`.
+Preserve the on-disk SQL column name via the `column:` option.
+
+### 4. SQL type to decorator mapping
+
+Look up `column.dataType` (case-insensitive) in this table:
+
+| SQL type family | Decorator | TS type |
+| --- | --- | --- |
+| `int`, `bigint`, `smallint`, `tinyint` | `@int()` | `number` |
+| `decimal`, `numeric`, `money`, `smallmoney`, `float`, `real` | `@decimal({ precision, scale })` | `number` |
+| `bit` | `@boolean()` | `boolean` |
+| `date`, `datetime`, `datetime2`, `smalldatetime`, `datetimeoffset`, `time` | `@date()` | `Date` |
+| `uniqueidentifier` | `@uuid()` | `string` |
+| `varchar`, `nvarchar`, `char`, `nchar`, `text`, `ntext` | `@text()` | `string` |
+| Anything else (`geography`, `hierarchyid`, `xml`, vector) | `@text()` + warning | `string` |
+
+For the fallback case, emit a warning: `Unknown SQL type <dataType> for <table>.<column>; falling back to @text().`
+
+### 4a. Server-generated columns
+
+`metadata.json` flags the columns the database fills in.
+On each column, check for these server-generation markers:
+
+- `identity` — an `IDENTITY(seed, increment)` key.
+- `default` — a column `DEFAULT` (for example `newid()`, `sysutcdatetime()`, `NEXT VALUE FOR <seq>`).
+- `computed` — a computed column (`AS (<expr>)`).
+- `serverManaged` — a column the server maintains with no user-facing expression: `'rowversion'`, `'temporalRowStart'`, or `'temporalRowEnd'`.
+
+If any of these is present, the column is server-generated: wrap its TS type from section 4 in `AutoGenerated<…>`.
+The decorator and its `column:` option are unchanged; do not emit a `default:` option — the marker is type-only and the connector never writes these columns.
+
+`AutoGenerated<T>` makes the column optional on create/update input and read back as plain `T` in the returned row.
+Nullability is unchanged: a non-null server-generated column still uses `!:`; a nullable one uses `?:`.
+
+Optional on input does not mean "accepts a value".
+For most server-generated columns, passing a value is rejected by the database:
+
+- `identity` — inserting an explicit value fails. Never send it.
+- `computed` — a computed column cannot be written; setting it is a server error.
+- `serverManaged` — server-maintained; writing is rejected.
+- plain `default` — the one exception: omit it to get the default, or pass a value to override it.
+
+```ts
+@int({ column: 'Id' })
+id!: AutoGenerated<number>;         // IDENTITY — omit on write, server assigns
+
+@uuid({ column: 'PublicId' })
+publicId!: AutoGenerated<string>;   // DEFAULT newid()
+
+@decimal({ optional: true, column: 'LineTotal', precision: 28, scale: 2 })
+lineTotal?: AutoGenerated<number>;  // computed: AS ([Quantity] * [UnitPrice])
+
+@text({ column: 'RowVer' })
+rowVer!: AutoGenerated<string>;     // rowversion (serverManaged) — read-back-only
+```
+
+### 5. Field-level decorator options
+
+For every column, the decorator option object is built in this order (omit keys you do not need):
+
+1. `optional: true` — if `column.isNullable` is true.
+2. `column: '<columnName>'` — when the SQL column name differs from the TS property name. Single-quote the value; escape embedded `'`.
+3. **Text only:** `max: <maxLength>` — when the decorator is `text` and `column.maxLength > 0`.
+4. **Decimal only:** `precision: <p>, scale: <s>` — when the decorator is `decimal` and both are present in metadata.
+5. **Integer:** do not emit `min`/`max` based on SQL precision; those are value bounds, not storage capacity. Plain `@int()` is correct.
+
+If the option object is empty, emit `@text()` rather than `@text({})`.
+
+Property name is always `camelCase(column.columnName)` — the PK is not special-cased or renamed to `id`.
+Nullable columns use `?:`; non-nullable use `!:`.
+
+### 5a. Server-generated columns have no decorator option
+
+`metadata.json` carries `column.identity`, `column.default`, and `column.computed`, but no field decorator has an option to mark a column as server-generated.
+Do not invent one.
+
+Declare the column normally — those markers change nothing about the emitted decorator, beyond the `AutoGenerated<T>` type wrapper in section 4a.
+What they do change is what you tell the Builder: surface a one-line note for each such column (for example, `Column '<table>.<column>' is server-generated (identity); the source will populate it, so omit it on create()`).
+
+An identity or computed column that is also a declared key follows the normal [primary key rules](#2-primary-keys-from-metadata) unchanged — being server-generated never exempts it from key-field validation.
+
+### 6. Global-type shadow rule
+
+If `pascalCase(table.tableName)` equals a column's TS type (for example a table named `Date` with a `datetime2` column), the unqualified `Date` in the annotation resolves to the entity class, not the global.
+Render the type as `globalThis.Date` in that one field annotation only.
+
+### 7. Relationships
+
+Forward (`@one`) and reverse (`@many`) relationships are emitted from foreign-key metadata **only**.
+Do not infer Lakehouse relationships from matching column names, star-schema naming, or sampled values.
+
+Schema discovery records an FK on the referencing table only, so `table.foreignKeys` governs **forward** relationships alone.
+When it is absent or empty, emit no `@one` — but still emit every `@many` the reverse-FK index below produces, because a parent table legitimately has no FKs of its own while being the target of another table's.
+A table with neither its own FKs nor any incoming constraint gets no relationship decorators at all.
+
+Before generating relationships, group `table.foreignKeys` entries by `constraintName`.
+One group is one FK relationship; rows in the same group are the ordered column pairs of a composite FK.
+Preserve their metadata order.
+
+**`@one` — one per FK constraint on this table.** For each FK constraint group:
+
+- All rows must reference the same schema and table. If they do not, report inconsistent metadata and skip the constraint.
+- `fieldName = camelCase(singularize(referencedTableName))`. If more than one constraint on the table would produce the same field name, derive a stable disambiguated name from `constraintName` rather than overwriting one.
+- `sourceFields = group.map(fk => camelCase(fk.columnName))`.
+- `targetFields = group.map(fk => camelCase(fk.referencedColumnName))`.
+- The relationship is optional when any source column in the group is nullable. Emit `{ optional: true }` and `?:` in that case.
+
+```ts
+@one(() => <ReferencedClass>, { sourceFields: ['<src1>', '<src2>'], targetFields: ['<tgt1>', '<tgt2>'] })
+<fieldName>!: <ReferencedClass>;
+
+// Optional relationship
+@one(() => <ReferencedClass>, { optional: true, sourceFields: ['<src>'], targetFields: ['<tgt>'] })
+<fieldName>?: <ReferencedClass>;
+```
+
+Self-referencing FK constraints follow the same rules and must be optional.
+Use the current class directly in the resolver and add no sibling import.
+The entity and DAB relationship generate fine, but the client does not currently support selecting a dotted path across a self-relationship.
+
+If the referenced table is not in the table index, skip the relationship and warn: `Foreign key <table>.<column> references unknown table <refSchema>.<refTable>; relationship skipped.`
+
+In subset mode, apply the same skip when the referenced table exists in `metadata.json` but is not in the set you are generating: omit the `@one` and its sibling import, and warn that the relationship was dropped because the target is out of scope.
+Never import a `./<Class>.js` file you did not write.
+
+**`@many` — reverse-direction relationships pointing at this table.**
+Build a reverse-FK index across all tables: every grouped FK constraint from another table to this table becomes one `@many` on this table.
+
+- `fieldName = camelCase(pluralize(otherTable.tableName))` — `pluralize` is idempotent, so an already-plural table (`Orders`) stays `orders`, never `orderses`.
+- `sourceFields = group.map(fk => camelCase(fk.referencedColumnName))` — this table's referenced properties.
+- `targetFields = group.map(fk => camelCase(fk.columnName))` — the other table's FK properties.
+
+```ts
+@many(() => <OtherClass>, { sourceFields: ['<src>'], targetFields: ['<tgt>'] })
+<fieldName>!: <OtherClass>[];
+```
+
+In subset mode, only emit a `@many` when the other table is also being generated.
+
+`singularize` / `pluralize` are the same simplified rules the generator uses:
+
+- `singularize`: `ies → y` (length > 3); `xes|ses|ches|shes → drop -es`; `<non-s>s → drop trailing -s`; else unchanged.
+- `pluralize` (idempotent): if the name is already plural (ends in `s`, `es`, or `ies`), return it unchanged; otherwise `<non-vowel>y → -ies`; `x|z|ch|sh → +es`; else `+s`.
+
+### 8. Missing key and relationship metadata
+
+When `primaryKeyColumns` is absent or empty, emit one warning to the user: `No PK metadata available for <tableName>; generated as a keyless entity.`
+
+When `foreignKeys` is absent or empty and no reverse FK constraint points at the table, emit one warning: `No FK metadata available for <tableName>; relationships omitted.`
+
+For Lakehouse, these warnings describe a known metadata limitation, not a request to infer schema.
+The entity file still generates with `primaryKey: []` and without `@one`/`@many`.
+If the Builder knows logical keys or relationships the endpoint does not expose, explain that they may add those declarations manually; never add them without that explicit input.
+
+### 9. Imports
+
+Build the import line deterministically:
+
+- Always include `entity` and `Source`.
+- Then append, in this exact order, any decorator names actually used in the file: `boolean`, `date`, `decimal`, `int`, `text`, `uuid`, `one`, `many`. Skip any not used.
+- All from `@microsoft/rayfin-core/experimental`.
+- If any column is server-generated, also add `import type { AutoGenerated } from '@microsoft/rayfin-core/experimental';`.
+- For every relationship target that is a different class, add a sibling import: `import { <SiblingClass> } from './<SiblingClass>.js';`. Sibling imports are alphabetised; self-references get no sibling import.
+- In subset mode, only relationships that survived the subset skip contribute sibling imports.
+
+### 10. Canonical example
+
+```ts
+// @generated — do not edit.
+
+import { entity, uuid, text, int, date, one, many, Source } from '@microsoft/rayfin-core/experimental';
+import type { AutoGenerated } from '@microsoft/rayfin-core/experimental';
+import { Category } from './Category.js';
+import { OrderItem } from './OrderItem.js';
+
+@entity()
+export class Product extends Source({ schema: 'dbo', table: 'Product', primaryKey: ['productId'] }) {
+  @uuid({ column: 'ProductID' })
+  productId!: string;
+
+  @text()
+  name!: string;
+
+  @int()
+  stock!: number;
+
+  // DEFAULT sysutcdatetime() — server-generated, so AutoGenerated: optional on
+  // write, read back in the returned row.
+  @date({ column: 'CreatedUtc' })
+  createdUtc!: AutoGenerated<Date>;
+
+  @one(() => Category, { sourceFields: ['categoryId'], targetFields: ['categoryId'] })
+  category!: Category;
+
+  @many(() => OrderItem, { sourceFields: ['productId'], targetFields: ['productId'] })
+  orderItems!: OrderItem[];
+}
+```
+
+## metadata.json reference
+
+Path: `rayfin/connectors/<name>/metadata.json`.
+Written by `connector add`; never edit by hand.
+It is regenerated only by `rayfin connector remove <name>` followed by `rayfin connector add ...`.
+
+Top-level: `SchemaMetadata { source, connector, connectionString, discoveredAt, schemas[] }`.
+Each schema entry: `{ schemaName, tables[] }`.
+Each table: `{ tableName, columns[], foreignKeys?, primaryKeyColumns? }`.
+
+Columns carry `columnName`, `dataType`, `isNullable`, and optional `maxLength` / `precision` / `scale`.
+Server-generated columns additionally carry `identity` (`{ seed, increment }`), `default` (the SQL default expression), `computed` (the `AS (...)` expression), `serverManaged`, and `datePrecision`.
+Foreign keys carry `constraintName`, `columnName`, and the `referencedTableSchema` / `referencedTableName` / `referencedColumnName` triple.
+
+`primaryKeyColumns`, when available, contains single-column or composite PKs in `ORDINAL_POSITION` order.
+Multiple `foreignKeys` entries with the same `constraintName` form one composite FK and must be generated as one relationship.
+
+Fabric SQL Database generally exposes PK/FK and server-generation metadata.
+Warehouse and Lakehouse may omit some catalog metadata; Lakehouse commonly omits PK/FK constraints entirely.
+Absence means "unknown / not exposed", not permission to synthesize keys or relationships.
+
+## Category A anti-patterns
+
+- Never leave `schema.ts` as bare re-exports — the client import of `<Name>Schema` and `connectorConfig` would fail.
+- Never import or re-export entity classes as **values** in `schema.ts`. Use `import type` / `export type`; a value import ships decorated classes to the browser and the page renders blank.
+- Populate `connectorConfig.entities` with **column-name arrays**, never entity classes. Omitting it makes every no-selection read throw `SELECTION_REQUIRED`; using classes puts them back in the bundle.
+- In subset mode, list in `TSchema` only entities you actually generated.
+- Keep `connectorConfig.operations` identical to the YAML `operations:`, and keep each entity `@role(...)` action a subset of that pair. Narrow YAML first; never widen above the type's catalog allowlist, and never widen a decorator just to match the connector.
+- Policies use the typed `claims` / `item` DSL — never raw SQL or DAB-policy strings like `"@claims.sub eq @item.owner_id"`.
+- Never double-pluralize an entity/class name.
+- GraphQL type names are global across connectors — disambiguate duplicates, never blanket-prefix.
+- `metadata.json` is the only source of truth for keys and relationships. Never synthesize a primary key or infer a relationship from column names, sampled values, or naming conventions — absent metadata means keyless and relationship-free.
+- When the user asks for one entity, read `metadata.json` and filter — do not regenerate every table.
+- Never edit `metadata.json` or `dab-config.json` by hand — both are regenerated.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `rayfin up connector apply` fails on a role action | Entity `@role(...)` includes an action not in the YAML `operations:` | Narrow the decorator to match YAML. |
+| `rayfin up connector apply` fails with a duplicate / redefined GraphQL type | Two connectors generated an entity with the same name — type names are global | Disambiguate the colliding entity by prefixing its source database name; update the class, file name, `@entity` name, `TSchema` key, and access path together, then re-apply. |
+| `rayfin connector add` writes the YAML entry but no entity files | Expected — the CLI never emits entity `.ts` files | Generate them from `metadata.json` per the contract. If `metadata.json` is also missing, schema discovery failed. |
+| `Property '<name>' does not exist on connectors` | Connector key in `AppConnectorsSchema` does not match the key in the `connectors` option | Use the `rayfin.yml` `name` in all three places. |
+| A CRUD method is missing from autocomplete | Expected: `<Name>Schema` narrows methods to the connector's `operations` | Widen the allow-list via `rayfin connector add --operations`, then re-import. |
+| Import of `ConnectorsRayfinClient` fails to resolve | Imported from the stable `@microsoft/rayfin-client` entry | Import from `@microsoft/rayfin-client/experimental`. |
+| `Cannot find module '@microsoft/rayfin-connector-fabric-graphql'` | The connector packages were never installed — `connector add` does not add them | Run the pinned `npm install` command `connector add` printed, or rebuild it from `rayfin connector types --json`. |
+| Deployed page is blank with `Uncaught SyntaxError: Invalid or unexpected token`, though build, tests and deploy all passed | `schema.ts` imports or re-exports entity classes as values, so the decorated classes were bundled into the browser build | Switch every entity import and re-export in `schema.ts` to `import type` / `export type`, and give `connectorConfig.entities` column-name arrays instead of classes. |
+| A read throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing, so there is no default column list | Add the entity's property names, or pass an explicit `select([...])`. |
+| A read returns null or errors on a field that exists in the database | `entities` lists database column names instead of the entity's property names | Use the names declared on the generated class (or `graphqlName` where set), for example `productId`, not `ProductID`. |

package/assets/docs/cli/connectors/category-b-function-bridge.md

@@ -0,0 +1,269 @@
+---
+sidebar_position: 7
+---
+
+# Category B — function-bridge connectors
+
+Reference for `kusto` (Fabric KQL Database) and `fabric-semanticmodel` (Power BI semantic model).
+A Category B connector is a named-operation surface backed by a small, platform-owned function (UDF).
+The Builder never writes or sees the function code.
+
+The Builder declares the connector and calls a typed method; the Fabric app backend injects connector configuration and delegated authentication before forwarding to the function.
+There are no GraphQL entities, so do **not** generate entity files, `@role` policies, or `metadata.json` entities for these connector types.
+
+For the entity-generating types (`fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`), read [Category A](./category-a-entities.md) instead.
+
+## What each type exposes
+
+| Type | Operations | Query language | Auth |
+| --- | --- | --- | --- |
+| `kusto` | `executeQuery`, `executeCommand` | KQL | `delegated` only |
+| `fabric-semanticmodel` | `executeQuery` | DAX | `delegated` only |
+
+Both are pinned to an adapter version (`version: '1'` today).
+Delegated authentication runs every call as the signed-in user through the on-behalf-of flow.
+
+## Add the connector
+
+```bash
+rayfin connector add \
+  --type kusto \
+  --workspace-id <ws-id> \
+  --item-id <kql-database-item-id> \
+  --name telemetry
+```
+
+`--item-id` identifies the Fabric item to query: a KQL Database for `kusto`, a semantic model for `fabric-semanticmodel`.
+Omit `--name` to derive the connector name from the Fabric item's display name.
+
+The CLI verifies the item, writes the `rayfin.yml` entry, and scaffolds `rayfin/connectors/<name>/schema.ts`.
+
+## Resulting rayfin.yml
+
+```yaml
+connectors:
+  - name: telemetry
+    type: kusto
+    version: '1'
+    config:
+      workspaceId: <ws-id>
+      itemId: <kql-database-item-id>
+    auth:
+      type: delegated
+    operations:
+      - name: executeQuery
+      - name: executeCommand
+```
+
+The `config` block is the single source of truth for what to query and is not sent on the client wire.
+`kusto` allows `executeQuery` and `executeCommand`; `fabric-semanticmodel` allows `executeQuery`.
+In every case `auth.type` must be `delegated`.
+
+## The generated schema.ts
+
+`connector add` writes `rayfin/connectors/<name>/schema.ts` with a `// @generated — do not edit.` banner.
+Do not hand-edit it.
+Regenerate it by removing and re-adding the connector (`rayfin connector remove <name>`, then `rayfin connector add ...`).
+
+For `fabric-semanticmodel` the file exports the typed marker plus a generic runtime config:
+
+```ts
+import type { ConnectorConfig } from '@microsoft/rayfin-connectors';
+import type { FabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
+
+export type SalesModelSchema = FabricSemanticModel<'executeQuery'>;
+
+export const connectorConfig = {
+  connector: 'fabric-semanticmodel',
+} as const satisfies ConnectorConfig;
+```
+
+### Kusto bakes cluster routing into the generated file
+
+`connector add --type kusto` resolves the KQL Database's cluster query endpoint and database name from `(workspaceId, itemId)` at add time and writes both into the generated `connectorConfig`:
+
+```ts
+import type { Kusto, KustoConnectorConfig } from '@microsoft/rayfin-connector-kusto';
+
+export type TelemetrySchema = Kusto<'executeQuery' | 'executeCommand'>;
+
+export const connectorConfig = {
+  connector: 'kusto',
+  queryServiceUri: 'https://<cluster>.kusto.fabric.microsoft.com',
+  databaseName: '<database>',
+} as const satisfies KustoConnectorConfig;
+```
+
+Three names appear here and nowhere else:
+
+- `queryServiceUri` — the resolved Kusto cluster query endpoint.
+- `databaseName` — the resolved KQL database name.
+- `KustoConnectorConfig` — the Kusto-specific config type these two keys satisfy, exported from `@microsoft/rayfin-connector-kusto` rather than `@microsoft/rayfin-connectors`.
+
+These keys live only in the file the Kusto scaffold writes.
+They are **not** part of the shared `rayfin.yml` schema — never write a cluster URI or database name into `rayfin.yml`, and never send either value from app code.
+If the resolved values look wrong, re-add the connector rather than editing the generated file; the values come from Fabric, not from anything you can fix by hand.
+
+The Kusto scaffold imports both its marker and `KustoConnectorConfig` from `@microsoft/rayfin-connector-kusto`, so it does not import `@microsoft/rayfin-connectors` at all.
+
+## Install the packages the generated file imports
+
+`connector add` scaffolds files but installs nothing. It prints the exact pinned command — copy it from that output, or rebuild it from the `packages` array in `rayfin connector types --json`, which carries both the package names and the version:
+
+```bash
+# Shape only. Use the version connector add printed, not this one.
+
+# kusto — marker and config type both come from this one package
+npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha
+
+# fabric-semanticmodel
+npm install @microsoft/rayfin-connector-fabric-semanticmodel@1.35.0-alpha @microsoft/rayfin-connectors@1.35.0-alpha
+```
+
+**Always pin the version.** Connector packages ship in lockstep with the CLI, but their npm `latest` and `preview` tags lag behind, so an unversioned install pulls an older release and its own mismatched `@microsoft/rayfin-data`.
+
+## Wire into the app client
+
+Use the same `ConnectorsRayfinClient` wiring as Category A, but with no entity re-exports and no `GraphQLBackedConnector`.
+Import the generated `<Name>Schema` type and `connectorConfig` value, key both maps by the exact `rayfin.yml` connector name, and pass the config through the client's `connectors` option.
+
+Category B additionally needs a **connector runtime map** as the client's second constructor argument.
+This is not optional: the runtime is what injects the generated routing and decodes the response.
+
+- `kusto()` merges the generated `queryServiceUri` and `databaseName` into the outbound payload. Without it, `executeQuery` and `executeCommand` cannot route to the cluster.
+- `fabricSemanticModel()` decodes the Arrow response. Without it, `executeQuery` results cannot be read.
+
+Key the runtime map by the same connector name, and call the factory once per connector:
+
+```ts
+import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+import { kusto } from '@microsoft/rayfin-connector-kusto';
+import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
+import {
+  type TelemetrySchema,
+  connectorConfig as telemetryConfig,
+} from '../../rayfin/connectors/telemetry/schema';
+import {
+  type SalesModelSchema,
+  connectorConfig as salesModelConfig,
+} from '../../rayfin/connectors/salesModel/schema';
+
+type AppConnectorsSchema = {
+  telemetry: TelemetrySchema;
+  salesModel: SalesModelSchema;
+};
+
+const client = new ConnectorsRayfinClient<
+  Record<string, never>,
+  Record<string, never>,
+  AppConnectorsSchema
+>(
+  {
+    baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
+    publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+    connectors: {
+      telemetry: telemetryConfig,
+      salesModel: salesModelConfig,
+    },
+  },
+  // Second argument: per-connector runtime hooks, keyed by connector name.
+  {
+    telemetry: kusto(),
+    salesModel: fabricSemanticModel(),
+  }
+);
+```
+
+`ConnectorsRayfinClient` is experimental — import it only from the `@microsoft/rayfin-client/experimental` subpath, never the stable `@microsoft/rayfin-client` entry.
+
+The connector key must be identical in four places: the `name` in `rayfin.yml`, the property in `AppConnectorsSchema`, the property in the `connectors` option, and the property in the runtime map.
+
+## Calling a Kusto connector
+
+Correlation ids are not part of the response body — the connector function relays the Kusto bytes untouched — so generate the `clientRequestId` yourself and pass the same value to both `executeQuery` and `toQueryResult`:
+
+```ts
+const clientRequestId = `KPC.rayfin_kusto_v1;${crypto.randomUUID()}`;
+
+const response = await client.connectors.telemetry.executeQuery({
+  query: 'StormEvents | summarize count() by State | top 10 by count_',
+  clientRequestId,
+});
+```
+
+Optionally normalize the raw Kusto v1 `{ Tables }` document into a discriminated result that preserves every returned Kusto table:
+
+```ts
+import { toQueryResult } from '@microsoft/rayfin-connector-kusto';
+
+const result = toQueryResult(response, { clientRequestId });
+if (result.status === 'success') {
+  renderTables(result.tables);
+} else {
+  showError(result.error.code, result.error.message);
+}
+```
+
+Successful results contain `tables` plus the `clientRequestId` you passed in (empty when you pass none) and an optional `activityId`; correlation is never on the wire.
+Each table contains named typed `columns` and row-major `rows`.
+Error results contain `error.message` and an optional `error.code`.
+
+### Management commands
+
+`executeCommand` runs a Kusto management (control) command — the command text starts with a leading dot.
+It returns the same native Kusto v1 `{ Tables }` document as `executeQuery`, so normalize it with `toQueryResult` the same way, and pass a matching `clientRequestId` to correlate end to end:
+
+```ts
+const clientRequestId = `KPC.rayfin_kusto_v1;${crypto.randomUUID()}`;
+
+const databases = await client.connectors.telemetry.executeCommand({
+  command: '.show databases',
+  clientRequestId,
+});
+
+const result = toQueryResult(databases, { clientRequestId });
+```
+
+## Calling a semantic model connector
+
+`executeQuery` on `fabric-semanticmodel` runs DAX and accepts an optional `resultSetRowCountLimit`.
+There is no default.
+Omit it and every row comes back, so ask the user for a bound rather than inventing one.
+
+Prefer it over wrapping the DAX in `TOPN` when the user wants a guard rather than a deliberately ranked subset.
+Exceeding it fails the query with an `'overflow'` error, so a truncated result announces itself, where a `TOPN` returns a complete-looking partial answer.
+
+Run `rayfin docs search "resultSetRowCountLimit"` for version-locked details, since this behavior is owned by the connector package rather than the CLI.
+
+## Exercising a Category B connector from the CLI
+
+`rayfin connector invoke <name> <operation>` is the loop for Category B.
+See [`connector invoke`](./invoke.md) for payload input, transports, token handling, and the output contract.
+
+- `connector inspect` supports `fabric-semanticmodel` but **not** `kusto` — a `kusto` connector errors with `Unsupported connector type: kusto`.
+  There is no ad-hoc query path for Kusto connectors today.
+- `connector invoke` on `fabric-semanticmodel` calls Fabric/Power BI directly under the developer's identity, so it works with or without `rayfin up`.
+  Every other type, `kusto` included, POSTs to the deployed item and requires a prior `rayfin up`.
+- `connector invoke` on `fabric-semanticmodel` returns an already-normalized result, because that connector normalizes inside its `invoke` middleware.
+  Do not apply `toQueryResult` to it again.
+- A resolved `connector invoke` call is not automatically a success.
+  A connector that normalizes reports failure as `status: 'error'`; one that returns the raw service envelope reports it as `status: 'Failed'`.
+  The CLI converts either into a non-zero exit.
+
+## Verify
+
+`rayfin dev` parses the `connectors:` block but does not wire Category B calls.
+A real `executeQuery` requires `rayfin up`.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `connector inspect` errors with `Unsupported connector type: kusto` | `connector inspect` has no Kusto path | Use `rayfin connector invoke <name> executeQuery` instead. |
+| `Cannot find module '@microsoft/rayfin-connector-kusto'` | `connector add` scaffolds but does not install | Run the pinned `npm install` command `connector add` printed; never install unversioned. |
+| The generated `schema.ts` has `queryServiceUri` / `databaseName` you did not expect | Expected — Kusto cluster routing is resolved at add time and baked in | Do not edit the file. Re-add the connector to re-resolve. |
+| `rayfin up` rejects `auth.type: application` | Category B connectors are delegated-only | Set `auth.type: delegated`. |
+| A Kusto query fails to reach the cluster, or the request carries no `queryServiceUri` | The runtime map was omitted, so nothing injected the generated routing | Pass `{ <name>: kusto() }` as the client's second constructor argument. |
+| A semantic-model `executeQuery` result cannot be read or decoded | `fabricSemanticModel()` was not registered, so the Arrow response is never decoded | Pass `{ <name>: fabricSemanticModel() }` as the client's second constructor argument. |
+| `client.connectors.<name>` is not typed | Connector key differs between `rayfin.yml`, `AppConnectorsSchema`, and the `connectors` option | Use the `rayfin.yml` `name` in all three. |
+| A Category B call works locally under `rayfin dev` | It does not — `rayfin dev` only parses the block | Deploy with `rayfin up` and retest. |

package/assets/docs/cli/connectors/index.md

@@ -6,14 +6,26 @@ sidebar_position: 6
 
 Connectors let a Rayfin app read from — and, for some types, write to — Microsoft Fabric data sources: warehouses, SQL databases, Lakehouse SQL analytics endpoints, semantic models, and KQL databases.
 
-## Prerequisite — the `connector` command group is feature-flagged
+## Prerequisite — enabling the `connector` command group
 
-`rayfin connector ...` is only registered when the `RAYFIN_FEATURE_FLAGS` environment variable contains `connectors`. Without it the commands do not exist and the CLI reports an unknown command.
+Connectors are behind a feature flag, so `rayfin connector ...` is only registered when the project opts in. Prefer the declarative setting in `rayfin/rayfin.yml`:
+
+```yaml
+services:
+  connectors:
+    enabled: true
+```
+
+With that setting present the command group is available from the very first `connector add`, with nothing to configure in the shell — the path generated apps and agents should use.
+
+The flag also activates automatically once `rayfin.yml` has a `connectors:` block (written by `connector add`), and it can still be turned on for a single command with the environment variable:
 
 ```bash
 RAYFIN_FEATURE_FLAGS=connectors npx rayfin connector search --help
 ```
 
+Without any of the three the commands do not exist and the CLI reports an unknown command.
+
 Each command has its own reference page:
 
 - [`connector search`](./search.md) — discover Fabric sources the signed-in identity can add.
@@ -21,6 +33,11 @@ Each command has its own reference page:
 - [`connector inspect`](./inspect.md) — run a single read-only sample query against a source.
 - [`connector invoke`](./invoke.md) — run one named operation against a configured connector.
 
+Each category has its own contract page — read the one that matches your connector type, not both:
+
+- [Category A — GraphQL entity connectors](./category-a-entities.md) — entity generation, `@role` policies, the aggregate schema, and the per-dialect read/write matrix.
+- [Category B — function-bridge connectors](./category-b-function-bridge.md) — the `kusto` and `fabric-semanticmodel` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
+
 A typical loop is search → add → inspect (Category A) or search → add → invoke (Category B).
 
 ## Two categories of connector

package/assets/docs/data/overview.md

@@ -55,7 +55,7 @@ If you omit it, the server generates a UUID automatically.
 
 **Scope:** the rules above apply to entities you own under `rayfin/data/`.
 Connector entities under `rayfin/connectors/` model an existing, external Fabric SQL source and follow different rules — the primary key is whatever the source actually declares, of any name and any datatype, including composite keys or no key at all.
-See the connector skill's [Entity Generation Contract](pathname://../../../../tools/cli/assets/agent-files/skills/rayfin-connectors/SKILL.md#entity-generation-contract) section for the connector-path key rules.
+See [Entity generation contract](../cli/connectors/category-a-entities.md#entity-generation-contract) for the connector-path key rules.
 
 ```typescript
 @entity()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.35.0-alpha.1412",
+  "version": "1.35.0-alpha.1541",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [