@microsoft/rayfin-guide 1.36.0-alpha.1593 → 1.36.0-alpha.1601

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

@@ -0,0 +1,38 @@
+---
+sidebar_position: 3
+---
+
+# up functions deploy
+
+Build, package, and deploy your functions to the remote Rayfin item.
+
+```bash
+npx rayfin up functions deploy [-v | --verbose] [--skip-build] [--json]
+```
+
+## When to use it
+
+`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.
+
+## 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`.
+
+## Options
+
+| Option          | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `-v, --verbose` | Print detailed build and deploy output.                        |
+| `--skip-build`  | Deploy the already-built output without rebuilding first.      |
+| `--json`        | Emit machine-readable JSON instead of human-readable progress. |
+
+## What it does
+
+1. Builds and packages the functions project (unless `--skip-build`).
+2. Deploys the package to the remote Rayfin item resolved from your active deployment.
+
+## Related
+
+- [`functions init`](./init.md) — scaffold and enable functions.
+- [`dev functions apply`](./dev-apply.md) — run and debug functions locally before deploying.
+- [Managing Secrets](../secrets.md) — push secrets that deployed functions read via `ctx.getSecret`.

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

@@ -0,0 +1,62 @@
+---
+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.
+
+```bash
+npx rayfin dev functions apply [--port <port>] [--inspect-port <port>] [--no-debug] [--no-emit-env]
+```
+
+## Prerequisites
+
+- **Functions must be enabled** — run [`npx rayfin functions init`](./init.md) first so `services.functions.enabled` is set in `rayfin.yml`.
+- **Node.js ≥ 20** and **Azure Functions Core Tools** must be installed. The command verifies these and, with your consent, installs Core Tools if missing.
+- **An active deployment** — run `npx rayfin up` at least once so a remote endpoint and publishable key exist to resolve against.
+
+## Options
+
+| Option                  | Default | Description                                                                   |
+| ----------------------- | ------- | ----------------------------------------------------------------------------- |
+| `--port <port>`         | `7071`  | Port for the local function host. Auto-shifts to the next free port if taken. |
+| `--inspect-port <port>` | `9229`  | Port for the Node inspector (debugger).                                       |
+| `--no-debug`            | off     | Disable the inspector / attach support.                                       |
+| `--no-emit-env`         | off     | Skip regenerating the framework `.env.local`.                                 |
+
+## What it does
+
+1. Gates on `services.functions.enabled` and checks prerequisites (Node, Core Tools).
+2. Resolves the active deployment and publishable key.
+3. Writes `rayfin/functions/local.settings.json` (environment, API URL, publishable key, workspace/item ids, inspector flag when debugging).
+4. Upserts `RAYFIN_PUBLIC_FUNCTIONS_URL` into `rayfin/.env` and regenerates the framework `.env.local` (unless `--no-emit-env`).
+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.
+
+Press `Ctrl+C` to stop the host and watcher.
+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.
+
+## 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).
+
+## Next step
+
+When your functions are working locally, deploy them:
+
+```bash
+npx rayfin up            # deploys everything, including functions
+# or, to re-run only functions:
+npx rayfin up functions deploy
+```
+
+See [`up functions deploy`](./deploy.md).

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

