@microsoft/rayfin-guide 1.35.0-beta.0 → 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,672 +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 } 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`. |
+> **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

@@ -30,12 +30,12 @@ Each command has its own reference page:
 
 - [`connector search`](./search.md) — discover Fabric sources the signed-in identity can add.
 - [`connector add`](./add.md) — declare a connector in `rayfin.yml` and scaffold its files.
-- [`connector inspect`](./inspect.md) — run a single read-only sample query against a source.
+- [`connector inspect`](./inspect.md) — list a source's entity names, or run a single read-only sample query against one.
 - [`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 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).
@@ -44,16 +44,16 @@ A typical loop is search → add → inspect (Category A) or search → add →
 
 The commands available to a connector, and the code you write against it, depend on its category.
 
-|                                       | Category A — GraphQL entity connectors                          | Category B — function-bridge connectors                |
-| ------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
-| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase` | `kusto`, `fabric-semanticmodel`                        |
-| **App surface**                       | Generated entity files with typed CRUD through the data client  | A single `executeQuery` operation carrying a raw query |
+|                                       | Category A — GraphQL entity connectors                                                                                                                                           | Category B — function-bridge connectors                |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`                                                                                                                  | `kusto`, `fabric-semanticmodel`                        |
+| **App surface**                       | Generated entity files with typed CRUD through the data client                                                                                                                   | A single `executeQuery` operation carrying a raw query |
 | **Operations**                        | `read` only for `fabric-sqlanalytics` (Lakehouse SQL endpoints are read-only); `read`, `create`, `update`, `delete` for `fabric-warehouse` and `fabric-sqldatabase` (narrowable) | `executeQuery` only                                    |
-| **Auth**                              | `delegated` or configured per project                           | Must be `delegated`                                    |
-| **Entity files and `@role` policies** | Yes                                                             | No                                                     |
-| **`metadata.json` entities**          | Yes                                                             | No                                                     |
-| **`connector inspect`**               | Supported                                                       | `fabric-semanticmodel` only — `kusto` is not supported |
-| **`connector invoke`**                | Rarely needed                                                   | The main way to exercise the connector                 |
+| **Auth**                              | `delegated` or configured per project                                                                                                                                            | Must be `delegated`                                    |
+| **Entity files and `@role` policies** | Yes                                                                                                                                                                              | No                                                     |
+| **`metadata.json` entities**          | Yes                                                                                                                                                                              | No                                                     |
+| **`connector inspect`**               | Supported                                                                                                                                                                        | `fabric-semanticmodel` only — `kusto` is not supported |
+| **`connector invoke`**                | Rarely needed                                                                                                                                                                    | The main way to exercise the connector                 |
 
 Category B connectors are pinned to an adapter version and expose no GraphQL entities, so there is nothing to generate and no row-level security to author.
 

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

@@ -5,28 +5,43 @@ sidebar_position: 3
 # connector inspect
 
 ```bash
-npx rayfin connector inspect (--name <name> | <direct-selector-flags>) (--entity <name> | --query <path>) [--rows <n>] [--verbose] [--json]
+npx rayfin connector inspect (--name <name> | <direct-selector-flags>) [--entity <name> | --query <path>] [--rows <n>] [--verbose] [--json]
 ```
 
 `connector inspect` takes no positional arguments — every selector and query mode is a flag.
 
-`connector inspect` runs a single read-only sample query against a connector's underlying source, before you have written any app code. Use it to check a table's real data and shape ahead of entity generation, or to debug a row-level-security or query issue on an already-wired connector. It is a development aid — never use it to power app functionality.
+`connector inspect` explores a connector's underlying source in read-only mode, before you have written any app code. Run it with just a selector to **list the entity/table names** the source exposes; add `--entity` to sample one of them, or `--query` to run a `.sql`/`.dax` file of your own. Use it to check a table's real data and shape ahead of entity generation, or to debug a row-level-security or query issue on an already-wired connector. It is a development aid — never use it to power app functionality.
 
 Supported types: the three Category A SQL types (`fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`) and `fabric-semanticmodel` (DAX). `kusto` is **not** supported today — the command errors with `Unsupported connector type: kusto`.
 
