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

package/assets/docs/{experimental/cli → cli}/connectors/add.md

@@ -8,6 +8,8 @@ sidebar_position: 2
 npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id> [--name <name>] [--operations <ops>]
 ```
 
+> **`kusto` authoring is held in this release**, so `connector add --type kusto` refuses before writing anything. Kusto examples below describe the authoring path for when it ships. See [Connectors](./index.md) for what a project that already declares Kusto can still do.
+
 `connector add` declares a connector in `rayfin/rayfin.yml` and scaffolds its supporting files.
 
 The CLI verifies the Fabric item, derives a connector `name` from the item's display name (override with `--name`), writes the entry to `rayfin.yml`, and scaffolds `rayfin/connectors/<name>/schema.ts`. For Category A connectors it also runs schema discovery and writes `rayfin/connectors/<name>/metadata.json` so a subset of entities can be generated later.

package/assets/docs/{experimental/cli → cli}/connectors/category-a-entities.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 5
 ---
 
 # Category A — GraphQL entity connectors

package/assets/docs/{experimental/cli → cli}/connectors/category-b-function-bridge.md

@@ -1,10 +1,14 @@
 ---
-sidebar_position: 7
+sidebar_position: 6
 ---
 
 # Category B — function-bridge connectors
 
-Reference for `kusto` (Fabric KQL Database) and `fabric-semanticmodel` (Power BI semantic model).
+Reference for `fabric-semanticmodel` (Power BI semantic model) and the experimental `kusto` (the **Eventhouse** connector — a Fabric Eventhouse KQL Database).
+Eventhouse is the Fabric product name; `kusto` is the type id you pass to `--type`, and KQL is its query language.
+
+> **`kusto` authoring is held in this release**, so `connector add --type kusto` refuses and search omits KQL databases. Everything below about `kusto` stays accurate for a project that **already declares** one — which still validates, deploys and invokes — and describes the authoring path for when it ships. Only `fabric-semanticmodel` can be added today. See [Connectors](./index.md).
+
 A Category B connector is a named-operation surface backed by a small, platform-owned function (UDF).
 The Builder never writes or sees the function code.
 
@@ -17,8 +21,8 @@ For the entity-generating types (`fabric-sqlanalytics`, `fabric-warehouse`, `fab
 
 | Type | Operations | Query language | Auth |
 | --- | --- | --- | --- |
-| `kusto` | `executeQuery`, `executeCommand` | KQL | `delegated` only |
 | `fabric-semanticmodel` | `executeQuery` | DAX | `delegated` only |
+| `kusto` (**experimental**) | `executeQuery`, `executeCommand` | KQL | `delegated` only |
 
 Both are pinned to an adapter version (`version: '1'` today).
 Delegated authentication runs every call as the signed-in user through the on-behalf-of flow.
@@ -78,7 +82,7 @@ export const connectorConfig = {
 } as const satisfies ConnectorConfig;
 ```
 
-### Kusto bakes cluster routing into the generated file
+### The Eventhouse scaffold bakes cluster routing into the generated file
 
 `connector add --type kusto` resolves the KQL Database's cluster query endpoint and database name from `(workspaceId, itemId)` at add time and writes both into the generated `connectorConfig`:
 
@@ -100,11 +104,11 @@ Three names appear here and nowhere else:
 - `databaseName` — the resolved KQL database name.
 - `KustoConnectorConfig` — the Kusto-specific config type these two keys satisfy, exported from `@microsoft/rayfin-connector-kusto` rather than `@microsoft/rayfin-connectors`.
 
-These keys live only in the file the Kusto scaffold writes.
+These keys live only in the file the Eventhouse scaffold writes.
 They are **not** part of the shared `rayfin.yml` schema — never write a cluster URI or database name into `rayfin.yml`, and never send either value from app code.
 If the resolved values look wrong, re-add the connector rather than editing the generated file; the values come from Fabric, not from anything you can fix by hand.
 
-The Kusto scaffold imports both its marker and `KustoConnectorConfig` from `@microsoft/rayfin-connector-kusto`, so it does not import `@microsoft/rayfin-connectors` at all.
+The Eventhouse scaffold imports both its marker and `KustoConnectorConfig` from `@microsoft/rayfin-connector-kusto`, so it does not import `@microsoft/rayfin-connectors` at all.
 
 ## Install the packages the generated file imports
 
@@ -113,7 +117,7 @@ The Kusto scaffold imports both its marker and `KustoConnectorConfig` from `@mic
 ```bash
 # Shape only. Use the version connector add printed, not this one.
 
-# kusto — marker and config type both come from this one package
+# kusto (experimental) — marker and config type both come from this one package
 npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha
 
 # fabric-semanticmodel
@@ -136,7 +140,7 @@ This is not optional: the runtime is what injects the generated routing and deco
 Key the runtime map by the same connector name, and call the factory once per connector:
 
 ```ts