@@ -0,0 +1,41 @@
+---
+sidebar_position: 4
+---
+
+# Functions
+
+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)).
+
+Each command has its own reference page:
+
+- [`functions init`](./init.md) — scaffold `rayfin/functions/`, install dependencies, and seed `types.ts`.
+- [`dev functions apply`](./dev-apply.md) — run the local function host with a live typegen watcher for development and debugging.
+- [`up functions deploy`](./deploy.md) — build, package, and deploy functions to the remote Rayfin item.
+
+## The development loop
+
+```text
+functions init  →  write UDFs in src/function_app.ts  →  dev functions apply  →  up
+   (scaffold)          (typegen keeps types.ts fresh)       (local host+debug)    (deploy)
+```
+
+1. **`npx rayfin functions init`** scaffolds the project, installs dependencies, runs a one-shot typegen, and enables the service in `rayfin.yml`.
+2. **Write functions** with `udf.func(name, handler, [])` in `rayfin/functions/src/function_app.ts`. The CLI parses these calls and generates `rayfin/functions/src/types.ts` (the `AppFunctionsSchema`) — never hand-edit it.
+3. **`npx rayfin dev functions apply`** starts the local Azure Functions host, keeps a visible `[typegen]` watcher running so `types.ts` stays in sync as you edit, and publishes its URL for local frontend routing.
+   Bundled Vite apps use that URL through the same-origin `/.rayfin/api/<name>` route when you run the frontend separately.
+4. **`npx rayfin up`** deploys everything, including functions. To re-run only the functions step, use [`npx rayfin up functions deploy`](./deploy.md).
+
+> **`npx rayfin dev` vs. `npx rayfin dev functions apply`:** Prefer `npx rayfin dev` for normal local development because it runs your functions alongside the frontend and backend. Use `npx rayfin dev functions apply` when you want to run **only** the functions host — with its typegen watcher and debugger — without starting the frontend/static app.
+
+## Where functions state lives
+
+- `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`).
+
+## 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).

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

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+---
+
+# functions init
+
+Scaffold a Rayfin functions project under `rayfin/functions/`, enable the functions service, install dependencies, build, and generate the initial types.
+
+```bash
+npx rayfin functions init [directory] [--force]
+```
+
+## Prerequisites
+
+Run this from a directory that already contains a `rayfin/` project (i.e. you have already run `npx rayfin init`). If `rayfin/` is missing, the command errors and asks you to initialize the app first.
+
+## Arguments and options
+
+| Name          | Description                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| `[directory]` | Project directory to initialize in. Defaults to the current directory (`.`).                         |
+| `--force`     | Overwrite an existing `rayfin/functions/` scaffold. Without it, existing function code is preserved. |
+
+## 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'`.
+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.
+
+## Scaffolded structure
+
+```text
+rayfin/
+  functions/
+    src/
+      function_app.ts   # register UDFs here with udf.func(...)
+      types.ts          # generated AppFunctionsSchema — do not hand-edit
+    host.json
+    local.settings.json
+    package.json
+    tsconfig.json
+```
+
+## Re-running
+
+`functions init` is safe to re-run:
+
+- **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).
+
+## Next step
+
+Start the local host and typegen watcher:
+
+```bash
+npx rayfin dev functions apply
+```
+
+See [`dev functions apply`](./dev-apply.md).

package/assets/docs/cli/index.md

@@ -61,9 +61,29 @@ For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Buil
 | `npx rayfin up` | Deploy the project to Microsoft Fabric. If you are not signed in, the CLI launches an interactive login flow. Use `-t, --tenant <id>` when your account spans multiple tenants, `-w, --workspace <name>` for a Fabric workspace display name, `-n, --dry-run` to preview without API calls, and `-v, --verbose` for detailed output. Pass `--encryption-fallback-enabled` only when login fails with a keychain error to allow plaintext token storage on systems without OS credential storage, such as some Linux distros, dev containers, and Codespaces. Use `--exclude-services staticHosting` to skip static content build/package/deploy while leaving runtime settings untouched — useful during local development when Vite serves the frontend. Applies runtime settings, database configuration, and static content when enabled. |
 | `npx rayfin up status` | Display the status of the Fabric deployment (add `--json` for machine-readable output). |
 | `npx rayfin up db apply` | Generate and apply DAB configuration to the remote Rayfin item. Add `--force` to allow changes that may cause data loss. |
-| `npx rayfin up secrets apply` | Read secrets from `rayfin/.env` file (prefixed with `RAYFIN_SECRET_`) and securely apply them to the remote Rayfin item workload. Validates that secrets are persisted. Use `--env-file <path>` to specify a custom .env file location. |
 | `npx rayfin up staticapp deploy` | Build, package, and deploy static content to the remote Rayfin item. Add `--skip-build` to deploy existing build output without rebuilding. |
 
