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

package/assets/docs/app-backend/deep-linking.md

@@ -33,6 +33,8 @@ Your app owns the shape of the state object.
 npm install @microsoft/rayfin-app-state-fabric
 ```
 
+If your project uses prerelease Rayfin packages, install the same exact version of `@microsoft/rayfin-app-state-fabric` as the other `@microsoft/rayfin-*` packages in the project.
+
 ## Create the client
 
 Create one client for the lifetime of your app and share it, rather than constructing one per component.
@@ -40,13 +42,13 @@ Create one client for the lifetime of your app and share it, rather than constru
 ```typescript
 import { createFabricAppStateClient } from '@microsoft/rayfin-app-state-fabric';
 
-const appState = createFabricAppStateClient({
-  targetOrigin: 'https://app.fabric.microsoft.com',
-});
+const appState = createFabricAppStateClient();
 ```
 
-Pass `targetOrigin` whenever you know it.
-Without it, messages are posted with `"*"` and inbound events are not origin-checked.
+Leave `targetOrigin` unset.
+The parent window is a Fabric extension host, not the portal origin shown in the address bar, and its origin varies by environment.
+Pinning the portal origin makes the browser silently discard every message.
+When `targetOrigin` is omitted, messages are posted with `"*"` and inbound events are not origin-checked.
 
 ## Read launch state before first render
 
@@ -66,6 +68,36 @@ It resolves from the seeded URL on hosts that support it, so awaiting it does no
 Treat launch state as untrusted input.
 Anyone can edit a link before sharing it, so validate it exactly as you would a query parameter before using it to drive queries.
 
+## Keep the restored route through sign-in
+
+A Rayfin app is authenticated, and its route guard sends a signed-out visitor to the sign-in route.
+That redirect runs after the launch state has been restored, so a guard that does not carry the requested route forward replaces it, and the visitor lands on the default page.
+
+This is the normal path for a shared link, because the recipient is usually not signed in yet.
+
+Capture the requested route when you redirect to the sign-in route, then return to it after sign-in.
+
+```tsx
+if (requireAuth && !isAuthenticated) {
+  const redirectState: AuthRedirectState = {
+    from: `${location.pathname}${location.search}`,
+  };
+  return <Navigate to="/auth" replace state={redirectState} />;
+}
+
+if (!requireAuth && isAuthenticated) {
+  return <Navigate to={resolveReturnPath(location.state)} replace />;
+}
+```
+
+Validate the captured route before navigating back to it.
+Accept only same-origin application paths, and reject the sign-in route itself so sign-in cannot loop.
+
+Keeping the sign-in route out of the state you persist is not the same thing.
+A shared link needs both: never write the sign-in route into deep-link state, and carry the requested route across the sign-in redirect.
+
+Templates that ship a route guard already carry the requested route through sign-in, so preserve that behavior as you add routes.
+
 ## Write state as the user navigates
 
 Choose between the two writers by asking who caused the change.
@@ -167,6 +199,12 @@ Validate launch state before using it, and tolerate state written by a different
 **`isSupported()` resolves to `undefined`.**
 Either the app is not embedded in the Fabric portal, or deep linking has not reached this tenant yet.
 Both are expected, and your app should fall back to its own routing.
+Also check that the client does not set `targetOrigin`; pinning the portal origin silently prevents communication with the Fabric extension host.
+
+**A shared link opens the default page instead of the shared view.**
+The app restored the launch state and then replaced it.
+Check the sign-in redirect first, because the recipient of a shared link is usually signed out.
+See [Keep the restored route through sign-in](#keep-the-restored-route-through-sign-in).
 
 **Writes reject with `STATE_TOO_LARGE`.**
 The state exceeds the encoded budget the host reported.

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
 
@@ -107,7 +142,9 @@ After deployment, the CLI prints:
 
 Each deployment is recorded in `rayfin/.deployments.json` (the registry of every workspace you have deployed to from this project), and the corresponding `RAYFIN_PUBLIC_*` variables are merged into `rayfin/.env` so subsequent commands and your frontend pick up the same values.
 
-For frontend frameworks, the CLI also runs `rayfin env` to emit a framework-specific `.env.local` (e.g. for Vite) before the static build. That file is what your client code reads at runtime.
+For frontend frameworks, the CLI refreshes a framework-specific `.env.local` (for example, for Vite) before the static build.
+Detection and environment generation use the frontend directory selected by `services.staticHosting.path` and its optional `root`, while the public deployment values come from the project's `rayfin/.env`.
+If detection or environment generation fails, the deployment reports a warning with guidance instead of treating it as a successful refresh.
 
 ```text title="rayfin/.deployments.json"
 {
@@ -165,9 +202,23 @@ services:
 Use `-n, --dry-run` to see what the CLI would do without creating or modifying any resources:
 
 ```bash
-npx rayfin up -n
+npx rayfin up -n --workspace-id <workspace-id>
 ```
 
+Preview validates deterministic local static-hosting inputs before authentication or remote lookup.
+The configured frontend `path` and optional build `root` must exist and be directories.
+When `buildCommand` is configured, the output `folder` may be missing because the build has not run yet.
+Without a build command, the output folder must already exist and contain files.
+Static input checks are skipped when static hosting is disabled or excluded.
+
+After local validation, preview uses the same authentication and workspace-selection rules as deployment.
+It makes read-only Fabric requests to resolve the current workspace display name and ID, showing both before the planned operations.
+With `--json`, these values are available as `plan.workspaceName` and `plan.workspaceId`.
+If the workspace cannot be resolved, preview exits nonzero without creating or modifying resources.
+
+Preview does not run builds, provision an item, apply settings or schemas, or update project deployment files.
+A successful preview is not a build result or a guarantee that remote deployment operations will succeed.
+
 ### Skip specific services
 
 Use `--exclude-services <names>` to skip the build/package/deploy phase for supported services without touching the rest of the deployment.

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

@@ -28,6 +28,15 @@ If you do not already know the workspace and item IDs, run [`connector search`](
 | `-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 +55,7 @@ connectors:
       workspaceId: ${WS_ID}
       itemId: ${ITEM_ID}
     auth:
-      type: delegated
+      type: application
     operations:
       - name: read
       - name: update
@@ -97,6 +106,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/index.md

@@ -35,7 +35,7 @@ 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`; `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`                                    |

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

@@ -5,7 +5,7 @@ sidebar_position: 4
 # connector invoke
 
 ```bash
-npx rayfin connector invoke <connector-name> <operation> (--input '<json>' | --file <path>) [--verbose] [--json]
+npx rayfin connector invoke <connector-name> <operation> (--input '<json>' | --file <path>) [--output-file <path>] [--max-inline-bytes <bytes>] [--verbose] [--json]
 ```
 
 `connector invoke` runs a single named operation against a configured connector and prints the result. It is the loop for exercising [Category B connectors](./index.md#two-categories-of-connector) — `executeQuery` over DAX or KQL — without writing any app code.
@@ -50,6 +50,8 @@ Two transports, chosen by connector type:
 
 Success emits `{status: 'ok', connector, operation, output}`. In non-JSON modes it prints `✅ Invoked <name>.<operation>` followed by the output.
 
+A result larger than 8 KB is written to a file instead of being printed whole; see [Large results](#large-results).
+
 What `output` holds depends on the connector. `fabric-semanticmodel` normalises inside its `invoke` middleware, so `output` is already a discriminated result rather than the raw service envelope: `{status: 'success', table, requestId}`, where `table.columns` are `{name, dataType}` and `table.rows` are column-aligned arrays. No caller-side conversion is needed, and the same shape comes back whether the operation ran locally or through the deployed item.
 
 A resolved call is **not** automatically a success, and the failure signal depends on the same distinction. A connector that normalises reports Power BI failures — expired token, missing Build permission, throttling — as `{status: 'error', error, requestId}`, where `error` carries `category`, `message`, and optional `code` and `details`. A connector that returns the raw envelope reports failure as `status: 'Failed'` instead. The CLI reads both, converts either into a non-zero exit, and surfaces the service-supplied request id for tracing.
@@ -82,6 +84,56 @@ For example, an invalid DAX query exits with code `1` and can emit:
 Read `connectorError.code` and `connectorError.details` rather than parsing the display string.
 Service diagnostics may contain query or model content; review them before sharing or recording them in logs.
 
+## Large results
+
+A query has no upper bound on how much it returns, and printing a multi-megabyte result set floods a terminal — or, when an agent runs the CLI and reads its stdout, burns the agent's context window on rows it cannot use.
+
+When the serialized result exceeds **8 KB**, the full payload is written to a file and `output` carries only a preview.
+
+That threshold is a token budget, not a byte intuition.
+Connector output tokenizes at roughly 2.8 characters per token, and numeric table data at about 1.8, so 8 KB is around 3k–4.5k tokens — a reasonable cost for one probe.
+For scale, 256 KB of the same data is 93,000–144,000 tokens, which is most of a typical context window.
+
+The preview samples bulk data but preserves metadata: arrays of **50 or fewer** entries pass through whole, longer arrays keep their first 20 entries, and long strings are cut.
+That rule is what keeps a column list intact — a sampled column list would report a partial schema with nothing marking it partial, so a caller asking what a query returns would get a confident wrong answer.
+If a 20-entry sample would itself exceed the threshold, the sample shrinks (10, 5, 2, 1) until it fits; only if no setting fits does `output` become `null`.
+
+The envelope gains these fields, so this is detectable rather than silent:
+
+| Field             | Meaning                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| `outputFile`      | Absolute path the full result was written to.                |
+| `outputBytes`     | Serialized size of the full result, in bytes.                 |
+| `outputTruncated` | `true` when `output` is a preview rather than the whole result. |
+| `previewItems`    | Entries kept from each sampled array, or `0` when `output` is `null`. |
+
+Read `outputFile` instead of re-running the query.
+The file holds exactly what `output` would have held, so it can be passed straight to `jq` or opened by an agent.
+
+Spilled results are written to `<project-root>/rayfin/.temp/invoke-results/` with owner-only permissions, and are pruned after 14 days or 20 files, whichever comes first.
+`rayfin/.temp/` is the CLI's existing scratch directory and is covered by the scaffolded `.gitignore`, so query results — which are customer data — cannot be committed by a stray `git add`.
+
+Two flags control this:
+
+- `--max-inline-bytes <bytes>` — change the threshold. `0` restores the old behavior and always prints the result in full.
+- `--output-file <path>` — always write the full result to `<path>`, whatever its size. The inline result is still shown in full unless it also crosses the threshold.
+
+```json
+{
+  "status": "ok",
+  "connector": "mymodel",
+  "operation": "executeQuery",
+  "output": { "status": "success", "table": { "columns": [], "rows": [] } },
+  "outputFile": "/path/to/app/rayfin/.temp/invoke-results/2026-09-21T101500.123Z-mymodel-executequery-1a2b3c4d.json",
+  "outputBytes": 4821004,
+  "outputTruncated": true,
+  "previewItems": 20
+}
+```
+
+If the file cannot be written, the command still succeeds with a truncated `output` and warns — falling back to printing the whole payload would recreate the problem this exists to prevent.
+An explicit `--output-file` that cannot be written fails instead, because the caller named that path.
+
 ## Examples
 
 ```bash
@@ -93,6 +145,9 @@ npx rayfin connector invoke --name mymodel --operation executeQuery --file ./pay
 
 # Machine-readable (no --verbose allowed alongside)
 npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOPN(1, Sales)"}' --json
+
+# Send the full result to a known path instead of hunting for the spill file
+npx rayfin connector invoke mymodel executeQuery --file ./payload.json --output-file ./result.json --json
 ```
 
 ## Errors
@@ -106,3 +161,5 @@ npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOP
 | `missing workspaceId/itemId in rayfin.yml`                       | Add both under `config:`, or re-run [`connector add`](./add.md).                      |
 | `Access token has the wrong audience for the Power BI query API` | Unset or replace `RAYFIN_TOKEN`, or re-run without `--json` to consent interactively. |
 | `No remote endpoint configured`                                  | The non-semantic-model transport needs a deployed item — run `npx rayfin up` first.   |
+| `Invalid --max-inline-bytes value`                               | Pass a non-negative whole number of bytes, or `0` to always print inline.             |
+| `Could not write the result to <path>`                           | Point `--output-file` at a writable path, or drop the flag to use the default location. |

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`.
@@ -35,4 +39,4 @@ Run `npx rayfin up` at least once first. This command deploys to an existing rem
 
 - [`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

@@ -4,7 +4,8 @@ sidebar_position: 2
 
 # dev functions apply
 
-Start the local Rayfin functions runtime against your active deployment, with a live typegen watcher and debugger support. This is the command you run while developing and debugging functions.
+Start the local Rayfin functions runtime against your active deployment, with automatic recompilation when a `build:watch` script is configured, a live typegen watcher, and debugger support.
+This is the command you run while developing and debugging functions.
 
 ```bash
 npx rayfin dev functions apply [--port <port>] [--inspect-port <port>] [--no-debug] [--no-emit-env]
@@ -34,20 +35,44 @@ npx rayfin dev functions apply [--port <port>] [--inspect-port <port>] [--no-deb
 5. Preserves the existing same-origin adapter in bundled Vite templates.
    For recognized older or custom Vite clients, the first run patches `functionsBaseUrl` to read the generated URL only during development.
 6. Builds the functions project, runs a one-shot typegen, then starts a visible **typegen watcher** (`[typegen]` prefix) that keeps `src/types.ts` in sync as you edit `function_app.ts`.
-7. Starts `func start` in the foreground and writes a `.vscode/launch.json` **"Functions: Attach"** configuration for debugging.
+7. Starts `func start` alongside the package's `npm run build:watch` compiler watcher when configured, and writes a `.vscode/launch.json` **"Functions: Attach"** configuration for debugging.
 
-Press `Ctrl+C` to stop the host and watcher.
+Press `Ctrl+C` to stop the host and watchers.
 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.
+Both commands use `services.functions.path` from `rayfin.yml` and preserve `services.functions.buildCommand` for the initial build.
+
+To enable automatic recompilation, define a long-running `build:watch` script in the functions package's `package.json`; the TypeScript scaffold uses `"build:watch": "tsc --build --watch"`.
+If you use a custom compiler or bundler, set that script to its watch command instead.
+Source edits are compiled into `dist`, which the host watches to reload handlers.
+The separate typegen watcher keeps `src/types.ts` up to date and does not rewrite the file when the generated types are unchanged.
+
+If `build:watch` is absent, the CLI warns and starts the host without a compiler watcher; run the functions package's build command manually after source edits.
+Type generation remains enabled without a compiler watcher.
+An invalid watch script or an unreadable package manifest remains an error.
+An initial build failure prevents host startup; later compiler diagnostics can be fixed without restarting the session.
+If the compiler watcher exits, the session stops rather than serving stale code.
+
+Core Tools owns worker reloads; edits made while it is restarting can occasionally leave a stale handler running.
+If the response remains stale after compilation finishes, restart the dev session.
+
 ## 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.
 
 ## 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
 
@@ -60,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,24 @@ 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.
+This also applies when `rayfin init` scaffolds the Functions service.
+
+The running CLI version may differ from the SDK version already installed in your app.
+Run the CLI release you want the Functions runtime to match.
+Re-running without `--force` preserves the existing Functions `package.json`, including any runtime version you selected.
+
 ## Scaffolded structure
 
 ```text
@@ -51,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

@@ -70,7 +70,7 @@ Functions are server-side user-defined functions (UDFs) that run in the Fabric r
 | Command | Description |
 | --- | --- |
 | `npx rayfin functions init [directory]` | Scaffold `rayfin/functions/`, enable the functions service, install dependencies, build, and generate types. See [functions init](./functions/init.md). |
-| `npx rayfin dev functions apply` | Run the local function host with a live typegen watcher and debugger support. See [dev functions apply](./functions/dev-apply.md). |
+| `npx rayfin dev functions apply` | Run the local function host with an optional compiler watcher, live typegen, and debugger support. See [dev functions apply](./functions/dev-apply.md). |
 | `npx rayfin up functions deploy` | Build, package, and deploy functions to the remote Rayfin item. `rayfin up` runs this automatically. See [up functions deploy](./functions/deploy.md). |
 
 ### Connectors
@@ -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,30 @@ 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 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.

package/assets/docs/cli/secrets.md

@@ -4,7 +4,7 @@ sidebar_position: 50
 
 # Managing Secrets
 
-Secrets are encrypted values — API keys, connection strings, tokens — that your app needs at runtime but must never ship in client code. They are stored securely on your deployed Rayfin item and read on the server by [functions](./functions/index.md) via `ctx.getSecret(name)`.
+Secrets are encrypted values — API keys, connection strings, tokens — that your app needs at runtime but must never ship in client code. They are stored securely on your deployed Rayfin item and read on the server by [functions](./functions/index.md) via `ctx.Secrets`.
 
 Manage secrets with the `npx rayfin secret` command group:
 
@@ -105,18 +105,28 @@ Deleting a secret that does not exist reports a not-found error — run `npx ray
 
 ## Reading secrets from functions
 
-Server-side functions read secrets at runtime with `ctx.getSecret(name)`, which resolves against the deployed item's secret bag and falls back to `process.env`. Set a secret with `npx rayfin secret set <name>`, then read it by the same name inside your handler:
+Server-side functions read secrets at runtime as typed properties on `ctx.Secrets`, which resolve against the deployed item's secret bag and fall back to `process.env`. Set a secret with `npx rayfin secret set <name>`, then read it by the same name inside your handler:
 
 ```ts
-udf.func("summarize", async (ctx, input: { text: string }) => {
-  const apiKey = ctx.getSecret("OPENAI_KEY");
-  // ... call the API with apiKey
-});
+import { type RayfinContext } from "@microsoft/fabric-user-data-functions";
+
+udf.func(
+  "summarize",
+  async (ctx: RayfinContext<AppSchema>, input: { text: string }) => {
+    const apiKey = ctx.Secrets.OPENAI_KEY;
+    // ... call the API with apiKey
+  },
+  [],
+);
 ```
 
+The `RayfinContext<AppSchema>` annotation is what makes this type-safe. An unannotated `ctx` is contextually `any`, so `ctx.Secrets.OPENAI_KEY` compiles whether or not the secret is declared — and the annotation is also how typegen recognises the parameter as the injected context rather than a request-body argument.
+
+Setting the secret is what types it: the CLI regenerates `rayfin/functions/src/secrets.generated.ts`, so `ctx.Secrets.OPENAI_KEY` is a `string` and an undeclared name is a compile error. See [Secrets](../functions/secrets.md) for the full model.
+
 ## Using secrets in local development
 
-When you run functions locally with [`npx rayfin dev functions apply`](./functions/dev-apply.md), there is no deployed secret bag, so `ctx.getSecret(name)` falls back to `process.env`. To make a secret available locally, add it under `Values` in `rayfin/functions/local.settings.json` — the Azure Functions host loads those entries into `process.env`:
+When you run functions locally with [`npx rayfin dev functions apply`](./functions/dev-apply.md), there is no deployed secret bag, so `ctx.Secrets.<NAME>` falls back to `process.env`. To make a secret available locally, add it under `Values` in `rayfin/functions/local.settings.json` — the Azure Functions host loads those entries into `process.env`:
 
 ```json
 {
@@ -166,6 +176,6 @@ If `secret delete` reports the secret was not found:
 
 ## See also
 
-- [Functions](./functions/index.md) — read secrets from server-side functions with `ctx.getSecret`.
+- [Functions](./functions/index.md) — read secrets from server-side functions with `ctx.Secrets`.
 - [CLI quickstart](./quickstart.md)
 - [Environment configuration](./env-interpolation.md)