-import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
 import { kusto } from '@microsoft/rayfin-connector-kusto';
 import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
 import {
@@ -174,11 +178,11 @@ const client = new ConnectorsRayfinClient<
 );
 ```
 
-`ConnectorsRayfinClient` is experimental — import it only from the `@microsoft/rayfin-client/experimental` subpath, never the stable `@microsoft/rayfin-client` entry.
+`ConnectorsRayfinClient` is stable — import it from the main `@microsoft/rayfin-client` entry.
 
 The connector key must be identical in four places: the `name` in `rayfin.yml`, the property in `AppConnectorsSchema`, the property in the `connectors` option, and the property in the runtime map.
 
-## Calling a Kusto connector
+## Calling an Eventhouse connector
 
 Correlation ids are not part of the response body — the connector function relays the Kusto bytes untouched — so generate the `clientRequestId` yourself and pass the same value to both `executeQuery` and `toQueryResult`:
 
@@ -208,6 +212,28 @@ Successful results contain `tables` plus the `clientRequestId` you passed in (em
 Each table contains named typed `columns` and row-major `rows`.
 Error results contain `error.message` and an optional `error.code`.
 
+### Building queries safely
+
+`executeQuery` takes its KQL in `query` and `executeCommand` takes its command in `command`; neither operation binds parameters — `ExecuteQueryInput` exposes only `query` and `clientRequestId`, and `ExecuteCommandInput` only `command` and `clientRequestId`. Every user value you place in that text runs as KQL, so treat all user input as unsafe and never interpolate it raw.
+
+- **Identifiers** (table, column, function names): map the user's choice through a fixed allow-list to a known-good constant. Never build an identifier from user text.
+- **Values**: serialize each as a typed KQL literal. Validate numbers (for example with `Number.isFinite`), parse datetimes to ISO 8601 and wrap them in `todatetime(...)`, and for strings escape `\` and `"` and reject control characters. This repo ships no KQL encoder; generic SQL or JSON escaping does not make KQL safe.
+
+```ts
+const TABLES = { events: 'Events', logs: 'Logs' } as const;
+const table = TABLES[userTable];
+if (!table) throw new Error('unknown table');
+
+// Typed KQL string literal: escape backslash and double-quote, reject control chars.
+function kqlString(value: string): string {
+  if (/[\u0000-\u001F]/.test(value)) throw new Error('control character in value');
+  return '"' + value.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+// kqlString('contoso "42"')  ->  "contoso \"42\""
+
+const query = `${table} | where DeviceId == ${kqlString(userDeviceId)} | take 200`;
+```
+
 ### Management commands
 
 `executeCommand` runs a Kusto management (control) command — the command text starts with a leading dot.
@@ -240,10 +266,10 @@ Run `rayfin docs search "resultSetRowCountLimit"` for version-locked details, si
 `rayfin connector invoke <name> <operation>` is the loop for Category B.
 See [`connector invoke`](./invoke.md) for payload input, transports, token handling, and the output contract.
 
-- `connector inspect` supports `fabric-semanticmodel` but **not** `kusto` — a `kusto` connector errors with `Unsupported connector type: kusto`.
+- `connector inspect` supports `fabric-semanticmodel` but **not** experimental `kusto` — a `kusto` connector errors with `Unsupported connector type: kusto`.
   There is no ad-hoc query path for Kusto connectors today.
 - `connector invoke` on `fabric-semanticmodel` calls Fabric/Power BI directly under the developer's identity, so it works with or without `rayfin up`.