+### Functions
+
+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, privileged data access, and server-side validation. See [Functions](./functions/index.md) for the full guide.
+
+| 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 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). |
+
+### 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.
+
+| Command | Description |
+| --- | --- |
+| `npx rayfin secret set <name>` | Set a single secret on the deployed item with a masked prompt. Use `--stdin` for non-interactive input and `--describe="..."` to record a description in `rayfin.yml`. |
+| `npx rayfin secret set --env-file <path>` | Bulk-set every `KEY=VALUE` entry from a dotenv file. |
+| `npx rayfin secret list` | List secret names and their created/updated timestamps (values are never returned). |
+| `npx rayfin secret delete <name>` | Delete a secret from the deployed item. Add `-y, --yes` to skip the confirmation prompt. |
+
 ## Update the CLI
 
 To get the latest version of the Rayfin CLI and its dependencies:

package/assets/docs/cli/secrets.md

@@ -4,193 +4,168 @@ sidebar_position: 50
 
 # Managing Secrets
 
-The Rayfin CLI provides secure secret management for your remote deployments.
-Secrets are encrypted and stored securely in your Rayfin item workload.
+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)`.
 
-## Overview
+Manage secrets with the `npx rayfin secret` command group:
 
-Use the `rayfin up secrets apply` command to manage application secrets for your remote deployment.
-Secrets are read from your `.env` file, securely transmitted to your workload, encrypted, and validated.
+| Command                                   | Description                                          |
+| ----------------------------------------- | ---------------------------------------------------- |
+| `npx rayfin secret set <name>`            | Set one secret (masked prompt or `--stdin`).         |
+| `npx rayfin secret set --env-file <path>` | Bulk-set every `KEY=VALUE` entry from a dotenv file. |
+| `npx rayfin secret list`                  | List secret names and timestamps (never values).     |
+| `npx rayfin secret delete <name>`         | Delete a secret.                                     |
 
-## Setting up secrets
+## Prerequisite: deploy first
 
-### 1. Define secrets in `.env`
-
-Create a `rayfin/.env` file with secrets prefixed using `RAYFIN_SECRET_`:
+Secrets live on the remote Rayfin item, so you must deploy before managing them:
 
 ```bash
-# rayfin/.env
-RAYFIN_SECRET_API_KEY=sk-prod-abc123xyz789
-RAYFIN_SECRET_DATABASE_PASSWORD=secure-db-pass-123
-RAYFIN_SECRET_AUTH_TOKEN=token-abcdefg-hijklmn
-RAYFIN_SECRET_OPENAI_KEY=sk-openai-your-key-here
+npx rayfin up
 ```
 
-> **Secret naming:** Secret names must follow the `RAYFIN_SECRET_` prefix convention.
-> The part after the prefix becomes your secret name.
-> For example, `RAYFIN_SECRET_API_KEY` creates a secret named `API_KEY`.
+Every `secret` command resolves the remote endpoint from your active deployment. If none exists, the CLI stops with:
+
+```text
+❌ No remote endpoint configured
+   Run 'npx rayfin up' first to deploy your item to Fabric.
+```
 
-### 2. Deploy your item
+## Setting a secret
 
-Before managing secrets, deploy your project to Microsoft Fabric:
+By default, `secret set` prompts for the value with masked input:
 
 ```bash
-npx rayfin up
+npx rayfin secret set OPENAI_KEY
+# ? Enter secret value for "OPENAI_KEY" ********
 ```
 
-This creates your Rayfin item and sets up the workload endpoint.
-
-### 3. Apply secrets
-
-Apply your secrets to the remote workload:
+For non-interactive use (CI, scripts), pipe the value in with `--stdin`:
 
 ```bash
-npx rayfin up secrets apply
+echo "sk-openai-your-key-here" | npx rayfin secret set OPENAI_KEY --stdin
 ```
 
-The CLI will:
-1. Read your `rayfin/.env` file
-2. Extract all `RAYFIN_SECRET_*` variables
-3. Securely send each secret to your workload
-4. Encrypt and persist the secrets
-5. Validate that all secrets were successfully saved
-
-### 4. Verify secrets
+### Recording a description in `rayfin.yml`
 
-After running the apply command, you'll see output confirming each secret:
+Use `--describe` to record a human-readable description alongside the secret's metadata in `rayfin/rayfin.yml` (the value itself is never written to `rayfin.yml`). The flag **must** use the `=` syntax:
 
-```text
-🔐 Acquiring authentication token...
-✓ Token acquired
-📤 Sending 4 secret(s) to workload...
-✓ Secrets sent to workload (4 persisted)
-✅ Validating secrets persisted to workload...
-✓ All secrets validated
-
-✨ Secrets applied successfully (4/4)
-  ✓ API_KEY
-  ✓ DATABASE_PASSWORD
-  ✓ AUTH_TOKEN
-  ✓ OPENAI_KEY
+```bash
+npx rayfin secret set OPENAI_KEY --describe="OpenAI API key for the chat function"
 ```
 
