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

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,6 +29,7 @@ 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.                                                                                                                                                                                                    |
 
@@ -72,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.
 

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-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/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

@@ -35,6 +35,14 @@ 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.

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

@@ -68,7 +68,7 @@ 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
 

package/assets/docs/cli/index.md

@@ -140,6 +140,7 @@ Other standalone subcommands and Docker maintenance flags such as `dev --stop` d
 
 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.

package/assets/docs/preview/local-dev-docker.md

@@ -28,6 +28,7 @@ This command:
 - Runs health checks and waits for all services to be healthy.
 - Applies the project's declared data configuration to the local backend.
 - Starts the frontend with `npm run dev:frontend` when that script exists, falling back to `npm run dev` for existing projects.
+  `rayfin init` sets this up automatically for a from-scratch scaffold, when `@microsoft/rayfin-cli` is installed or already declared as a dependency.
 - Resolves that script from `services.staticHosting.path` when the frontend lives in a nested package, otherwise from the project root.
 - Builds and starts the configured local Functions host when `services.functions.enabled` is `true`.
 
@@ -48,7 +49,7 @@ The command also:
 
 - Merges local backend settings into the configured functions package's `local.settings.json`.
 - Reserves a Node inspector port starting at `9229`.
-- Adds `Functions: Attach` to the root `.vscode/launch.json` after the Functions host is ready.
+- Adds `Functions: Attach` to the root `.vscode/launch.json` after the Functions host is ready. If the entry already exists and the inspector moved to another port, only its `port` is updated.
 - Patches recognized existing `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` files to pass `VITE_RAYFIN_FUNCTIONS_URL` directly only during Vite development.
 
 If `.vscode/launch.json` contains JSON with comments, Rayfin leaves it unchanged to avoid losing those comments and asks you to add the attach configuration manually.

package/package.json

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