-  Every other type, `kusto` included, POSTs to the deployed item and requires a prior `rayfin up`.
+  Every other type, including experimental `kusto`, POSTs to the deployed item and requires a prior `rayfin up`.
 - `connector invoke` on `fabric-semanticmodel` returns an already-normalized result, because that connector normalizes inside its `invoke` middleware.
   Do not apply `toQueryResult` to it again.
 - A resolved `connector invoke` call is not automatically a success.

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

@@ -0,0 +1,21 @@
+---
+sidebar_position: 9
+---
+
+# Eventhouse (`kusto`) usage guide
+
+> **Moved.** This usage guide now ships **inside the connector package**,
+> version-locked to the `kusto` connector the Builder actually installed — so the
+> streaming model, KQL shaping, safe query construction, and result handling can
+> never drift from the CLI. It is fetched on demand with `packageVersion`
+> provenance.
+>
+> Read it from `@microsoft/rayfin-connector-kusto`:
+>
+> - MCP: `search_docs` / `discover_packages`
+> - CLI: `rayfin docs search "<term>"` (module `rayfin-connector-kusto`)
+> - Source: `@microsoft/rayfin-connector-kusto/assets/docs/`
+>
+> The shared function-bridge mechanics — `connector add`, the generated
+> `rayfin.yml` and `schema.ts`, and the `client.connectors.<name>` call — stay in
+> the [Category B guide](./category-b-function-bridge.md).

package/assets/docs/{experimental/cli → cli}/connectors/index.md

@@ -6,25 +6,9 @@ sidebar_position: 6
 
 Connectors let a Rayfin app read from — and, for some types, write to — Microsoft Fabric data sources: warehouses, SQL databases, Lakehouse SQL analytics endpoints, semantic models, and KQL databases.
 
-## Prerequisite — enabling the `connector` command group
+The `connector` command group is always available.
 
-Connectors are behind a feature flag, so `rayfin connector ...` is only registered when the project opts in. Prefer the declarative setting in `rayfin/rayfin.yml`:
-
-```yaml
-services:
-  connectors:
-    enabled: true
-```
-
-With that setting present the command group is available from the very first `connector add`, with nothing to configure in the shell — the path generated apps and agents should use.
-
-The flag also activates automatically once `rayfin.yml` has a `connectors:` block (written by `connector add`), and it can still be turned on for a single command with the environment variable:
-
-```bash
-RAYFIN_FEATURE_FLAGS=connectors npx rayfin connector search --help
-```
-
-Without any of the three the commands do not exist and the CLI reports an unknown command.
+> **`kusto` authoring is held in this release.** `connector types` and `connector search` omit it, and `connector add --type kusto` refuses it. A project that **already declares** a Kusto connector is unaffected: it still validates, deploys through `rayfin up`, and answers `connector invoke`. Kusto material in these docs describes that preserved runtime contract and the authoring path for when it ships.
 
 Each command has its own reference page:
 
@@ -36,7 +20,8 @@ Each command has its own reference page:
 Each category has its own contract page — read the one that matches your connector type, not both:
 
 - [Category A — GraphQL entity connectors](./category-a-entities.md) — now **package-owned**; the full reference (entity generation, `@role` policies, the aggregate schema, and the per-dialect read/write matrix) ships in `@microsoft/rayfin-connector-fabric-graphql` (`rayfin docs search` / `search_docs`).
-- [Category B — function-bridge connectors](./category-b-function-bridge.md) — the `kusto` and `fabric-semanticmodel` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
+- [Category B — function-bridge connectors](./category-b-function-bridge.md) — the `fabric-semanticmodel` and experimental `kusto` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
+- [Eventhouse (`kusto`) usage guide](./eventhouse.md) — the experimental `kusto` supplement, now **package-owned**; when to reach for the type, its streaming model, shaping KQL, safe query construction, and reading results all ship in `@microsoft/rayfin-connector-kusto` (`rayfin docs search` / `search_docs`).
 
 A typical loop is search → add → inspect (Category A) or search → add → invoke (Category B).
 