-## Advanced usage
+Passing `--describe "..."` with a space is rejected — always use `--describe="..."`.
 
-### Custom .env file location
+## Bulk-setting from a file
 
-If your secrets are in a non-standard location, use the `--env-file` option:
+To set many secrets at once, keep them in a dotenv file and point `secret set` at it with `--env-file`:
 
 ```bash
-npx rayfin up secrets apply --env-file ./config/secrets.env
+# rayfin/.env.secrets
+OPENAI_KEY=sk-openai-your-key-here
+DATABASE_PASSWORD=secure-db-pass-123
+AUTH_TOKEN=token-abcdefg-hijklmn
 ```
 
-### JSON output
-
-For automation or scripting, use `--json` for machine-readable output:
-
 ```bash
-npx rayfin up secrets apply --json
+npx rayfin secret set --env-file rayfin/.env.secrets
 ```
 
-Output example:
-
-```json
-{
-  "status": "success",
-  "message": "All secrets applied and validated",
-  "secretsCount": 4,
-  "persisted": 4,
-  "validated": true,
-  "secrets": [
-    {
-      "name": "API_KEY",
-      "id": "secret-123",
-      "createdAt": "2026-04-17T10:30:00Z"
-    }
-  ]
-}
-```
+Every `KEY=VALUE` line becomes a secret named `KEY` — there is **no prefix convention**; the key is used verbatim. Blank lines and `#` comments are ignored, and surrounding single or double quotes are stripped from values. Do not pass a `<name>` together with `--env-file`, and do not combine `--env-file` with `--stdin`.
 
-### Verbose logging
+> **Keep secret files out of version control.** Add your secrets file to `.gitignore` — it is for authoring only, never committed:
+>
+> ```bash
+> echo "rayfin/.env.secrets" >> .gitignore
+> ```
 
-Enable detailed logging for debugging:
+## Listing secrets
 
 ```bash
-npx rayfin up secrets apply --verbose
+npx rayfin secret list
 ```
 
-### Non-interactive mode
+Only names and created/updated timestamps are returned — values are never read back:
 
-Use `-y` or `--yes` to skip confirmation prompts:
+```text
+📋 Secrets (3):
 
-```bash
-npx rayfin up secrets apply -y
+  Name:         OPENAI_KEY
+  Created:      4/17/2026, 10:30:00 AM
+  Last Updated: 4/17/2026, 10:30:00 AM
 ```
 
-## Secret handling and security
+## Deleting a secret
 
-### Encryption
+```bash
+npx rayfin secret delete OPENAI_KEY          # prompts for confirmation
+npx rayfin secret delete OPENAI_KEY --yes    # skips the prompt (-y)
+```
 
-Secrets are transmitted over HTTPS with encrypted payloads.
-The workload endpoint encrypts and persists secrets securely.
-Secrets are never logged or displayed after being sent to the workload.
+Deleting a secret that does not exist reports a not-found error — run `npx rayfin secret list` to see what is currently stored.
 
-### Best practices
+## Reading secrets from functions
 
-1. **Use `.env` files for local development only** – Never commit `.env` files to version control.
-   Add `.env` to your `.gitignore`:
+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:
 
-   ```bash
-   echo "rayfin/.env" >> .gitignore
-   ```
+```ts
+udf.func("summarize", async (ctx, input: { text: string }) => {
+  const apiKey = ctx.getSecret("OPENAI_KEY");
+  // ... call the API with apiKey
+});
+```
 
-2. **Use environment variables for CI/CD** – In automated environments, set `RAYFIN_SECRET_*` variables directly:
+## Using secrets in local development
 
-   ```bash
-   export RAYFIN_SECRET_API_KEY=prod-key-from-vault
-   npx rayfin up secrets apply
-   ```
+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`:
 