-## Pick exactly one selector and one query mode
+## Pick exactly one selector, and at most one query mode
 
-Two independent choices, each a mutually exclusive pair. Passing zero or both options in a pair fails validation before any network call.
+Two independent choices. The **selector** is a mutually exclusive pair — passing zero or both fails validation before any network call. The **query mode** has three options, and omitting it is a mode of its own rather than an error; only passing `--entity` and `--query` together fails.
 
-| Choice                                          | Option A                                                                                                                      | Option B                                                                                                                                                                                       |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Selector** — which connector or item to query | `--name <name>` — a connector already declared in `rayfin.yml`                                                                | Direct mode — `--workspace-id`/`--workspace <name>` plus `--item-id`/`--item <name>` plus `--type <type>`, or `--url <portal-url>` for a semantic model (auto-extracts workspace and item IDs) |
-| **Query mode**                                  | `--entity <name>` — structured: builds `SELECT TOP (n) * FROM <entity>` (SQL) or `EVALUATE TOPN(n, '<entity>')` (DAX) for you | `--query <path>` — raw: runs the literal `.sql` or `.dax` file verbatim, still capped and validated                                                                                            |
+| Selector — which connector or item to query | Meaning                                                                                                                                                                           |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`                             | A connector already declared in `rayfin.yml`.                                                                                                                                     |
+| Direct mode                                 | `--workspace-id`/`--workspace <name>` plus `--item-id`/`--item <name>` plus `--type <type>`, or `--url <portal-url>` for a semantic model (auto-extracts workspace and item IDs). |
 
-All four combinations of `{--name, direct} × {--entity, --query}` are valid.
+| Query mode                     | What it runs                                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| _omit both_ — entity listing   | Lists the entity/table names the source exposes, so you have something to pass to `--entity`. This is the default. |
+| `--entity <name>` — structured | Builds `SELECT TOP (n) * FROM <entity>` (SQL) or `EVALUATE TOPN(n, '<entity>')` (DAX) for you.                     |
+| `--query <path>` — raw         | Runs the literal `.sql` or `.dax` file verbatim, still capped and validated.                                       |
+
+All six combinations of `{--name, direct} × {listing, --entity, --query}` are valid.
 
 `--workspace` and `--item` accept display names and are resolved to IDs the same way [`connector add`](./add.md) fuzzy matching works; `--workspace-id` and `--item-id` take literal IDs directly.
 
+## Entity listing
+
+Omitting both `--entity` and `--query` lists the entity names available on the source. This is the starting point when you don't know the names yet — the output is what you feed back into `--entity`, and the command prints a ready-to-run `--entity` suggestion carrying the same selector flags you just used.
+
+- **SQL types** — reads `INFORMATION_SCHEMA.TABLES`, returning `TABLE_SCHEMA` and `TABLE_NAME`.
+- **`fabric-semanticmodel`** — reads `INFO.TABLES()`, returning table names.
+
+Listing honours `--rows` and `--json` like any other mode, and the `--json` envelope reports `queryMode: "entities"`.
+
 ## Entity resolution
 
 Applies to `--entity` mode only.
@@ -37,22 +52,28 @@ Applies to `--entity` mode only.
 
 ## Validation
 
-Applies to both query modes.
+Applies to `--entity` and `--query` modes.
 
 - **SQL** — must start with `SELECT` or `WITH`; must be a single statement (a trailing `;` is fine, an embedded one is not); rejects `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `EXEC`/`EXECUTE`, and `INTO` anywhere outside a string literal.
 - **DAX** — must start with `EVALUATE`.
 - `--query <path>` must resolve to a `.sql` or `.dax` file inside the project root; paths outside it are rejected. The project root is the directory containing `rayfin/rayfin.yml` when one is found. Direct mode (no `--name`) falls back to the current working directory if no `rayfin.yml` exists, so `--query` never requires a Rayfin project.
-- `--rows <n>` caps the sample size — default 10, maximum 100. The result reports `truncated: true` when the source had more rows than the cap.
+- `--rows <n>` caps the sample size — maximum 100. The default is mode-specific: entity listing (neither `--entity` nor `--query`) defaults to **100**, while `--entity` and `--query` sampling default to **10**. The result reports `truncated: true` when the source had more rows than the cap; inspect fetches one row beyond the cap to detect that, then discards it.
 
 ## Examples
 
 ```bash
+# --name selector, no query mode: list the entity names on the source
+npx rayfin connector inspect --name inventory
+
 # --name selector + structured entity mode
 npx rayfin connector inspect --name inventory --entity Order
 
 # --name selector + raw query file
 npx rayfin connector inspect --name inventory --query rayfin/queries/order.sql
 
+# Direct selector, no query mode: list the entity names on the source
+npx rayfin connector inspect --workspace-id <ws-id> --item-id <item-id> --type fabric-warehouse
+
 # Direct selector (literal IDs) + structured entity mode
 npx rayfin connector inspect --workspace-id <ws-id> --item-id <item-id> --type fabric-warehouse --entity Order
 
@@ -63,7 +84,7 @@ npx rayfin connector inspect --workspace "Sales Analytics" --item "Inventory War
 npx rayfin connector inspect --url <fabric-portal-semantic-model-url> --query rayfin/queries/model.dax
 ```
 
-Combine `--workspace-id`, `--item-id`, and `--type` with either `--entity` or `--query` freely — none of the four combinations require `--name` or a `rayfin.yml` entry to exist.
+Combine `--workspace-id`, `--item-id`, and `--type` with entity listing, `--entity`, or `--query` freely — none of the six combinations require `--name` or a `rayfin.yml` entry to exist.
 
 ## Errors
 

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

@@ -78,6 +78,8 @@ services:
   data:
     enabled: true
     dialect: mssql
+  storage:
+    enabled: false
   staticHosting:
     enabled: true
     root: .
@@ -158,6 +160,12 @@ Configure an email provider for magic links, password resets, and email verifica
 | `useStartTls` | `boolean` | `false` | Use STARTTLS for the SMTP connection. |
 | `webPort` | `number` | `1080` | MailDev web UI port (local development only). |
 
+#### `services.storage`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable the storage service. |
+
 #### `services.staticHosting`
 
 | Field | Type | Default | Description |

package/assets/docs/hosting/index.md

@@ -38,6 +38,24 @@ services:
 | `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`). |
 
+### Declared package versions
+
+Every `rayfin up` records which packages produced the deployment, under `packageVersions` in the runtime settings it uploads:
+
+| Key | When it is sent |
+| --- | --- |
+| `@microsoft/rayfin-cli` | Always, set to the running CLI's version. |
+| `@microsoft/rayfin-auth` | When your frontend package has the auth SDK installed, set to the installed version. |
+
+You do not author this.
+Run `rayfin up --dry-run` to see exactly which versions a deploy would declare, without deploying.
+
+Once your tenant enforces static-hosting access control, a CLI too old to record its version cannot deploy a static-hosted app, and the deployment is rejected with instructions to upgrade:
+
+```bash
+npm install -g @microsoft/rayfin-cli@latest
+```
+
 ### Example with a separate frontend directory
 
 If your frontend lives in a subdirectory:
@@ -133,7 +151,7 @@ The deploy tool updates the configuration and pushes it to the backend during de
 
 - The compressed ZIP archive must not exceed **100 MB**.
 - The CLI uses maximum compression to minimize upload size.
-- If your build output exceeds the limit, consider excluding large assets from the deployed bundle.
+- If your build output exceeds the limit, consider excluding large assets or using the storage service for binary files.
 
 ## Complete example
 
@@ -182,6 +200,7 @@ If the ZIP exceeds 100 MB:
 
 - Review your build output for unnecessary files (source maps, unoptimized images).
 - Configure your bundler to exclude development artifacts from the production build.
+- Move large binary assets to Rayfin storage instead of bundling them as static content.
 
 ### No remote endpoint configured
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.35.0-beta.0",
+  "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": [