@@ -46,13 +31,13 @@ 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`                                                                                                                  | `kusto`, `fabric-semanticmodel`                        |
-| **App surface**                       | Generated entity files with typed CRUD through the data client                                                                                                                   | A single `executeQuery` operation carrying a raw query |
+| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `fabric-graphql`                                                                                                | `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`                                    |
 | **Entity files and `@role` policies** | Yes                                                                                                                                                                              | No                                                     |
 | **`metadata.json` entities**          | Yes                                                                                                                                                                              | No                                                     |
-| **`connector inspect`**               | Supported                                                                                                                                                                        | `fabric-semanticmodel` only — `kusto` is not supported |
+| **`connector inspect`**               | Supported                                                                                                                                                                        | `fabric-semanticmodel` only — experimental `kusto` is not supported |
 | **`connector invoke`**                | Rarely needed                                                                                                                                                                    | The main way to exercise the connector                 |
 
 Category B connectors are pinned to an adapter version and expose no GraphQL entities, so there is nothing to generate and no row-level security to author.

package/assets/docs/{experimental/cli → cli}/connectors/invoke.md

@@ -32,6 +32,10 @@ Two transports, chosen by connector type:
 - **`fabric-semanticmodel`** — the CLI calls Fabric/Power BI **directly under the developer's own identity**, so this works whether or not `npx rayfin up` has been run. It requires `workspaceId` **and** `itemId` under the connector's `config:` block; without both, it fails up front rather than falling through to the deployed transport. The Power BI scope and audience are derived from the configured Fabric API base URL, so an INT ring mints an INT-audience token.
 - **Every other type, including `kusto`** — POSTs to the deployed item at `<remote-endpoint>/__private/connectors/<name>/invoke`, so it requires a prior `npx rayfin up`.
 
+> `kusto` authoring is held in this release, but invocation is deliberately preserved: a project that already declares a Kusto connector can still invoke it. Only `connector add`, `types` and `search` withdraw the type. See [Connectors](./index.md).
+
+`--transport deployed` overrides the type-based choice and forces the deployed route. That route authenticates the **app**, not the developer, so it needs an app-session token in `RAYFIN_TOKEN`; `npx rayfin login` cannot mint one.
+
 ## Token handling (semantic model path)
 
 `npx rayfin login` only consents to the Fabric scope, not the Power BI scope this path needs. Consequences:

package/assets/docs/{experimental/cli → cli}/connectors/search.md

@@ -8,7 +8,9 @@ sidebar_position: 1
 npx rayfin connector search [query] [--workspace-id <id> --type <types> | --all-workspaces --type <types>] [--limit <n>] [--json]
 ```
 
-`connector search` finds Fabric data sources — warehouses, SQL databases, Lakehouses, semantic models, and KQL databases — that the signed-in identity can add as connectors, before you know exact workspace or item IDs.
+> **`kusto` authoring is held in this release**, so search does not return KQL databases and `--type kusto` is not accepted. Search exists to feed `connector add`, which would refuse the type — surfacing a source the Builder could not then attach. See [Connectors](./index.md).
+
+`connector search` finds Fabric data sources — warehouses, SQL databases, Lakehouses, and semantic models — that the signed-in identity can add as connectors, before you know exact workspace or item IDs.
 
 Use it to find candidates for [`connector add`](./add.md). It never touches app data itself.
 
@@ -38,7 +40,7 @@ Only one of `--workspace-id` and `--all-workspaces` may be given. Outside a Rayf
 
 Duplicate-looking entries — for example a SQL Database and its SQL-analytics-endpoint twin sharing a workspace and display name — are grouped visually next to each other in interactive and plain output only. They are never deduplicated, and `--json` always returns the canonical, ungrouped order.
 
