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

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

@@ -4,12 +4,15 @@ sidebar_position: 5
 
 # Connecting to external resources
 
-Functions can call external Azure and Fabric resources **as the calling user** using delegated authentication.
-You declare a connection on the function, and at invocation time the runtime exchanges the user's identity for a resource-scoped on-behalf-of (OBO) token.
+Deployed Functions call external Azure and Fabric resources **as the app identity** using application authentication.
+You declare the audiences a function needs and consume platform-provided, resource-scoped tokens through `ctx.Tokens`.
+See [Application authentication](../index.md#application-authentication) for configuration, resource permissions, and the distinction from caller-scoped Rayfin DB access.
+
+Developer CLI login and authoring-time endpoint discovery are separate from deployed runtime access; verify the deployed app identity's permissions even when a developer can access the resource.
 
 ## The pattern
 
-Declare an audience-scoped connection in the third argument of `udf.func()`, then read its token with `ctx.getToken()`:
+Declare the audiences in the `RayfinContext` annotation, then read the scoped token off `ctx.Tokens`:
 
 ```ts
 import {
@@ -21,19 +24,123 @@ import {
 const udf = new UserDataFunctions();
 
 udf.func(
-  "myFunction",
-  async (ctx: RayfinContext): Promise<string> => {
-    const token = ctx.getToken(AudienceType.KeyVault);
+  "accessStorage",
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
+  ): Promise<string> => {
+    const token: string = ctx.Tokens.Storage;
     // Use `token` with the resource's SDK or REST API.
     return "ok";
   },
-  [udf.connection({ audienceType: AudienceType.KeyVault })],
+  [],
+);
+```
+
+**The annotation is the declaration.** Listing an audience in `RayfinContext<Schema, Audiences>` is what registers the connection binding — there is nothing to add to the third argument of `udf.func()`.
+
+`ctx.Tokens` is narrowed to exactly the audiences you declared, so an undeclared audience is a compile error rather than a runtime throw:
+
+```ts
+async (
+  ctx: RayfinContext<AppSchema, AudienceType.Sql | AudienceType.Storage>,
+) => {
+  const sqlToken: string = ctx.Tokens.Sql; // ok
+  const storageToken: string = ctx.Tokens.Storage; // ok
+  ctx.Tokens.Fabric; // compile error — not declared
+};
+```
+
+Values are typed `string`, not `string | undefined`.
+Declaring an audience registers its binding, but does not guarantee token availability or resource access.
+If the host does not supply a declared token, reading its `ctx.Tokens` property throws.
+
+### The schema argument
+
+`RayfinContext` takes your app schema first — the same one you pass to `RayfinClient<AppSchema>` — so the data client stays typed while you add audiences:
+
+```ts
+async (ctx: RayfinContext<AppSchema, AudienceType.Sql>) => {
+  const data = ctx.getDataClient(); // typed by AppSchema
+  const token = ctx.Tokens.Sql;
+};
+```
+
+If a function needs audiences but no data access, pass the default schema explicitly:
+
+```ts
+async (ctx: RayfinContext<Record<string, any>, AudienceType.Fabric>) => {
+  const token = ctx.Tokens.Fabric;
+};
+```
+
+## The third argument
+
+`udf.func()` still takes a third argument, and it stays `[]`. Audience-scoped connections are declared entirely in the context annotation — there is nothing to add there:
+
+```ts
+udf.func(
+  "syncWarehouse",
+  async (ctx: RayfinContext<AppSchema, AudienceType.Sql>): Promise<void> => {
+    const token = ctx.Tokens.Sql;
+  },
+  [],
+);
+```
+
+## Supported audiences
+
+`AudienceType` is the source of truth — inventing a member will not compile:
+
+`Sql`, `Storage`, `Fabric`, `AzureAI`, `ADO`.
+
+A Power BI semantic model is **not** reachable this way; use the `fabric-semanticmodel` connector instead.
+
+## How audiences reach the deployment
+
+Type arguments are erased before your function runs, so the audiences have to be recovered at build time. `npx rayfin up` resolves them with the TypeScript compiler and writes the resolved union into the deployment metadata, which is what the worker binds against.
+
+Because the compiler does the resolving, a type alias works:
+
+```ts
+type SqlAccess = AudienceType.Sql;
+
+// Resolves to AudienceType.Sql and binds a Sql connection.
+async (ctx: RayfinContext<AppSchema, SqlAccess>) => {
+  const token = ctx.Tokens.Sql;
+};
+```
+
+Writing audiences **literally** is still the clearer default, and there is one case where it is required: if the functions project has no `tsconfig.json`, the CLI has no compiler to ask and falls back to reading the annotation's syntax. An alias then resolves to its own name rather than the audience it stands for. The CLI warns when it is in that mode — treat the warning as a real problem, not noise.
+
+The context parameter must also carry an explicit `RayfinContext<...>` annotation. Typegen identifies the context parameter by that annotation; an unannotated parameter is treated as a request-body parameter instead.
+
+## Migrating from `ctx.getToken()`
+
+`ctx.getToken(audienceType)` is **deprecated**. It is flagged by `@typescript-eslint/no-deprecated`, which the scaffolded ESLint config reports as an error.
+
+```ts
+// Before
+udf.func(
+  "queryData",
+  async (ctx: RayfinContext): Promise<void> => {
+    const token = ctx.getToken(AudienceType.Sql);
+  },
+  [udf.connection({ audienceType: AudienceType.Sql })],
+);
+
+// After
+udf.func(
+  "queryData",
+  async (ctx: RayfinContext<AppSchema, AudienceType.Sql>): Promise<void> => {
+    const token = ctx.Tokens.Sql;
+  },
+  [],
 );
 ```
 
-- `udf.connection({ audienceType })` declares the delegated connection.
-- `ctx.getToken(audienceType)` returns the OBO access token as a `string`. It throws if no connection was declared for that audience.
-- The connection declaration is what makes the token available — declaring the audience and calling `getToken` with the same audience always go together.
+Move the audience from the third argument into the annotation, then replace the call with the property.
+
+**Both halves are required.** The array keeps working at *runtime* — array audiences are unioned with the annotated ones, so a deployed function still binds the connection. But it no longer carries any type information: `TokenTypes` defaults to `never`, so a handler left as `ctx: RayfinContext<AppSchema>` stops compiling at `ctx.getToken(AudienceType.Sql)` even with `Sql` declared in the array. Add the audience to the annotation first; the array alone is not enough.
 
 ## Wrapping the token for Azure SDK clients
 
@@ -51,12 +158,12 @@ class ContextTokenCredential implements TokenCredential {
 }
 ```
 
-Pass `new ContextTokenCredential(ctx.getToken(AudienceType.X))` wherever an Azure SDK client asks for a credential.
+Pass `new ContextTokenCredential(ctx.Tokens.X)` wherever an Azure SDK client asks for a credential.
 The per-resource guides below use this helper.
 
 ## Choose a recipe
 
-Find what you want to connect to. Each row links to a task-oriented walkthrough; the `AudienceType` is the value you pass to `udf.connection()` and `ctx.getToken()`. A single audience can back more than one use case (for example `Storage` covers both Fabric OneLake and Azure Blob).
+Find what you want to connect to. Each row links to a task-oriented walkthrough; the `AudienceType` is the value you put in the context annotation and the key you read off `ctx.Tokens`. A single audience can back more than one use case (for example `Storage` covers both Fabric OneLake and Azure Blob).
 
 | I want to connect to…                            | `AudienceType` | Recipe                                                               |
 | ------------------------------------------------ | -------------- | -------------------------------------------------------------------- |
@@ -64,26 +171,24 @@ Find what you want to connect to. Each row links to a task-oriented walkthrough;
 | Azure SQL Database                               | `Sql`          | [Add a Fabric resource](./add-fabric-resource.md#sql-databases)      |
 | Fabric OneLake files                             | `Storage`      | [Add a Fabric resource](./add-fabric-resource.md#onelake-files)      |
 | Azure Blob / Table / Queue                       | `Storage`      | [Add an Azure resource](./add-azure-resource.md#blob-storage)        |
-| Fabric Eventhouse (KQL)                          | `Kusto`        | [Add a Fabric resource](./add-fabric-resource.md#eventhouse-and-kql) |
-| Azure Data Explorer                              | `Kusto`        | [Add a Fabric resource](./add-fabric-resource.md#eventhouse-and-kql) |
 | Microsoft Fabric REST API                        | `Fabric`       | [Add a Fabric resource](./add-fabric-resource.md#fabric-rest-api)    |
-| Azure Key Vault                                  | `KeyVault`     | [Add an Azure resource](./add-azure-resource.md#key-vault)           |
-| Azure Cosmos DB                                  | `CosmosDB`     | [Add an Azure resource](./add-azure-resource.md#cosmos-db)           |
-| Azure Event Grid                                 | `EventGrid`    | [Add an Azure resource](./add-azure-resource.md#event-grid)          |
 | Azure AI Foundry                                 | `AzureAI`      | [Add Azure AI Foundry](./add-foundry.md)                             |
 | Azure DevOps                                     | `ADO`          | [Add Azure DevOps](./add-ado.md)                                     |
-| WorkIQ                                           | `WorkIQ`       | [Add WorkIQ](./add-work-iq.md)                                       |
 
-To look up a Fabric item's connection coordinates (SQL endpoint, OneLake path, Kusto query URI), see [Get Fabric info](./get-fabric-info.md).
+To look up a Fabric item's connection coordinates (SQL endpoint or OneLake path), see [Get Fabric info](./get-fabric-info.md).
 
 ## Rules
 
+- **Declare generic audiences in the annotation** and read them with `ctx.Tokens.<Audience>`. Prefer literal `AudienceType.X`, and keep a `tsconfig.json` in the functions project so the CLI can resolve anything that isn't.
+- **Pass `[]` as the third argument** to `udf.func()`.
 - **Use real endpoint URLs** — don't hardcode a guess or read them from `process.env`. For Fabric items, [Get Fabric info](./get-fabric-info.md) shows how to look them up.
-- Declare every connection in the third argument to `udf.func()`.
-- Use `ctx.getToken(AudienceType.X)` — never acquire tokens manually.
+- Never acquire tokens manually.
+- Grant resource access to the app identity, and keep its tokens server-side; never return them as function results.
 - Install resource SDK packages in `rayfin/functions/package.json`, not the project root.
 
 ## Local development
 
-When you run `npx rayfin dev functions apply`, the local host acquires delegated tokens interactively for debugging, so `ctx.getToken()` works against your declared audiences without a deployment.
+`npx rayfin dev` and `npx rayfin dev functions apply` start a local Azure Functions Core Tools host.
+External resource tokens use the identity and permissions of the account the builder signs in with in the local Functions host.
+Deployed Functions instead use the [application identity](../index.md#application-authentication).
 See [`npx rayfin dev functions apply`](../../cli/functions/dev-apply.md).

package/assets/docs/functions/index.md

@@ -29,6 +29,44 @@ npx rayfin functions init
 This creates `rayfin/functions/`, installs dependencies, and generates the initial `types.ts`.
 See [`npx rayfin functions init`](../cli/functions/init.md) for the full command reference.
 
+## Application authentication
+
+Enabled Functions require explicit application authentication in `rayfin/rayfin.yml`:
+
+```yaml
+services:
+  functions:
+    enabled: true
+    auth:
+      type: application
+    buildCommand: npm run build
+```
+
+New Functions scaffolds set `auth.type: application`.
+For an existing app, set it explicitly; loading the configuration does not add a default or migrate an older auth mode.
+Disabled Functions may omit `auth`, but any supplied `auth` must include `type: application`.
+No feature flag is needed.
+
+Full `npx rayfin up` and normal `npx rayfin dev` validate this setting before applying project settings to either the Fabric or Docker backend.
+Run a full `npx rayfin up` to apply the YAML auth mode to an existing remote app.
+Standalone `npx rayfin dev functions apply`, `npx rayfin up functions deploy`, and `npx rayfin up staticapp deploy` do not perform this project-settings validation or change the remote Functions auth mode.
+
+Deployed Functions use two separate authentication paths:
+
+| Access path | Credential | Identity and permissions |
+| --- | --- | --- |
+| External connections through `ctx.Tokens.*` | Platform-provided resource token | Application identity and its permissions on the external resource |
+| Rayfin DB through `ctx.getDataClient()` | The invocation's Rayfin token | The caller's identity and permissions on the Rayfin DB |
+
+For current Fabric apps, the app identity is the owner of the Fabric app item.
+External connections therefore use the item owner's permissions, not those of whichever app user invokes the function.
+Grant that identity the permissions required by each external resource and API your functions call.
+Declaring an audience or deploying Functions does not grant those permissions.
+App sign-in and authorization to invoke a function remain separate from the app identity's external resource access.
+Rayfin DB access always uses the Rayfin token and preserves the caller's identity and database permissions.
+Setting `services.functions.auth.type: application` does not switch Rayfin DB access to the application identity.
+See [Connecting to external resources](./connections/index.md) for audience declarations, permissions, and local development.
+
 ## Project structure
 
 After `npx rayfin functions init`, the functions project lives at `rayfin/functions/`:
@@ -86,6 +124,6 @@ See [`npx rayfin dev functions apply`](../cli/functions/dev-apply.md) for detail
 
 - [Writing functions](./writing-functions.md) — the `udf.func()` API, `RayfinContext`, and data access.
 - [Type generation](./typegen.md) — how `types.ts` is generated and kept in sync.
-- [Connecting to external resources](./connections/index.md) — delegated access to SQL, Storage, Key Vault, and more.
+- [Connecting to external resources](./connections/index.md) — app-identity access to SQL, Storage, the Fabric REST API, and more.
 - [Secrets](./secrets.md) — reading secrets from inside a function.
 - [Invoking functions from the frontend](./invoking-from-frontend.md) — calling functions with `RayfinClient`.

package/assets/docs/functions/secrets.md

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # Secrets
 
-Functions read secret values through `ctx.getSecret(name)` on [`RayfinContext`](./writing-functions.md#rayfincontext-api).
+Functions read secret values as typed properties on `ctx.Secrets`, part of [`RayfinContext`](./writing-functions.md#rayfincontext-api).
 
 ```ts
 import {
@@ -16,23 +16,34 @@ const udf = new UserDataFunctions();
 
 udf.func(
   "readApiKey",
-  async (ctx: RayfinContext): Promise<string> => {
-    const apiKey = ctx.getSecret("THIRD_PARTY_API_KEY");
-    if (!apiKey) {
-      throw new Error("Missing THIRD_PARTY_API_KEY secret.");
-    }
-    return apiKey;
+  async (ctx: RayfinContext<AppSchema>): Promise<string> => {
+    return ctx.Secrets.THIRD_PARTY_API_KEY;
   },
   [],
 );
 ```
 
+There is nothing to add to the function's declaration and nothing to add to your data schema — declaring the secret with the CLI is what types it.
+
+## How the names are typed
+
+`npx rayfin secret set <NAME>` records the name in `rayfin.yml`, and the CLI regenerates `rayfin/functions/src/secrets.generated.ts`. That file augments the SDK's `RayfinSecretRegistry` interface, which is what narrows `ctx.Secrets`:
+
+```ts
+ctx.Secrets.THIRD_PARTY_API_KEY; // string
+ctx.Secrets.NOT_DECLARED; // compile error
+```
+
+- Values are typed `string`, not `string | undefined` — the name was declared, so the value is modelled as present. Reading a declared secret that was not supplied throws a diagnosable error rather than silently yielding `undefined`.
+- Nothing imports `secrets.generated.ts`; it only has to be part of the compilation. **Never hand-edit it** — the CLI overwrites it, and the typegen watcher deliberately ignores it so regenerating doesn't loop.
+- Deleting a secret narrows the type, so stale references stop compiling instead of failing at invocation.
+
 ## How resolution works
 
-`ctx.getSecret(name)` returns `string | undefined`. It resolves in this order:
+`ctx.Secrets.<NAME>` resolves in this order:
 
 1. The host-provided secret bag delivered with the invocation.
-2. `process.env[name]` as a fallback.
+2. `process.env[NAME]` as a fallback.
 
 ## Setting secrets
 
@@ -48,7 +59,7 @@ See [Managing secrets](../cli/secrets.md) for the full `npx rayfin secret` comma
 ## Secrets in local development
 
 The host-provided secret bag is only present for deployed invocations.
-When you debug locally with `npx rayfin dev functions apply`, add the same key under `Values` in `rayfin/functions/local.settings.json` so it flows into `process.env` and is picked up by the `getSecret` fallback:
+When you debug locally with `npx rayfin dev functions apply`, add the same key under `Values` in `rayfin/functions/local.settings.json` so it flows into `process.env` and is picked up by the fallback:
 
 ```jsonc
 {
@@ -64,7 +75,24 @@ When you debug locally with `npx rayfin dev functions apply`, add the same key u
 `local.settings.json` is git-ignored, so these values stay on your machine.
 See [Secrets in local development](../cli/secrets.md#using-secrets-in-local-development) for more.
 
+## The deprecated `ctx.getSecret()`
+
+`ctx.getSecret(name)` returns `string | undefined` and is **deprecated** — it is flagged by `@typescript-eslint/no-deprecated`, which the scaffolded ESLint config reports as an error.
+
+```ts
+// Before
+const apiKey = ctx.getSecret("THIRD_PARTY_API_KEY");
+if (!apiKey) {
+  throw new Error("Missing THIRD_PARTY_API_KEY secret.");
+}
+
+// After
+const apiKey = ctx.Secrets.THIRD_PARTY_API_KEY;
+```
+
+It remains valid for a value deliberately **not** modelled in `rayfin.yml` — a host-injected environment variable, for example. Suppress the lint at that one call site rather than project-wide.
+
 ## Best practices
 
-- Prefer secrets set with `npx rayfin secret set <NAME>` as the source of truth for deployed functions.
+- Declare every secret with `npx rayfin secret set <NAME>` and read it from `ctx.Secrets` — never hard-code a secret name string.
 - Use the `process.env` fallback only for local debugging — do not make it your primary production secret source.

package/assets/docs/functions/writing-functions.md

@@ -26,11 +26,11 @@ udf.func(
 
 `udf.func()` takes three arguments:
 
-| Argument      | Description                                                                                   |
-| ------------- | --------------------------------------------------------------------------------------------- |
-| `name`        | The function name. Becomes the invocation route and the key in your generated schema.         |
-| `fn`          | The handler. Its parameter and return types are read by [typegen](./typegen.md).              |
-| `connections` | Optional array of connection bindings. Pass `[]` when the function does not use a connection. |
+| Argument      | Description                                                                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | The function name. Becomes the invocation route and the key in your generated schema.                                                        |
+| `fn`          | The handler. Its parameter and return types are read by [typegen](./typegen.md).                                                             |
+| `connections` | Optional array of connection bindings. Pass `[]` — audience-scoped connections are declared in the context annotation instead. |
 
 The handler's typed parameters and return type are extracted into `types.ts` so the frontend can call the function type-safely.
 `Promise<T>` return types are unwrapped to `T` in the generated schema.
@@ -38,7 +38,8 @@ The handler's typed parameters and return type are extracted into `types.ts` so
 ## Accessing data and request context
 
 To read your data, tokens, or logging from inside a function, declare a `RayfinContext` parameter.
-Pass your app schema as a generic (`RayfinContext<AppSchema>`) — the same schema you use with `RayfinClient<AppSchema>` — for a fully typed data client:
+Pass your app schema as the first generic (`RayfinContext<AppSchema>`) — the same schema you use with `RayfinClient<AppSchema>` — for a fully typed data client.
+A second, optional generic declares the external audiences the function may use; see [Connecting to external resources](./connections/index.md).
 
 ```ts
 import {
@@ -67,14 +68,16 @@ udf.func(
 
 ### `RayfinContext` API
 
-| Member                       | Description                                                                                                                                                                                                                                                             |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx.getDataClient()`        | Returns the typed entity data client. Query with `.select([...]).where(...).execute()`, the same chain as `client.data.<Entity>` on the frontend. Typed when a generic is supplied; untyped (`Record<string, any>`) otherwise.                                          |
-| `ctx.getSecret(name)`        | Returns a secret value, or `undefined` when unset. See [Secrets](./secrets.md).                                                                                                                                                                                         |
-| `ctx.getToken(audienceType)` | Returns the delegated OBO access token (a `string`) for an external resource. Only works for an audience you declared with `udf.connection({ audienceType })` in the third argument — throws otherwise. See [Connecting to external resources](./connections/index.md). |
-| `ctx.baseUrl`                | The Rayfin endpoint URL (readonly).                                                                                                                                                                                                                                     |
-| `ctx.accessToken`            | The auth token for the current request (readonly).                                                                                                                                                                                                                      |
-| `ctx.publishableKey`         | The Rayfin publishable key (readonly).                                                                                                                                                                                                                                  |
+| Member                | Description                                                                                                                                                                                                                   |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.getDataClient()` | Returns the Rayfin DB entity data client using the invocation's Rayfin token and the caller's identity and database permissions. Query with `.select([...]).where(...).execute()`, as with `client.data.<Entity>` on the frontend. Typed when a schema generic is supplied; otherwise untyped. |
+| `ctx.Secrets`         | Secret values keyed by the names declared in `rayfin.yml`, each typed `string`. Reading an undeclared name is a compile error. See [Secrets](./secrets.md).                                                                      |
+| `ctx.Tokens`          | Resource access tokens keyed by audience, each typed `string`. Narrowed to the declared audiences; deployed Functions use the app identity. See [Connecting to external resources](./connections/index.md), including local development. |
+| `ctx.baseUrl`         | The Rayfin endpoint URL (readonly).                                                                                                                                                                                           |
+| `ctx.accessToken`     | The invocation's Rayfin token, used for caller-scoped Rayfin DB access (readonly). Not an external resource token from `ctx.Tokens`.                                                                                          |
+| `ctx.publishableKey`  | The Rayfin publishable key (readonly).                                                                                                                                                                                        |
+
+`ctx.getSecret(name)` and `ctx.getToken(audienceType)` are the deprecated predecessors of `ctx.Secrets` and `ctx.Tokens`. They still work, but are flagged by `@typescript-eslint/no-deprecated`.
 
 Use `console.log(...)` / `console.error(...)` for logging.
 
@@ -100,24 +103,25 @@ udf.func(
 
 ## Connecting to external resources
 
-To call external Azure or Fabric resources (SQL, Storage, Key Vault, Cosmos DB, and more) from inside a function, declare a connection in the third argument of `udf.func()` and read a delegated token from the context:
+To call external Azure or Fabric resources (SQL, Storage, the Fabric REST API, and more) from inside a function, declare the audience in the `RayfinContext` annotation and read the token from `ctx.Tokens`:
 
 ```ts
 import { AudienceType } from "@microsoft/fabric-user-data-functions";
 
 udf.func(
-  "readSecret",
-  async (ctx: RayfinContext, secretName: string): Promise<string> => {
-    const token = ctx.getToken(AudienceType.KeyVault);
+  "accessStorage",
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
+  ): Promise<void> => {
+    const token = ctx.Tokens.Storage;
     // Use `token` with the resource's SDK or REST API.
-    return secretName;
   },
-  [udf.connection({ audienceType: AudienceType.KeyVault })],
+  [],
 );
 ```
 
-The runtime exchanges the caller's identity for a resource-scoped token, so the function acts **as the calling user**.
-See [Connecting to external resources](./connections/index.md) for the full model, the list of supported audiences, and per-resource guides.
+The annotation is the declaration — listing the audience is what registers the connection binding, so nothing goes in the third argument.
+See [Application authentication](./index.md#application-authentication) for configuration and identities, and [Connecting to external resources](./connections/index.md) for supported audiences and per-resource guides.
 
 ## Importing data entities
 
@@ -135,6 +139,6 @@ import type { Entry } from "../../data/Entry.js";
 
 - Always register functions with `udf.func(name, handler, [])` — do not export bare functions.
 - Use `RayfinContext<AppSchema>` for type-safe data access. Bare `RayfinContext` still works but gives no type safety on `getDataClient()`.
-- Only call `ctx.getToken(audienceType)` for an audience you declared with `udf.connection({ audienceType })` in the third argument of `udf.func()` — calling it for an undeclared audience throws.
+- Declare external audiences in the context annotation (`RayfinContext<AppSchema, AudienceType.X>`) and read them with `ctx.Tokens.X` — an audience you did not declare is a compile error.
 - A function must return a value or `void`. Throwing an error surfaces to the caller as an invocation failure carrying the error message.
 - Use `import type` for data entity imports; never a runtime `import`.

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

@@ -76,7 +76,7 @@ The root build orders shared, data, and frontend work.
 Focused package commands use npm's workspace selector, such as `npm run -w @rayfin-app/frontend test`.
 
 The base workspace does not contain `packages/functions`, and `services.functions.enabled` is `false`.
-Running `npm run pack:add -- functions` creates the stable functions package, enables its service, composes its build into root orchestration, and installs dependencies from the workspace root.
+Running `npm run pack:add -- functions` creates the stable functions package, enables its service with `auth.type: application`, composes its build into root orchestration, and installs dependencies from the workspace root.
 Capability packs do not use a nested functions lockfile or nested install.
 
 ### Universal App service paths
@@ -102,6 +102,8 @@ services:
 Rayfin resolves each `path` from the application root, then runs that service's `buildCommand` with the service directory as its working directory.
 The static-hosting folder is therefore `packages/frontend/dist`, not a root `dist` directory.
 After the functions pack is applied, functions uses `path: packages/functions` with its package-local `npm run build`.
+Enabled Functions require explicit `services.functions.auth.type: application`; the disabled base configuration above may omit `auth`.
+See [Application authentication](../functions/index.md#application-authentication) for existing-app configuration and downstream permissions.
 
 The Project Rayfin repository keeps this Builder-facing workspace under `samples/universal-app/template`.
 Its parent `samples/universal-app` is only a Rush validation harness that generates an ephemeral target and links that target to repository-local SDK packages.

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.1756",
+  "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": [

package/assets/docs/functions/connections/add-work-iq.md

@@ -1,39 +0,0 @@
----
-sidebar_position: 6
----
-
-# Add WorkIQ
-
-Call the **WorkIQ** service from a function **as the signed-in user**, using `AudienceType.WorkIQ`.
-
-Provide the **WorkIQ endpoint** you are calling. The token is a standard bearer token — send it with `fetch`:
-
-```ts
-import {
-  UserDataFunctions,
-  AudienceType,
-  type RayfinContext,
-} from "@microsoft/fabric-user-data-functions";
-
-const udf = new UserDataFunctions();
-
-// Use your real WorkIQ endpoint.
-const WORKIQ_ENDPOINT = "https://workiq.svc.cloud.microsoft/...";
-
-udf.func(
-  "callWorkIq",
-  async (ctx: RayfinContext): Promise<unknown> => {
-    const token = ctx.getToken(AudienceType.WorkIQ);
-    const res = await fetch(WORKIQ_ENDPOINT, {
-      headers: { Authorization: `Bearer ${token}` },
-    });
-    if (!res.ok) {
-      throw new Error(`WorkIQ returned ${res.status}`);
-    }
-    return res.json();
-  },
-  [udf.connection({ audienceType: AudienceType.WorkIQ })],
-);
-```
-
-See [Connecting to external resources](./index.md) for the shared connection model.