-3. **Rotate secrets regularly** – Re-run `rayfin up secrets apply` after updating secret values in your `.env` file.
+```json
+{
+  "IsEncrypted": false,
+  "Values": {
+    "OPENAI_KEY": "sk-local-dev-key"
+  }
+}
+```
 
-4. **Separate development and production secrets** – Use different `.env` files or environment variables for each environment.
+`npx rayfin dev functions apply` **merges** its own CLI-managed values into `local.settings.json` and preserves any keys you add, so your local secrets survive re-runs. Keep `local.settings.json` out of version control — it is for local development only.
 
-## Troubleshooting
+## Automation and JSON output
 
-### No secrets found
+Every `secret` command accepts the global `--json` flag for machine-readable output and `--verbose` for detailed logging:
+
+```bash
+npx rayfin secret list --json
+npx rayfin secret set OPENAI_KEY --stdin --json < key.txt
+```
 
-If you see "No secrets found in .env file", verify:
+## Security notes
 
-- Your `.env` file exists at `rayfin/.env`
-- Variables are prefixed with `RAYFIN_SECRET_`
-- The file is readable by the CLI process
+- Secrets are transmitted over HTTPS and encrypted at rest on the workload. They are never logged or displayed after being sent.
+- `npx rayfin secret list` returns only names and timestamps — never values.
+- Use separate secret values per environment, and rotate them by re-running `npx rayfin secret set` with the new value.
 
-### Authentication failed
+## Troubleshooting
 
-If you see "Failed to acquire authentication token":
+### No remote endpoint configured
 
-- Run `npx rayfin login` to sign in
-- Check that you have valid Entra ID credentials
-- On containers or restricted environments, use `--encryption-fallback-enabled` or set `RAYFIN_ENCRYPTION_FALLBACK_ENABLED=true`
+Run `npx rayfin up` first to deploy your item, then retry. Secrets cannot be managed before an initial deployment exists.
 
-### Validation inconclusive
+### Authentication failed
 
-If some secrets fail validation:
+If acquiring a token fails:
 
-- Check your network connection to Fabric
-- Verify the workload endpoint is running and healthy
-- Run `npx rayfin up status` to confirm deployment health
-- Re-run `npx rayfin up secrets apply` to retry
+- Run `npx rayfin login` to sign in and confirm you have valid Entra ID credentials.
+- On containers or restricted environments without an OS keychain, pass `--encryption-fallback-enabled` to allow plaintext token storage.
 
-### Permission denied
+### Secret not found on delete
 
-If you see permission errors:
+If `secret delete` reports the secret was not found:
 
-- Ensure you're authenticated with an account that has access to the Fabric workspace
-- Verify you have the correct workspace selected
-- Run `npx rayfin login --select` to choose a different account/tenant
+- It may already be deleted — run `npx rayfin secret list` to confirm.
+- Secret management may not be enabled for the item; verify the deployment with `npx rayfin up status`.
 
 ## See also
 
+- [Functions](./functions/index.md) — read secrets from server-side functions with `ctx.getSecret`.
 - [CLI quickstart](./quickstart.md)
 - [Environment configuration](./env-interpolation.md)

package/assets/docs/functions/connections/add-ado.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 5
+---
+
+# Add Azure DevOps
+
+Call the [Azure DevOps REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/) from a function **as the signed-in user**, using `AudienceType.ADO`.
+
+Provide your Azure DevOps **organization** (and project, if the call needs one) — e.g. `https://dev.azure.com/<org>`. 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 organization URL.
+const ORG = "https://dev.azure.com/<org>";
+
+udf.func(
+  "listProjects",
+  async (ctx: RayfinContext): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.ADO);
+    const res = await fetch(`${ORG}/_apis/projects?api-version=7.1`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`Azure DevOps returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.ADO })],
+);
+```
+
+See [Connecting to external resources](./index.md) for the shared connection model.