-The SQL-endpoint-permissions note ("Schema discovery for SQL-based connectors requires SQL endpoint permissions") only prints when at least one result is a SQL-dialect connector type — never for a semantic-model-only or Kusto-only result set.
+The SQL-endpoint-permissions note ("Schema discovery for SQL-based connectors requires SQL endpoint permissions") only prints when at least one result is a SQL-dialect connector type — never for a semantic-model-only result set. (It would also not print for a Kusto-only set, once Kusto authoring ships.)
 
 ## Examples
 

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

@@ -189,7 +189,7 @@ These variables are read from the shell environment and are never written to fil
 | `RAYFIN_WORKSPACE_ID` | Fabric workspace ID for non-interactive setup. Used with `RAYFIN_TOKEN`. |
 | `RAYFIN_TENANT_ID` | Entra ID tenant used by `rayfin up` for portal URLs and the `ctid` query parameter. Equivalent to the `-t, --tenant <id>` flag (precedence: flag > env var > signed-in tenant). |
 | `RAYFIN_ENCRYPTION_FALLBACK_ENABLED` | Set to `true` to allow plaintext token cache on systems without OS credential storage. Development only. |
-| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized values include `docker-local-dev`, `functions`, and `postgresql`. |
+| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized public values include `docker-local-dev`, `postgresql`, and `storage`. |
 | `RAYFIN_WEBSERVICE_IMAGE_NAME` | **Experimental.** Override the webservice container image used by `rayfin dev --provider docker` and Docker Compose. Defaults to `ghcr.io/microsoft/project-rayfin/webservice:cli-<version>`. |
 | `RAYFIN_APPINSIGHTS_CONNECTION_STRING` | Override the telemetry endpoint for the CLI and VS Code extension. |
 | `RAYFIN_TELEMETRY_ENV` | Override the CLI and `create-rayfin` telemetry environment label. Values are trimmed and lowercased. Known labels include `github-actions`, `azure-pipelines`, `gitlab-ci`, `jenkins`, `codespaces`, `devcontainer`, `local`, and `other`; custom labels may contain 1–64 ASCII letters, digits, hyphens, or underscores. Invalid non-empty values map to `other`, while an empty value uses automatic detection. Do not include identifying or sensitive values. |
@@ -199,8 +199,8 @@ These variables are read from the shell environment and are never written to fil
 | Flag | Effect |
 | --- | --- |
 | `docker-local-dev` | Allows `rayfin dev --provider docker` and the Docker maintenance commands. Bare `rayfin dev` remains available without this flag and defaults to Fabric. |
-| `functions` | Exposes Functions service prompts during `rayfin init`. |
 | `postgresql` | Adds PostgreSQL as a selectable dialect during `rayfin init` and `rayfin init` with bundled templates. |
+| `storage` | Enables the preview Storage service when declared in `rayfin.yml` or opted in from the shell. |
 
 ## File locations
 

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,43 @@ 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). |
+
+### Connectors
+
+Connectors let a Rayfin app read from — and, for some types, write to — Microsoft Fabric data sources. See [Connectors](./connectors/index.md) for the full guide.
+
+| Command | Description |
+| --- | --- |
+| `npx rayfin connector search [query]` | Discover Fabric sources the signed-in identity can add before you know exact workspace or item IDs. See [connector search](./connectors/search.md). |
+| `npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id>` | Declare a connector in `rayfin.yml` and scaffold `rayfin/connectors/<name>/`. See [connector add](./connectors/add.md). |
+| `npx rayfin connector inspect` | Explore a connector's underlying source in read-only mode by listing entity names, sampling one entity, or running a `.sql` / `.dax` query file. See [connector inspect](./connectors/inspect.md). |
+| `npx rayfin connector invoke <connector-name> <operation>` | Run a single named operation against a configured connector. See [connector invoke](./connectors/invoke.md). |
+| `npx rayfin connector list` | Print the configured connectors. See [Connectors](./connectors/index.md#where-connector-state-lives). |
+| `npx rayfin connector remove <name>` | Delete both the `rayfin.yml` entry and the `rayfin/connectors/<name>/` directory. See [Connectors](./connectors/index.md#where-connector-state-lives). |
+| `npx rayfin up connector apply [--name <name>]` | Re-apply DAB config only. See [Deploying connectors](./connectors/index.md#deploying-connectors). |
+
+### 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: