@microsoft/rayfin-guide 1.36.0-alpha.1581 → 1.36.0-alpha.1588

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

@@ -91,12 +91,56 @@ With `--json`, the same information is available under `install`:
 }
 ```
 
+## Re-adding an existing connector
+
+Running `connector add` against a name already in `rayfin.yml` refreshes the declaration.
+It prompts before overwriting, or requires `--yes` when non-interactive.
+
+Your generated entity files under `rayfin/connectors/<name>/` are **preserved**.
+Only `metadata.json` is rewritten, by schema discovery.
+The hand-authored aggregate `schema.ts` is preserved too, unless you pass `--yes` — which opts in to overwriting it with a fresh placeholder.
+
+To start from a clean directory instead, use [`connector remove`](#related-commands) first.
+
+## When schema discovery fails
+
+Schema discovery is best-effort.
+If it fails, the connector is still written to `rayfin.yml` and the command still exits `0` — you can retry discovery later by re-running `connector add`.
+
+The failure is reported as a warning with a recovery hint, and under `--json` as a `schemaDiscovery` object:
+
+```json
+{
+  "status": "success",
+  "action": "connector.add",
+  "schemaDiscovery": {
+    "status": "failed",
+    "reason": "login",
+    "error": "The data source rejected the login for connector \"inventory\". ...",
+    "recovery": "Confirm your account has read access to item <id> in workspace <id> — that is the usual cause. If it does, run `rayfin login` to refresh your session and retry."
+  }
+}
+```
+
+`schemaDiscovery` is present only for Category A connectors, which are the only ones that run discovery.
+Top-level `status` stays `success` because the connector was added; check `schemaDiscovery.status` to branch on discovery specifically.
+
+| `reason` | Meaning |
+| --- | --- |
+| `permission` | The data source explicitly denied the read. Someone must grant your account access. |
+| `login` | The login was rejected without saying why. Usually missing access to the item; occasionally a stale CLI session. |
+| `auth` | The control plane rejected your token. Run `rayfin login`. |
+| `unknown` | Anything else — the raw driver message is in `error`. |
+
 ## Related commands
 
 ```bash
-npx rayfin connector list [--verbose] [--json]
+npx rayfin connector list --json
+npx rayfin connector list --verbose
 
-# Removes the rayfin.yml entry AND the rayfin/connectors/<name>/ directory.
-# Re-add after remove to refresh metadata, then regenerate entity files yourself.
+# Removes the rayfin.yml entry AND the rayfin/connectors/<name>/ directory,
+# including any entity files you generated.
 npx rayfin connector remove <name> [--yes]
 ```
+
+`--json` and `--verbose` are mutually exclusive and cannot be combined.

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

@@ -4,670 +4,18 @@ 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, 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`.
-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`.
-- If any column is server-generated, also add `import type { AutoGenerated } from '@microsoft/rayfin-core';`.
-- 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';
-import type { AutoGenerated } from '@microsoft/rayfin-core';
-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, for example `productId`, not `ProductID`. |
+> **Moved.** This reference now ships **inside the connector package**,
+> version-locked to the connector the Builder actually installed — so per-dialect
+> read/write behavior, SQL-type mappings, and composite-PK semantics can never
+> drift from the CLI. It is fetched on demand with `packageVersion` provenance.
+>
+> Read it from `@microsoft/rayfin-connector-fabric-graphql`:
+>
+> - MCP: `search_docs` / `discover_packages`
+> - CLI: `rayfin docs search "<term>"` (module `rayfin-connector-fabric-graphql`)
+> - Source: `@microsoft/rayfin-connector-fabric-graphql/assets/docs/`
+>
+> Pages: `index.md` (generation workflow, the aggregate `schema.ts`, client
+> wiring, worked example), `entities.md` (`@role` row-level policies, the entity
+> generation contract, the `metadata.json` reference), `querying.md`,
+> `mutations.md`, and `troubleshooting.md`.

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

@@ -11,7 +11,7 @@ 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.
+For the entity-generating types (`fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`), read the package-owned Category A docs in `@microsoft/rayfin-connector-fabric-graphql` (`rayfin docs search` / `search_docs`) instead.
 
 ## What each type exposes
 

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

@@ -35,7 +35,7 @@ Each command has its own reference page:
 
 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 A — GraphQL entity connectors](./category-a-entities.md) — now **package-owned**; the full reference (entity generation, `@role` policies, the aggregate schema, and the per-dialect read/write matrix) ships in `@microsoft/rayfin-connector-fabric-graphql` (`rayfin docs search` / `search_docs`).
 - [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).

package/assets/docs/getting-started/project-structure.md

@@ -175,10 +175,6 @@ Configure an email provider for magic links, password resets, and email verifica
 | `folder` | `string` | `"dist"` | Directory containing built static assets (relative to `root`). |
 | `buildCommand` | `string` | — | Shell command to run before packaging (e.g. `npm run build`). |
 | `indexDocument` | `string` | — | Default document served for the root path (e.g. `index.html`). |
-| `anonymousAccess` | `boolean` | — | Whether visitors can open the app without signing in. Required when static hosting is enabled. |
-
-`anonymousAccess` has no default.
-See [Static hosting](../hosting/index.md) for the posture table.
 
 > **Tip:** All string values support environment variable interpolation with `${VAR}` and `${VAR:-default}` syntax.
 > Variables are resolved from `rayfin/.env` and the shell environment.

package/assets/docs/hosting/index.md

@@ -37,36 +37,6 @@ services:
 | `root` | No | Project root | Root directory of the frontend project, relative to the project root. |
 | `buildCommand` | No | — | Shell command to run before packaging (for example, `npm run build`). |
 | `indexDocument` | No | — | Default document to serve for directory requests (for example, `index.html`). |
-| `anonymousAccess` | Yes | — | Whether visitors can open the app without signing in. |
-
-### Access posture
-
-`anonymousAccess` selects who can open your deployed app.
-Set `anonymousAccess` explicitly — leaving it out is not the same as setting it to `false`, and once your tenant enforces static-hosting access control a deployment that omits `anonymousAccess` is rejected.
-
-| Posture | `anonymousAccess` | Who can open the app |
-| --- | --- | --- |
-| Signed-in users only | `false` | Visitors must sign in. |
-| Public | `true` | Anyone with the link, no sign-in. |
-
-```yaml
-services:
-  staticHosting:
-    enabled: true
-    folder: dist
-    anonymousAccess: false
-```
-
-`rayfin up` asks you to choose a posture the first time it deploys a project that has not recorded one, then writes your choice to `rayfin.yml` so later deploys never ask again.
-In automation — `--yes`, a non-interactive terminal, or `CI=true` — it never prompts: add `anonymousAccess` to `rayfin.yml` and re-run.
-`anonymousAccess` must be `true` or `false`; a value that is neither, such as an environment variable that did not resolve, is rejected before anything is deployed.
-
-A newly scaffolded project already has `anonymousAccess: false`, so it is private from the moment it exists and deploys without a prompt.
-The prompt exists for projects created before this property did: those apps are being served publicly today, so `rayfin up` asks once and never guesses on your behalf.
-Choosing public does not turn off Rayfin auth — it decides who may load the site, not whether the app can sign users in.
-
-`rayfin up staticapp deploy` does not set an access posture.
-It publishes content only, so the app keeps whatever posture the last full `rayfin up` recorded.
 
 ### Declared package versions
 

package/package.json

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