@microsoft/rayfin-guide 1.36.0-alpha.1756 → 1.36.0-alpha.1917

package/assets/docs/app-backend/deploy.md

@@ -62,6 +62,41 @@ npx rayfin up
 
 If you are not signed in, the CLI launches an interactive login flow automatically.
 
+### Prepare Fabric capacity
+
+Before creating the Rayfin item, `rayfin up` checks whether the target workspace already has Fabric capacity.
+If the workspace reports an assigned capacity, Rayfin uses it without changing or reevaluating the assignment.
+
+On a first interactive deployment without a workspace target or `--capacity-id`, Rayfin asks you to choose:
+
+1. `Use new workspace [Recommended]` runs workspace and capacity readiness.
+2. `Select existing workspace` skips capacity readiness and opens the accessible-workspace picker.
+
+Explicit workspace options and recorded deployments continue directly to their existing targeting flow without showing this choice.
+Dry-run invocations do not show the choice.
+An interactive invocation with `--capacity-id <id>` automatically prepares a new workspace and assigns that capacity without showing the workspace choice.
+An untargeted non-interactive invocation automatically prepares a new workspace without prompting.
+Pass `--capacity-id <id>` to use a specific capacity for that new workspace.
+Pass an existing workspace target to deploy there instead.
+
+When the workspace needs capacity, an interactive deployment asks for confirmation before assigning the selected or trial capacity.
+Pass `--yes` to approve a deterministic capacity assignment without the prompt:
+
+```bash
+npx rayfin up --yes
+```
+
+To select a specific existing capacity, pass its Fabric capacity ID.
+This explicitly approves assigning that capacity:
+
+```bash
+npx rayfin up --capacity-id <capacity-guid>
+```
+
+Do not combine `--capacity-id` with `--workspace`, `--workspace-id`, or `--workspace-uri`.
+If multiple premium capacities are available, select one explicitly with `--capacity-id`.
+An existing recorded deployment keeps its current workspace capacity and ignores a newly supplied capacity ID.
+
 ### Choose a unique Fabric item name
 
 By default, `rayfin up` uses the project ID from `rayfin.yml` as the Fabric item name.
@@ -84,7 +119,7 @@ npx rayfin up \
   --output json
 ```
 
-Do not pass `--yes` unless reusing an existing same-named item is intentional.
+The `--yes` option also approves reuse of an existing same-named item, so use it only when both automatic capacity assignment and item reuse are acceptable.
 
 ### What `rayfin up` does
 

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

@@ -5,10 +5,14 @@ sidebar_position: 2
 # connector add
 
 ```bash
-npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id> [--name <name>] [--operations <ops>]
+npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id> [--name <name>] [--operations <ops>] [--auth <type>]
 ```
 
 > **`kusto` authoring is held in this release**, so `connector add --type kusto` refuses before writing anything. Kusto examples below describe the authoring path for when it ships. See [Connectors](./index.md) for what a project that already declares Kusto can still do.
+>
+> **`fabric-dataagent` authoring is held in this release** too.
+> `connector add --type fabric-dataagent` refuses before writing a YAML entry or scaffold directory, even with `--yes` or `--operations`.
+> The connector remains experimental; its existing configuration and runtime contract are preserved.
 
 `connector add` declares a connector in `rayfin/rayfin.yml` and scaffolds its supporting files.
 
@@ -25,9 +29,19 @@ If you do not already know the workspace and item IDs, run [`connector search`](
 | `--item-id <id>`      | yes (Fabric) | Fabric item or artifact ID. Must be a literal.                                                                                                                                                                          |
 | `--name <name>`       | no           | Connector name. Derived from the item display name when omitted.                                                                                                                                                        |
 | `--operations <ops>`  | no           | Comma-separated subset of the type's allowed operations, for example `read,update`. Narrows the emitted `operations:` at add time. Omit for all allowed operations. Each value must be in the type's catalog allowlist. |
+| `--auth <type>`       | no           | Identity each call runs as: `delegated` (the signed-in caller) or `application` (the app owner). Omit to use the connector type's catalog default. Must be in the type's allowed auth types.                            |
 | `-y, --yes`           | no           | Auto-accept overwrite and confirmation prompts (non-interactive).                                                                                                                                                       |
 | `-v, --verbose`       | no           | Verbose diagnostics.                                                                                                                                                                                                    |
 
+## Authentication
+
+`connector add` writes `auth.type: application` for Category A connectors: `fabric-sqlanalytics`, `fabric-warehouse`, and `fabric-sqldatabase`.
+The connector accesses the data source with the app's identity rather than the signed-in end user's identity.
+For per-user data-source access, explicitly set `auth.type: delegated` in `rayfin.yml` before deploying.
+
+Category B connectors continue to require `auth.type: delegated`.
+Existing declarations are not migrated, and omitting `auth.type` remains a validation error.
+
 ## Scoping operations
 
 Without `--operations`, `connector add` writes **every** operation the catalog allows for the type. Prefer scoping at add time over hand-editing YAML afterwards:
@@ -46,7 +60,7 @@ connectors:
       workspaceId: ${WS_ID}
       itemId: ${ITEM_ID}
     auth:
-      type: delegated
+      type: application
     operations:
       - name: read
       - name: update
@@ -63,7 +77,7 @@ Rules:
 For `kusto` and `fabric-semanticmodel`, `connector add` writes the `rayfin.yml` entry and generates a complete typed `schema.ts`, but there are no GraphQL entities to discover, so no entity files are generated and no row-level security applies:
 
 - `fabric-semanticmodel` allows `executeQuery`; `kusto` allows `executeQuery` and `executeCommand`. Check `rayfin connector types --json` for the current set.
-- `auth.type` must be `delegated`.
+- `auth.type` is `delegated` for `fabric-semanticmodel` and `application` for `kusto` — see [Category B](./category-b-function-bridge.md). Set it with `--auth`.
 - The connector is pinned to an adapter version.
 - There is no `metadata.json` entity list to generate from.
 
@@ -97,6 +111,7 @@ With `--json`, the same information is available under `install`:
 
 Running `connector add` against a name already in `rayfin.yml` refreshes the declaration.
 It prompts before overwriting, or requires `--yes` when non-interactive.
+This rewrites `auth.type` to the catalog default, so reapply an explicit `delegated` setting for a Category A connector after re-adding it if needed.
 
 Your generated entity files under `rayfin/connectors/<name>/` are **preserved**.
 Only `metadata.json` is rewritten, by schema discovery.

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

@@ -4,15 +4,20 @@ sidebar_position: 6
 
 # Category B — function-bridge connectors
 
-Reference for `fabric-semanticmodel` (Power BI semantic model) and the experimental `kusto` (the **Eventhouse** connector — a Fabric Eventhouse KQL Database).
+Reference for `fabric-semanticmodel` (Power BI semantic model), the experimental `fabric-dataagent` (Fabric Data Agent), and the experimental `kusto` (the **Eventhouse** connector — a Fabric Eventhouse KQL Database).
 Eventhouse is the Fabric product name; `kusto` is the type id you pass to `--type`, and KQL is its query language.
 
 > **`kusto` authoring is held in this release**, so `connector add --type kusto` refuses and search omits KQL databases. Everything below about `kusto` stays accurate for a project that **already declares** one — which still validates, deploys and invokes — and describes the authoring path for when it ships. Only `fabric-semanticmodel` can be added today. See [Connectors](./index.md).
+>
+> **`fabric-dataagent` authoring is held in this release**, and the connector remains experimental, not generally available.
+> `connector add --type fabric-dataagent` refuses before writing files; `connector types` and `connector search` omit it.
+> Data Agent examples describe the contract for existing configurations and the authoring path for when it is released, not an available setup flow.
+> The hold does not disable existing validation, deployment, or invocation paths; live use still requires the backend adapter.
 
 A Category B connector is a named-operation surface backed by a small, platform-owned function (UDF).
 The Builder never writes or sees the function code.
 
-The Builder declares the connector and calls a typed method; the Fabric app backend injects connector configuration and delegated authentication before forwarding to the function.
+The Builder declares the connector and calls a typed method; the Fabric app backend injects connector configuration and 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 the package-owned Category A docs in `@microsoft/rayfin-connector-fabric-graphql` (`rayfin docs search` / `search_docs`) instead.
@@ -22,10 +27,17 @@ For the entity-generating types (`fabric-sqlanalytics`, `fabric-warehouse`, `fab
 | Type | Operations | Query language | Auth |
 | --- | --- | --- | --- |
 | `fabric-semanticmodel` | `executeQuery` | DAX | `delegated` only |
-| `kusto` (**experimental**) | `executeQuery`, `executeCommand` | KQL | `delegated` only |
+| `kusto` (**experimental**) | `executeQuery`, `executeCommand` | KQL | `application` only |
+| `fabric-dataagent` (**experimental**) | `getInfo`, `startTask`, `getTask`, `getTaskResult`, `cancelTask` | Natural language (MCP) | `delegated` only |
 
-Both are pinned to an adapter version (`version: '1'` today).
-Delegated authentication runs every call as the signed-in user through the on-behalf-of flow.
+All three are pinned to an adapter version (`version: '1'` today).
+`delegated` runs every call as the signed-in user through the on-behalf-of flow; `application` runs it as the app owner.
+
+Kusto's adapter authorizes as the app owner and rejects a delegated caller token, so it takes `application` only — `auth.type: delegated` is refused at validation rather than failing at the data plane. Row-level security is therefore evaluated against the owner, not the caller.
+
+The experimental `fabric-dataagent` SDK package also provides an `ask` helper.
+`ask` is a client-side convenience composed from the task operations, not a connector operation, so it never appears in `rayfin.yml`.
+See [Calling a Data Agent connector](#calling-a-data-agent-connector).
 
 ## Add the connector
 
@@ -37,7 +49,7 @@ rayfin connector add \
   --name telemetry
 ```
 
-`--item-id` identifies the Fabric item to query: a KQL Database for `kusto`, a semantic model for `fabric-semanticmodel`.
+`--item-id` identifies the Fabric item to query: a KQL Database for `kusto`, a semantic model for `fabric-semanticmodel`, a published Data Agent for experimental `fabric-dataagent`.
 Omit `--name` to derive the connector name from the Fabric item's display name.
 
 The CLI verifies the item, writes the `rayfin.yml` entry, and scaffolds `rayfin/connectors/<name>/schema.ts`.
@@ -53,21 +65,22 @@ connectors:
       workspaceId: <ws-id>
       itemId: <kql-database-item-id>
     auth:
-      type: delegated
+      type: application
     operations:
       - name: executeQuery
       - name: executeCommand
 ```
 
 The `config` block is the single source of truth for what to query and is not sent on the client wire.
-`kusto` allows `executeQuery` and `executeCommand`; `fabric-semanticmodel` allows `executeQuery`.
-In every case `auth.type` must be `delegated`.
+`kusto` allows `executeQuery` and `executeCommand`; `fabric-semanticmodel` allows `executeQuery`; experimental `fabric-dataagent` allows `getInfo`, `startTask`, `getTask`, `getTaskResult` and `cancelTask`.
+`auth.type` is `application` for `kusto` and `delegated` for the other two.
 
 ## The generated schema.ts
 
 `connector add` writes `rayfin/connectors/<name>/schema.ts` with a `// @generated — do not edit.` banner.
 Do not hand-edit it.
-Regenerate it by removing and re-adding the connector (`rayfin connector remove <name>`, then `rayfin connector add ...`).
+For released types, regenerate it by removing and re-adding the connector (`rayfin connector remove <name>`, then `rayfin connector add ...`).
+Do not remove a held connector to regenerate its files: `connector add` will refuse to recreate it.
 
 For `fabric-semanticmodel` the file exports the typed marker plus a generic runtime config:
 
@@ -110,6 +123,19 @@ If the resolved values look wrong, re-add the connector rather than editing the
 
 The Eventhouse scaffold imports both its marker and `KustoConnectorConfig` from `@microsoft/rayfin-connector-kusto`, so it does not import `@microsoft/rayfin-connectors` at all.
 
+### The experimental Data Agent scaffold uses the generic config shape
+
+Experimental `fabric-dataagent` needs no client-side routing values.
+An existing `schema.ts` uses the generic `ConnectorConfig` shape shown for semantic models above, and a marker whose type argument is the operations declared in `rayfin.yml`:
+
+```ts
+import type { FabricDataAgent } from '@microsoft/rayfin-connector-fabric-dataagent';
+
+export type SalesAgentSchema = FabricDataAgent<'getInfo' | 'startTask' | 'getTask' | 'getTaskResult' | 'cancelTask'>;
+```
+
+The AppBackend resolves the workspace and Data Agent item from `rayfin.yml`; app code and `fabricDataAgent()` never supply an MCP endpoint.
+
 ## Install the packages the generated file imports
 
 `connector add` scaffolds files but installs nothing. It prints the exact pinned command — copy it from that output, or rebuild it from the `packages` array in `rayfin connector types --json`, which carries both the package names and the version:
@@ -122,6 +148,9 @@ npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha
 
 # fabric-semanticmodel
 npm install @microsoft/rayfin-connector-fabric-semanticmodel@1.35.0-alpha @microsoft/rayfin-connectors@1.35.0-alpha
+
+# fabric-dataagent (experimental, authoring held) — existing configurations only
+npm install @microsoft/rayfin-connector-fabric-dataagent@1.35.0-alpha @microsoft/rayfin-connectors@1.35.0-alpha
 ```
 
 **Always pin the version.** Connector packages ship in lockstep with the CLI, but their npm `latest` and `preview` tags lag behind, so an unversioned install pulls an older release and its own mismatched `@microsoft/rayfin-data`.
@@ -136,6 +165,7 @@ This is not optional: the runtime is what injects the generated routing and deco
 
 - `kusto()` merges the generated `queryServiceUri` and `databaseName` into the outbound payload. Without it, `executeQuery` and `executeCommand` cannot route to the cluster.
 - `fabricSemanticModel()` decodes the Arrow response. Without it, `executeQuery` results cannot be read.
+- `fabricDataAgent()` (experimental) normalizes each operation's result and supplies the client-side `ask` helper. Without it, results arrive as raw, un-normalized payloads and `client.connectors.<name>.ask(...)` is posted to the host as an operation it does not know.
 
 Key the runtime map by the same connector name, and call the factory once per connector:
 
@@ -261,6 +291,69 @@ Exceeding it fails the query with an `'overflow'` error, so a truncated result a
 
 Run `rayfin docs search "resultSetRowCountLimit"` for version-locked details, since this behavior is owned by the connector package rather than the CLI.
 
+## Calling a Data Agent connector
+
+> **Experimental; new authoring is held.**
+> The API below describes an already-configured connector, not a currently available `connector add` flow.
+> It may change substantially in a future release.
+
+A Data Agent answers natural-language questions over the data sources its publisher configured.
+Questions can take minutes, so the Data Agent MCP endpoint runs them as tasks.
+The connector exposes that lifecycle as named operations — `startTask`, `getTask`, `getTaskResult`, `cancelTask` — plus `getInfo` for the agent's metadata.
+
+Use the `ask` helper for the common case.
+`ask` is a client-side convenience, not a connector operation: it calls `startTask`, polls `getTask` while reporting progress, honours cancellation, applies an overall deadline (5 minutes by default), and returns `getTaskResult`.
+It is only typed on `client.connectors.<name>` when the connector allows `startTask`, `getTask`, `getTaskResult` and `cancelTask`.
+
+```ts
+import { FabricDataAgentError } from '@microsoft/rayfin-connector-fabric-dataagent';
+
+const controller = new AbortController();
+
+try {
+  const answer = await client.connectors.salesAgent.ask({
+    question: 'What were sales by region last quarter?',
+    onProgress: (p) => setStatus(p.statusMessage ?? p.status),
+    signal: controller.signal,
+  });
+  render(answer.text);
+  if (answer.deepLinkUrl) showLink('Open in Data Agent', answer.deepLinkUrl);
+} catch (err) {
+  if (err instanceof FabricDataAgentError && err.code === 'DATA_AGENT_FORBIDDEN') {
+    showAccessRequest();
+  } else {
+    throw err;
+  }
+}
+```
+
+`answer.text` joins the text blocks; `answer.content`, `answer.structuredContent`, and `answer.meta` preserve everything the server returned.
+`onProgress` and `signal` never leave the browser — the SDK consumes them.
+
+Read the agent's name, description, and tool contract with `getInfo()`; the result is cached per client for five minutes.
+
+Call the task operations directly when the app needs to own the task lifecycle, for example to resume polling after a page reload:
+
+```ts
+const started = await client.connectors.salesAgent.startTask({ question });
+if (started.kind === 'answer') {
+  render(started.answer.text);
+} else {
+  const { taskId } = started.task;
+  // Persist taskId, then later:
+  const status = await client.connectors.salesAgent.getTask({ taskId });
+  if (status.status === 'completed') {
+    const answer = await client.connectors.salesAgent.getTaskResult({ taskId });
+    render(answer.text);
+  }
+}
+```
+
+Every operation throws `FabricDataAgentError` with a stable `code` (`DATA_AGENT_FORBIDDEN`, `DATA_AGENT_NOT_PUBLISHED`, `DATA_AGENT_TIMEOUT`, `DATA_AGENT_THROTTLED`, ...), a `retryable` flag, a `category` of `user` or `system`, and a `correlationId` when the service supplied one.
+
+The endpoint is stateless.
+To give the agent context from earlier turns, pass them in `history`; the app owns any persisted chat transcript.
+
 ## Exercising a Category B connector from the CLI
 
 `rayfin connector invoke <name> <operation>` is the loop for Category B.
@@ -268,6 +361,9 @@ See [`connector invoke`](./invoke.md) for payload input, transports, token handl
 
 - `connector inspect` supports `fabric-semanticmodel` but **not** experimental `kusto` — a `kusto` connector errors with `Unsupported connector type: kusto`.
   There is no ad-hoc query path for Kusto connectors today.
+- `connector inspect` does not support experimental `fabric-dataagent` either.
+  Use `rayfin connector invoke <name> getInfo` to read the agent's metadata.
+  `connector invoke` accepts the connector's named operations only; `ask` is a client-side SDK helper, so it is not an operation `invoke` can call.
 - `connector invoke` on `fabric-semanticmodel` calls Fabric/Power BI directly under the developer's identity, so it works with or without `rayfin up`.
   Every other type, including experimental `kusto`, POSTs to the deployed item and requires a prior `rayfin up`.
 - `connector invoke` on `fabric-semanticmodel` returns an already-normalized result, because that connector normalizes inside its `invoke` middleware.
@@ -288,8 +384,12 @@ A real `executeQuery` requires `rayfin up`.
 | `connector inspect` errors with `Unsupported connector type: kusto` | `connector inspect` has no Kusto path | Use `rayfin connector invoke <name> executeQuery` instead. |
 | `Cannot find module '@microsoft/rayfin-connector-kusto'` | `connector add` scaffolds but does not install | Run the pinned `npm install` command `connector add` printed; never install unversioned. |
 | The generated `schema.ts` has `queryServiceUri` / `databaseName` you did not expect | Expected — Kusto cluster routing is resolved at add time and baked in | Do not edit the file. Re-add the connector to re-resolve. |
-| `rayfin up` rejects `auth.type: application` | Category B connectors are delegated-only | Set `auth.type: delegated`. |
+| `rayfin up` rejects `auth.type: application` on `fabric-semanticmodel` | `fabric-semanticmodel` is delegated-only | Set `auth.type: delegated`. |
+| A Kusto query returns the app owner's data instead of the caller's | Kusto is application-only, so the call runs as the owner and row-level security is evaluated against them | Expected. Enforce per-user access in your app. |
 | A Kusto query fails to reach the cluster, or the request carries no `queryServiceUri` | The runtime map was omitted, so nothing injected the generated routing | Pass `{ <name>: kusto() }` as the client's second constructor argument. |
 | A semantic-model `executeQuery` result cannot be read or decoded | `fabricSemanticModel()` was not registered, so the Arrow response is never decoded | Pass `{ <name>: fabricSemanticModel() }` as the client's second constructor argument. |
+| `client.connectors.<name>.ask` is not typed on an experimental `fabric-dataagent` connector | The connector does not allow every operation `ask` is composed from | Allow `startTask`, `getTask`, `getTaskResult` and `cancelTask` in `rayfin.yml`, and list them in the generated marker's type argument. |
+| `client.connectors.<name>.ask` fails with an unknown or unsupported operation | `fabricDataAgent()` was not registered, so `ask` was posted to the host instead of being composed client-side | Pass `{ <name>: fabricDataAgent() }` as the client's second constructor argument. |
+| `ask` throws `DATA_AGENT_NOT_PUBLISHED` | The Data Agent has a draft but no published configuration | Publish the Data Agent in Fabric, then retry. |
 | `client.connectors.<name>` is not typed | Connector key differs between `rayfin.yml`, `AppConnectorsSchema`, and the `connectors` option | Use the `rayfin.yml` `name` in all three. |
 | A Category B call works locally under `rayfin dev` | It does not — `rayfin dev` only parses the block | Deploy with `rayfin up` and retest. |

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

@@ -13,6 +13,10 @@ It can read SQL-visible tables and views, but it cannot directly open files from
 This connector is read-only; the Warehouse and SQL Database connectors also support write operations.
 
 > **`kusto` authoring is held in this release.** `connector types` and `connector search` omit it, and `connector add --type kusto` refuses it. A project that **already declares** a Kusto connector is unaffected: it still validates, deploys through `rayfin up`, and answers `connector invoke`. Kusto material in these docs describes that preserved runtime contract and the authoring path for when it ships.
+>
+> **`fabric-dataagent` authoring is held in this release**, and the connector remains experimental, not generally available.
+> `connector types` and `connector search` omit it, and `connector add --type fabric-dataagent` refuses before writing files.
+> Existing configurations remain valid and retain their deployment and invocation paths; live use still requires the Data Agent backend adapter.
 
 Each command has its own reference page:
 
@@ -24,7 +28,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) — 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 `fabric-semanticmodel` and experimental `kusto` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
+- [Category B — function-bridge connectors](./category-b-function-bridge.md) — the `fabric-semanticmodel`, experimental `fabric-dataagent` and experimental `kusto` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
 - [Eventhouse (`kusto`) usage guide](./eventhouse.md) — the experimental `kusto` supplement, now **package-owned**; when to reach for the type, its streaming model, shaping KQL, safe query construction, and reading results all ship in `@microsoft/rayfin-connector-kusto` (`rayfin docs search` / `search_docs`).
 
 A typical loop is search → add → inspect (Category A) or search → add → invoke (Category B).
@@ -35,10 +39,10 @@ The commands available to a connector, and the code you write against it, depend
 
 |                                       | Category A — GraphQL entity connectors                                                                                                                                           | Category B — function-bridge connectors                |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `fabric-graphql`                                                                                                | `fabric-semanticmodel`; `kusto` (**experimental**)      |
+| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`                                                                                                                  | `fabric-semanticmodel`; `fabric-dataagent` (**experimental**); `kusto` (**experimental**) |
 | **App surface**                       | Generated entity files with typed CRUD through the data client                                                                                                                   | Named operations carrying raw queries                  |
-| **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`                                    |
+| **Operations**                        | `read` only for `fabric-sqlanalytics` (Lakehouse SQL endpoints are read-only); `read`, `create`, `update`, `delete` for `fabric-warehouse` and `fabric-sqldatabase` (narrowable) | `executeQuery`; experimental `fabric-dataagent` uses named task operations instead |
+| **Auth**                              | `delegated` or configured per project                                                                                                                                            | `application` for `kusto`; `delegated` for the others  |
 | **Entity files and `@role` policies** | Yes                                                                                                                                                                              | No                                                     |
 | **`metadata.json` entities**          | Yes                                                                                                                                                                              | No                                                     |
 | **`connector inspect`**               | Supported                                                                                                                                                                        | `fabric-semanticmodel` only — experimental `kusto` is not supported |

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

@@ -54,11 +54,44 @@ Applies to `--entity` mode only.
 
 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.
+- **SQL** — must start with `SELECT` or `WITH`; an embedded `;` is rejected while a trailing `;` is allowed; rejects `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `EXEC`/`EXECUTE`, and `INTO` anywhere outside a string literal.
+- **SQL result contract** — the query must produce one result set. If Tedious emits a second result set, inspection rejects the query instead of combining rows with a different column contract.
 - **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 — 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.
 
+## SQL column types and values
+
+SQL inspection reads column types from Tedious result metadata, including when a query returns zero rows.
+It never guesses a column type from row values.
+Plain output lists each column as `name (type)` before populated or empty results.
+If the contract exceeds the terminal width, it folds between column entries.
+
+The `columns[].type` field in JSON uses this normalized vocabulary:
+
+| Normalized type    | Tedious metadata types                                                   |
+| ------------------ | ------------------------------------------------------------------------ |
+| `integer`          | `TinyInt`, `SmallInt`, `Int`, `BigInt`, `IntN`                          |
+| `decimal`          | `Decimal`, `Numeric`, money types, and their nullable forms              |
+| `floating-point`   | `Real`, `Float`, `FloatN`                                                |
+| `text`             | Character and Unicode text types, plus `Xml`                             |
+| `boolean`          | `Bit`, `BitN`                                                            |
+| `date`             | `Date`                                                                   |
+| `time`             | `Time`                                                                   |
+| `datetime`         | `SmallDateTime`, `DateTime`, `DateTimeN`, `DateTime2`, `DateTimeOffset` |
+| `uniqueidentifier` | `UniqueIdentifier`                                                       |
+| `binary`           | `Binary`, `VarBinary`, `Image`                                           |
+| `unknown`          | `Null`, `Variant`, `UDT`, `TVP`, and unrecognized or custom types       |
+
+Plain output renders SQL `date` values as `YYYY-MM-DD`, so the calendar value does not shift with the local time zone.
+SQL `time` values render as the UTC time portion `HH:mm:ss.sss`, without Tedious' internal 1970 date anchor.
+SQL `datetime` and `datetime2` are timezone-naive values that Tedious represents using a JavaScript `Date`; plain and JSON output therefore use an ISO value with `Z` by driver convention.
+SQL `datetimeoffset` is also returned as a JavaScript `Date`, so its original offset is not preserved.
+SQL `bigint` row values are strings, while decimal and numeric row values are JavaScript numbers and can carry JavaScript precision limitations.
+Binary and buffer-backed custom values render as terminal-safe `0x` hexadecimal in plain output and use the existing column-width truncation marker when needed.
+JSON row serialization is unchanged: JavaScript `Date` values remain ISO strings, while `columns[].type` now reports the metadata-derived normalized type instead of `unknown`.
+Queries that produce a second SQL result set are rejected when the driver emits its second column contract, including newline-separated batches without semicolons.
+
 ## Examples
 
 ```bash

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

@@ -33,6 +33,10 @@ Two transports, chosen by connector type:
 - **Every other type, including `kusto`** — POSTs to the deployed item at `<remote-endpoint>/__private/connectors/<name>/invoke`, so it requires a prior `npx rayfin up`.
 
 > `kusto` authoring is held in this release, but invocation is deliberately preserved: a project that already declares a Kusto connector can still invoke it. Only `connector add`, `types` and `search` withdraw the type. See [Connectors](./index.md).
+>
+> Experimental `fabric-dataagent` follows the same authoring-only hold.
+> An existing configuration can still invoke its named operations, such as `getInfo`; the hold does not bypass backend availability, authentication, or operation checks.
+> `ask` is an SDK helper, not a CLI-invokable operation.
 
 `--transport deployed` overrides the type-based choice and forces the deployed route. That route authenticates the **app**, not the developer, so it needs an app-session token in `RAYFIN_TOKEN`; `npx rayfin login` cannot mint one.
 

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

@@ -9,6 +9,10 @@ npx rayfin connector search [query] [--workspace-id <id> --type <types> | --all-
 ```
 
 > **`kusto` authoring is held in this release**, so search does not return KQL databases and `--type kusto` is not accepted. Search exists to feed `connector add`, which would refuse the type — surfacing a source the Builder could not then attach. See [Connectors](./index.md).
+>
+> **`fabric-dataagent` authoring is held in this release** too.
+> Search omits Data Agent items, and an explicit `--type fabric-dataagent` is rejected before authentication or discovery.
+> The connector remains experimental and cannot be added yet.
 
 `connector search` finds Fabric data sources — warehouses, SQL databases, Lakehouses, and semantic models — that the signed-in identity can add as connectors, before you know exact workspace or item IDs.
 

package/assets/docs/cli/environment-variables.md

@@ -56,6 +56,7 @@ Set `RAYFIN_WORKSPACE_ID` to target a specific workspace; otherwise the active r
 The CLI starts `npm run dev:frontend` when that script exists and falls back to `npm run dev` for existing projects.
 This lets bundled templates expose `npm run dev` as the complete session without recursively starting the CLI.
 When migrating an existing project to `"dev": "rayfin dev"`, also add a non-recursive child such as `"dev:frontend": "vite"`; otherwise the CLI fails with an actionable recursion error.
+`rayfin init` does this automatically for a from-scratch scaffold, when `@microsoft/rayfin-cli` is installed or already declared as a dependency.
 Scripts are resolved from `services.staticHosting.path` when configured, otherwise from the project root.
 For a nested frontend package, declare `dev:frontend` (or the legacy `dev` fallback) in that package's `package.json`.
 
@@ -73,7 +74,7 @@ The proxy is reachable wherever the Vite dev server is reachable, so keep Vite b
 The local functions setup makes these workspace changes:
 
 - Merges backend coordinates and the Node inspector argument into the configured functions package's `local.settings.json`.
-- Adds a `Functions: Attach` configuration to the root `.vscode/launch.json` after the Functions host becomes ready.
+- Adds a `Functions: Attach` configuration to the root `.vscode/launch.json` after the Functions host becomes ready. If the entry already exists and the inspector moved to another port, only its `port` is updated.
 - Leaves JSON-with-comments launch files unchanged and reports that the attach configuration must be added manually.
 - Patches recognized existing `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` files once so non-adapter projects read `VITE_RAYFIN_FUNCTIONS_URL` only during Vite development.
 - Regenerates the framework `.env.local` file unless `--no-emit-env` is set.

package/assets/docs/cli/functions/deploy.md

@@ -14,6 +14,10 @@ npx rayfin up functions deploy [-v | --verbose] [--skip-build] [--json]
 
 `npx rayfin up` already deploys functions as part of a full deployment. Use `up functions deploy` when you want to run **only** the functions step — for example to retry after a functions deploy failed, or to push a functions-only change without redeploying the rest of the app.
 
+This standalone command uploads function code; it does not validate or apply `services.functions.auth.type` from YAML or migrate the remote Functions auth mode.
+After setting `services.functions.auth.type: application` for an existing app, run a full `npx rayfin up` to apply project settings.
+See [Application authentication](../../functions/index.md#application-authentication).
+
 ## Prerequisites
 
 Run `npx rayfin up` at least once first. This command deploys to an existing remote item, so a remote endpoint must already exist. If there is no active deployment, run a full `npx rayfin up`.
@@ -31,8 +35,16 @@ Run `npx rayfin up` at least once first. This command deploys to an existing rem
 1. Builds and packages the functions project (unless `--skip-build`).
 2. Deploys the package to the remote Rayfin item resolved from your active deployment.
 
+## Troubleshooting
+
+### `404` on deploy
+
+A `404` from the deploy endpoint usually means Functions are not enabled on the **remote** item, not that the endpoint is unavailable.
+The workload hides every Functions route behind the deployed project's `services.functions.enabled` setting, and this command uploads code without applying project settings.
+If you enabled Functions (for example by running `npx rayfin functions init`) after your last full deployment, run `npx rayfin up` once to sync `rayfin.yml`, then retry.
+
 ## Related
 
 - [`functions init`](./init.md) — scaffold and enable functions.
 - [`dev functions apply`](./dev-apply.md) — run and debug functions locally before deploying.
-- [Managing Secrets](../secrets.md) — push secrets that deployed functions read via `ctx.getSecret`.
+- [Managing Secrets](../secrets.md) — push secrets that deployed functions read via `ctx.Secrets`.

package/assets/docs/cli/functions/dev-apply.md

@@ -42,6 +42,11 @@ This command does not start the frontend.
 Run the Vite frontend separately to invoke local functions through `/.rayfin/api/<name>`, or use `npx rayfin dev` to start both together.
 If the local Functions host is unavailable, the Vite adapter returns HTTP 502 instead of invoking deployed function code.
 
+This standalone command does not validate or apply the project's Functions auth setting.
+Full `npx rayfin up` and normal `npx rayfin dev` perform that validation when applying project settings.
+Run a full `npx rayfin up` to apply [`services.functions.auth.type: application`](../../functions/index.md#application-authentication) to the remote app.
+For local token identity, see [Local development](../../functions/connections/index.md#local-development).
+
 ## Automatic recompilation
 
 Both `npx rayfin dev functions apply` and `npx rayfin dev` build the functions package once, then run its `build:watch` script alongside the local Functions host if the script is configured.
@@ -63,11 +68,11 @@ If the response remains stale after compilation finishes, restart the dev sessio
 
 ## Debugging
 
-With debugging enabled (default), attach your debugger to the inspector port (`9229` by default) using the generated **"Functions: Attach"** launch configuration in VS Code. Pass `--no-debug` to run without the inspector.
+With debugging enabled (default), attach your debugger to the inspector port (`9229` by default) using the generated **"Functions: Attach"** launch configuration in VS Code. If you pass a different `--inspect-port`, the existing configuration's port is updated to match. Pass `--no-debug` to run without the inspector.
 
 ## Secrets in local development
 
-Locally there is no deployed secret bag, so `ctx.getSecret(name)` falls back to `process.env`. To provide a secret, add it under `Values` in `rayfin/functions/local.settings.json`; the functions host loads those entries into `process.env`. See [Managing Secrets](../secrets.md#using-secrets-in-local-development).
+Locally there is no deployed secret bag, so `ctx.Secrets.<NAME>` falls back to `process.env`. To provide a secret, add it under `Values` in `rayfin/functions/local.settings.json`; the functions host loads those entries into `process.env`. See [Managing Secrets](../secrets.md#using-secrets-in-local-development).
 
 ## Next step
 
@@ -80,3 +85,4 @@ npx rayfin up functions deploy
 ```
 
 See [`up functions deploy`](./deploy.md).
+The standalone deployment uploads function code; it does not apply YAML auth settings or migrate the remote Functions auth mode.

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

@@ -7,6 +7,8 @@ sidebar_position: 4
 Rayfin functions are server-side user-defined functions (UDFs) that run in the Fabric runtime and are invocable from your frontend through `RayfinClient`. Use them for logic that must run on the backend — secrets and API keys, privileged data access, server-side validation, and anything that should not be exposed or tampered with in client code.
 
 The functions project lives at `rayfin/functions/` and is enabled by the `services.functions.enabled` flag in `rayfin.yml` (set for you the first time you run [`functions init`](./init.md)).
+Enabled Functions also require explicit `services.functions.auth.type: application`, which new scaffolds set.
+See [Application authentication](../../functions/index.md#application-authentication) for existing-app configuration and downstream resource permissions.
 
 Each command has its own reference page:
 
@@ -34,8 +36,8 @@ functions init  →  write UDFs in src/function_app.ts  →  dev functions apply
 - `rayfin/functions/src/function_app.ts` — where you register UDFs with `udf.func()`.
 - `rayfin/functions/src/types.ts` — auto-generated `AppFunctionsSchema`; regenerated by `functions init` (one-shot) and by the watcher inside `dev functions apply`.
 - `rayfin/functions/{package.json,host.json,tsconfig.json,local.settings.json}` — the functions app manifest, host config, TypeScript project references, and local settings.
-- `rayfin.yml` — the `services.functions` block (`enabled`, `buildCommand`).
+- `rayfin.yml` — the `services.functions` block (`enabled`, `auth.type`, `buildCommand`).
 
 ## Secrets
 
-Functions read secrets at runtime with `ctx.getSecret(name)`, backed by the host secret bag with a `process.env` fallback. Manage remote secrets with `npx rayfin secret set` — or bulk-set them from a file with `npx rayfin secret set --env-file` — see [Managing Secrets](../secrets.md).
+Functions read secrets at runtime as typed properties on `ctx.Secrets`, backed by the host secret bag with a `process.env` fallback. Manage remote secrets with `npx rayfin secret set` — or bulk-set them from a file with `npx rayfin secret set --env-file` — see [Managing Secrets](../secrets.md).

package/assets/docs/cli/functions/init.md

@@ -24,12 +24,15 @@ Run this from a directory that already contains a `rayfin/` project (i.e. you ha
 ## What it does
 
 1. **Scaffolds** `rayfin/functions/` with a starter function app, `host.json`, `tsconfig.json`, `package.json`, and `local.settings.json`.
-2. **Enables the service** in `rayfin.yml` by setting `services.functions.enabled: true` and `services.functions.buildCommand: 'npm run build'`.
+2. **Enables the scaffolded service** in `rayfin.yml` by setting `services.functions.enabled: true`, `services.functions.auth.type: application`, and `services.functions.buildCommand: 'npm run build'`.
 3. **Installs dependencies** for the functions project.
 4. **Builds** the project.
 5. **Generates types** — runs a one-shot typegen to produce `rayfin/functions/src/types.ts` (the `AppFunctionsSchema`).
 6. **Installs AI agent files** so assistants understand the functions surface.
 
+Enabled Functions require explicit application authentication.
+For existing apps, see [Application authentication](../../functions/index.md#application-authentication) for the configuration and full-deployment requirement.
+
 ## Runtime version
 
 Fresh and forced scaffolds pin `@microsoft/fabric-user-data-functions` to the exact version of the running Rayfin CLI, matching connector scaffolding.
@@ -60,6 +63,9 @@ rayfin/
 - **Without `--force`** on an existing project, it preserves your `function_app.ts` and only refreshes dependencies, build, and generated types.
 - **With `--force`**, it overwrites the scaffold (a warning is shown before your files are replaced).
 
+Re-running without `--force` does not rewrite the existing Functions auth setting.
+Set `services.functions.auth.type: application` explicitly in an existing app rather than relying on a re-run to migrate it.
+
 ## Next step
 
 Start the local host and typegen watcher:

package/assets/docs/cli/index.md

@@ -89,7 +89,7 @@ Connectors let a Rayfin app read from — and, for some types, write to — Micr
 
 ### Secrets
 
-Secrets are encrypted values stored on your deployed Rayfin item and read at runtime — for example by [functions](./functions/index.md) via `ctx.getSecret`. See [Managing Secrets](./secrets.md) for the full guide.
+Secrets are encrypted values stored on your deployed Rayfin item and read at runtime — for example by [functions](./functions/index.md) via `ctx.Secrets`. See [Managing Secrets](./secrets.md) for the full guide.
 
 | Command | Description |
 | --- | --- |
@@ -129,18 +129,31 @@ export RAYFIN_TELEMETRY_OPTOUT=1
 
 ## Diagnostic logs
 
-`npx rayfin up` and workflow-based `npx rayfin dev` record detailed diagnostics under `~/.rayfin/logs/` even when `--verbose` is absent, including when using `--json` or `--output json`.
+`npx rayfin up`, workflow-based `npx rayfin dev`, and `npx rayfin dev functions apply` record detailed diagnostics under `~/.rayfin/logs/` even when `--verbose` is absent, including when using `--json` or `--output json`.
 After a failure, open the file identified by `Diagnostic log:` to inspect the original invocation without rerunning it.
 JSON failures include the same path in the `diagnosticLog` field of the single result object.
 `dev` JSON failures also include a `hint` with recovery guidance, including provider/configuration preflight errors and unexpected failures.
 
-Adding `--verbose` also mirrors diagnostic records to stderr while `up` or `dev` runs.
+Adding `--verbose` also mirrors diagnostic records to stderr while these commands run.
 The CLI rejects combining `--verbose` with `--json` or `--output json`; detailed diagnostics are still recorded in the log file without `--verbose`.
-This capability applies to workflow-based `up` and `dev` sessions, not standalone subcommands or Docker maintenance flags such as `dev --stop`.
-
-`dev` preserves normal frontend and Functions terminal output and flushes its log after cleanup on Ctrl-C, runtime failure, or normal completion.
+Other standalone subcommands and Docker maintenance flags such as `dev --stop` do not record these logs.
+
+Local Functions sessions show function endpoints, the debugger address, application output, and warnings or errors by default.
+Recognized host startup and configuration detail, HTTP request metadata, and successful initial build output are kept in diagnostics; use `--verbose` to mirror that detail to the terminal.
+When the host restarts after a watched file change, such as `node_modules` updates after an install, the terminal shows a single `Functions host restarted.` line and the debugger address only when it changes.
+When the initial build fails, human output includes a bounded tail of compiler output, and JSON errors include it in `buildOutput`.
+The tail retains up to 100 complete lines and 64 KiB, with an explicit marker when earlier output is omitted.
+Verbose mode does not replay the same compiler output a second time.
+Terminal output preserves stack-frame paths and line numbers, while masking credentials and email addresses.
+Application lines up to 16 KiB are preserved; oversized lines are replaced with an explicit truncation marker.
+Persistent diagnostic logs continue to apply their separate privacy and size limits.
+Failed HTTP responses show their status and, when request metadata is available, the method and path without query strings.
+Unrecognized output remains visible.
+Frontend output is unchanged.
+Both `dev` and `dev functions apply` flush their logs after cleanup on Ctrl-C, runtime failure, or normal completion.
 Piped runtime and build output is captured with a 1 MiB limit per stream.
-Interactive runtimes that inherit the terminal keep their keyboard and TTY behavior; their console output is not captured, and the log records that limitation alongside lifecycle events.
+Interactive Functions sessions keep standard input attached for keyboard interaction, while stdout and stderr are piped for filtering and diagnostic capture.
+Other interactive runtimes that inherit the terminal keep their keyboard and TTY behavior; their console output is not captured, and the log records that limitation alongside lifecycle events.
 
 Logs stay on your machine and are independent of telemetry opt-out.
 The log directory is shared across projects on your machine, so the retention limits below apply across all projects using it.