@microsoft/rayfin-guide 1.35.0-alpha.1287 → 1.35.0-alpha.1331

package/assets/docs/app-backend/deploy.md

@@ -149,13 +149,14 @@ Use `--exclude-services <names>` to skip the build/package/deploy phase for supp
 The runtime settings POST still reflects your `rayfin.yml`, so the backend is never silently reconfigured.
 The only currently supported value is `staticHosting`; other names fail with a clear error.
 
-The canonical use case is local development where Vite serves the frontend locally, so you want the backend deployed but not the static bundle:
+Use `rayfin dev` for the normal local-development workflow; it never publishes the static bundle.
+The exclude flag remains useful for existing scripts and automation that intentionally run the deployment workflow while Vite serves the frontend:
 
 ```bash
 npx rayfin up --exclude-services staticHosting
 ```
 
-The samples and templates use this flag in their `npm run dev` script.
+Rayfin's bundled samples and templates use `rayfin dev` for their `npm run dev` script.
 
 ## Apply database changes remotely
 
@@ -202,6 +203,24 @@ Add `--json` for machine-readable output:
 npx rayfin up status --json
 ```
 
+When static content is deployed, the human-readable output includes its public URL:
+
+```text
+Static app:      https://silky-sand-4924b3ad1f-centraluseuap.webapp.rayfingwdev.com
+```
+
+The JSON output exposes the same value as `deployment.hostingUrl`:
+
+```json
+{
+  "deployment": {
+    "hostingUrl": "https://silky-sand-4924b3ad1f-centraluseuap.webapp.rayfingwdev.com"
+  }
+}
+```
+
+When no static app URL is recorded, the human-readable output omits the line and `deployment.hostingUrl` is `null` in JSON.
+
 ## Sign out
 
 Clear cached credentials when you are done or need to switch accounts:

package/assets/docs/auth/fabric.md

@@ -273,7 +273,8 @@ Most apps should use `ensureSignedInWithFabric` instead.
 ## Environment variables
 
 Fabric auth requires three Vite environment variables so your frontend can build the `FabricAuthOptions` at runtime.
-`npx rayfin up` writes the underlying `RAYFIN_PUBLIC_*` values to `rayfin/.env`, and `rayfin env --framework vite` (run automatically by the scaffolded `predev` / `prebuild` hooks) maps them to Vite-compatible names in `.env.local`.
+`npx rayfin dev` writes the underlying `RAYFIN_PUBLIC_*` values to `rayfin/.env` and maps them to Vite-compatible names in `.env.local` before starting the frontend.
+Production builds retain the scaffolded `prebuild` hook to refresh those values before bundling.
 
 | Source variable (`rayfin/.env`) | Vite variable (`.env.local`) | Description | Example |
 | --- | --- | --- | --- |
@@ -302,7 +303,7 @@ const fabricOptions = {
 
 ## Deployment values
 
-After running `npx rayfin up`, the CLI records deployment metadata in `rayfin/.deployments.json` and merges the corresponding `RAYFIN_PUBLIC_*` variables into `rayfin/.env`:
+After running `npx rayfin dev` or `npx rayfin up`, the CLI records deployment metadata in `rayfin/.deployments.json` and merges the corresponding `RAYFIN_PUBLIC_*` variables into `rayfin/.env`:
 
 ```text
 RAYFIN_PUBLIC_ITEM_ID=<guid>
@@ -310,7 +311,8 @@ RAYFIN_PUBLIC_WORKSPACE_ID=<guid>
 RAYFIN_PUBLIC_PORTAL_URL=https://app.fabric.microsoft.com/
 ```
 
-Run `rayfin env --framework vite` (or `npm run dev`, which triggers it via the scaffolded `predev` hook) to generate `.env.local` with the Vite-compatible names. Use `RAYFIN_PUBLIC_ITEM_ID` as the `projectId` and `RAYFIN_PUBLIC_WORKSPACE_ID` as the `workspaceId` in your `FabricAuthOptions`.
+`rayfin dev` generates `.env.local` with Vite-compatible names before starting the frontend.
+Use `RAYFIN_PUBLIC_ITEM_ID` as the `projectId` and `RAYFIN_PUBLIC_WORKSPACE_ID` as the `workspaceId` in your `FabricAuthOptions`.
 
 ## Troubleshooting
 

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

@@ -0,0 +1,78 @@
+---
+sidebar_position: 2
+---
+
+# connector add
+
+```bash
+npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id> [--name <name>] [--operations <ops>]
+```
+
+`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`, scaffolds `rayfin/connectors/<name>/schema.ts`, and runs schema discovery. `rayfin/connectors/<name>/metadata.json` is written so a subset of entities can be generated later.
+
+If you do not already know the workspace and item IDs, run [`connector search`](./search.md) first — its `--json` output includes a ready-to-run `addCommand` for each result.
+
+## Options
+
+| Flag                  | Required     | Purpose                                                                                                                                                                                                                 |
+| --------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--type <type>`       | yes          | The connector type, for example `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `kusto`, or `fabric-semanticmodel`.                                                                                    |
+| `--workspace-id <id>` | yes (Fabric) | Fabric workspace ID. Must be a literal — `${VAR}` placeholders are rejected.                                                                                                                                            |
+| `--item-id <id>`      | yes (Fabric) | Fabric item or artifact ID. Must be a literal.                                                                                                                                                                          |
+| `--name <name>`       | no           | Connector name. Derived from the item display name when omitted.                                                                                                                                                        |
+| `--operations <ops>`  | no           | Comma-separated subset of the type's allowed operations, for example `read,update`. Narrows the emitted `operations:` at add time. Omit for all allowed operations. Each value must be in the type's catalog allowlist. |
+| `-y, --yes`           | no           | Auto-accept overwrite and confirmation prompts (non-interactive).                                                                                                                                                       |
+| `-v, --verbose`       | no           | Verbose diagnostics.                                                                                                                                                                                                    |
+
+## Scoping operations
+
+Without `--operations`, `connector add` writes **every** operation the catalog allows for the type. Prefer scoping at add time over hand-editing YAML afterwards:
+
+```bash
+npx rayfin connector add --type fabric-warehouse --workspace-id <ws> --item-id <item> --operations read,update
+```
+
+The resulting `rayfin.yml` entry lists operations as objects, not bare strings:
+
+```yaml
+connectors:
+  - name: inventory
+    type: fabric-warehouse
+    config:
+      workspaceId: ${WS_ID}
+      itemId: ${ITEM_ID}
+    auth:
+      type: delegated
+    operations:
+      - name: read
+      - name: update
+```
+
+Rules:
+
+- You can narrow below the catalog default; you cannot widen above it.
+- There is no `all` meta-operation — list every action explicitly.
+- The host validator rejects unknown or duplicate operation names at `rayfin up` time.
+
+## Category B connectors
+
+For `kusto` and `fabric-semanticmodel`, `connector add` writes the `rayfin.yml` entry but there are no GraphQL entities to discover, so no entity files are generated and no row-level security applies:
+
+- `executeQuery` is the only allowed operation.
+- `auth.type` must be `delegated`.
+- The connector is pinned to an adapter version.
+- There is no `metadata.json` entity list to generate from.
+
+After adding, exercise the connector with [`connector invoke`](./invoke.md) rather than writing entity code.
+
+## Related commands
+
+```bash
+npx rayfin connector list [--verbose] [--json]
+
+# Removes the rayfin.yml entry AND the rayfin/connectors/<name>/ directory.
+# Re-add after remove to refresh metadata, then regenerate entity files yourself.
+npx rayfin connector remove <name> [--yes]
+```

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

@@ -0,0 +1,58 @@
+---
+sidebar_position: 6
+---
+
+# Connectors
+
+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 — the `connector` command group is feature-flagged
+
+`rayfin connector ...` is only registered when the `RAYFIN_FEATURE_FLAGS` environment variable contains `connectors`. Without it the commands do not exist and the CLI reports an unknown command.
+
+```bash
+RAYFIN_FEATURE_FLAGS=connectors npx rayfin connector search --help
+```
+
+Each command has its own reference page:
+
+- [`connector search`](./search.md) — discover Fabric sources the signed-in identity can add.
+- [`connector add`](./add.md) — declare a connector in `rayfin.yml` and scaffold its files.
+- [`connector inspect`](./inspect.md) — run a single read-only sample query against a source.
+- [`connector invoke`](./invoke.md) — run one named operation against a configured connector.
+
+A typical loop is search → add → inspect (Category A) or search → add → invoke (Category B).
+
+## Two categories of connector
+
+The commands available to a connector, and the code you write against it, depend on its category.
+
+|                                       | 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 |
+| **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 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.
+
+## Where connector state lives
+
+- `rayfin/rayfin.yml` — the `connectors:` block: each connector's `name`, `type`, `config` (workspace and item IDs), `auth`, and `operations`.
+- `rayfin/connectors/<name>/metadata.json` — discovered schema for Category A connectors; the source for generating entity files.
+- `rayfin/connectors/<name>/schema.ts` — placeholder scaffold written by `connector add`.
+
+`npx rayfin connector list` prints the configured connectors; `npx rayfin connector remove <name>` deletes both the `rayfin.yml` entry and the `rayfin/connectors/<name>/` directory.
+
+## Deploying connectors
+
+```bash
+npx rayfin up                                     # deploy connectors to the cloud
+npx rayfin up connector apply [--name <name>]     # re-apply DAB config only
+```
+
+Most connector commands work before deployment. The exception is [`connector invoke`](./invoke.md) for every type except `fabric-semanticmodel`, which posts to the deployed item and therefore requires a prior `rayfin up`.

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

@@ -0,0 +1,78 @@
+---
+sidebar_position: 3
+---
+
+# connector inspect
+
+```bash
+npx rayfin connector inspect (--name <name> | <direct-selector-flags>) (--entity <name> | --query <path>) [--rows <n>] [--verbose] [--json]
+```
+
+`connector inspect` takes no positional arguments — every selector and query mode is a flag.
+
+`connector inspect` runs a single read-only sample query against a connector's underlying source, before you have written any app code. Use it to check a table's real data and shape ahead of entity generation, or to debug a row-level-security or query issue on an already-wired connector. It is a development aid — never use it to power app functionality.
+
+Supported types: the three Category A SQL types (`fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`) and `fabric-semanticmodel` (DAX). `kusto` is **not** supported today — the command errors with `Unsupported connector type: kusto`.
+
+## Pick exactly one selector and one query mode
+
+Two independent choices, each a mutually exclusive pair. Passing zero or both options in a pair fails validation before any network call.
+
+| Choice                                          | Option A                                                                                                                      | Option B                                                                                                                                                                                       |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Selector** — which connector or item to query | `--name <name>` — a connector already declared in `rayfin.yml`                                                                | Direct mode — `--workspace-id`/`--workspace <name>` plus `--item-id`/`--item <name>` plus `--type <type>`, or `--url <portal-url>` for a semantic model (auto-extracts workspace and item IDs) |
+| **Query mode**                                  | `--entity <name>` — structured: builds `SELECT TOP (n) * FROM <entity>` (SQL) or `EVALUATE TOPN(n, '<entity>')` (DAX) for you | `--query <path>` — raw: runs the literal `.sql` or `.dax` file verbatim, still capped and validated                                                                                            |
+
+All four combinations of `{--name, direct} × {--entity, --query}` are valid.
+
+`--workspace` and `--item` accept display names and are resolved to IDs the same way [`connector add`](./add.md) fuzzy matching works; `--workspace-id` and `--item-id` take literal IDs directly.
+
+## Entity resolution
+
+Applies to `--entity` mode only.
+
+- **`--name` plus `--entity` with an unqualified name (no `.`)** — first checked against the connector's local `rayfin/connectors/<name>/metadata.json`, with no network call. Zero matches falls through to live resolution; exactly one match auto-qualifies to `schema.table`; more than one match fails immediately asking you to disambiguate with a schema-qualified name. It does **not** fall through to live resolution in the ambiguous case.
+- **Any other combination** — direct mode, or `--query` mode — never consults `metadata.json`. For SQL types, an unqualified `--entity` is resolved live via `SELECT TABLE_SCHEMA, TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE LOWER(TABLE_NAME) = LOWER('<entity>')`: zero matches passes the name through unqualified, one match auto-qualifies, more than one match throws asking you to disambiguate with `--entity <schema>.<table>`.
+- A schema-qualified `--entity <schema>.<table>` skips resolution entirely, in both cases.
+
+## Validation
+
+Applies to both query modes.
+
+- **SQL** — must start with `SELECT` or `WITH`; must be a single statement (a trailing `;` is fine, an embedded one is not); rejects `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `EXEC`/`EXECUTE`, and `INTO` anywhere outside a string literal.
+- **DAX** — must start with `EVALUATE`.
+- `--query <path>` must resolve to a `.sql` or `.dax` file inside the project root; paths outside it are rejected. The project root is the directory containing `rayfin/rayfin.yml` when one is found. Direct mode (no `--name`) falls back to the current working directory if no `rayfin.yml` exists, so `--query` never requires a Rayfin project.
+- `--rows <n>` caps the sample size — default 10, maximum 100. The result reports `truncated: true` when the source had more rows than the cap.
+
+## Examples
+
+```bash
+# --name selector + structured entity mode
+npx rayfin connector inspect --name inventory --entity Order
+
+# --name selector + raw query file
+npx rayfin connector inspect --name inventory --query rayfin/queries/order.sql
+
+# Direct selector (literal IDs) + structured entity mode
+npx rayfin connector inspect --workspace-id <ws-id> --item-id <item-id> --type fabric-warehouse --entity Order
+
+# Direct selector (fuzzy display names) + raw query file
+npx rayfin connector inspect --workspace "Sales Analytics" --item "Inventory Warehouse" --type fabric-warehouse --query rayfin/queries/order.sql
+
+# Semantic model (DAX), resolved from a Fabric portal URL
+npx rayfin connector inspect --url <fabric-portal-semantic-model-url> --query rayfin/queries/model.dax
+```
+
+Combine `--workspace-id`, `--item-id`, and `--type` with either `--entity` or `--query` freely — none of the four combinations require `--name` or a `rayfin.yml` entry to exist.
+
+## Errors
+
+SQL errors are categorized before being shown:
+
+| Condition                                                      | Surfaced as                                                                            |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| SQL Server error `229`, `230`, `262`, `297`, `300`             | "Permission denied", with a permissions recovery hint.                                 |
+| SQL Server error `18456`, `4060`, or `ELOGIN`                  | "Authentication failed", with a `rayfin login` recovery hint.                          |
+| Anything else, including invalid object name / table not found | The underlying message, with a generic "verify the entity/table name and access" hint. |
+
+Semantic model HTTP errors map `401` to re-login, `403` to permissions, and everything else to the generic hint.

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

@@ -0,0 +1,76 @@
+---
+sidebar_position: 4
+---
+
+# connector invoke
+
+```bash
+npx rayfin connector invoke <connector-name> <operation> (--input '<json>' | --file <path>) [--verbose] [--json]
+```
+
+`connector invoke` runs a single named operation against a configured connector and prints the result. It is the loop for exercising [Category B connectors](./index.md#two-categories-of-connector) — `executeQuery` over DAX or KQL — without writing any app code.
+
+Both positionals also have flag forms, `--name <name>` and `--operation <operation>`, which win over the positionals when both are given.
+
+Run it from inside a Rayfin project: it resolves `rayfin/rayfin.yml`, and fails with a recovery hint if there is no project root or the `connectors:` block is empty.
+
+## Payload input
+
+Exactly one of these is required — passing both, or neither, fails:
+
+- `--input '<json>'` — inline JSON payload for the operation input.
+- `--file <path>` — path to a JSON file. The path is resolved against the project root, and **the resolved path must stay inside it**; a `../` escape is rejected before the file is read. An absolute path is accepted as long as it resolves inside the project root.
+
+## Operation resolution
+
+The requested operation is matched **case-insensitively** against the connector's `operations:` list in `rayfin.yml`. If that entry has no `operations:`, the connector type's full catalog allowlist is used instead. A miss fails with the allowed set listed.
+
+## Transports
+
+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`.
+
+## Token handling (semantic model path)
+
+`npx rayfin login` only consents to the Fabric scope, not the Power BI scope this path needs. Consequences:
+
+- Interactively (no `--json`), the CLI prompts to complete Power BI consent.
+- With `--json`, token acquisition is **silent-only** so prompts cannot corrupt the single-JSON-object contract. If consent is still needed the command fails and tells you to drop `--json` or set `RAYFIN_TOKEN`.
+- `RAYFIN_TOKEN`, when set, is passed through **unchanged** regardless of the scopes requested. Its audience is decoded and checked locally, so a wrong-audience or undecodable token fails with a clear message instead of surfacing later as a phantom workspace-permission error.
+
+## Output
+
+`--verbose` cannot be combined with `--json` — narration would break the single-object contract.
+
+Success emits `{status: 'ok', connector, operation, output}`. In non-JSON modes it prints `✅ Invoked <name>.<operation>` followed by the output.
+
+What `output` holds depends on the connector. `fabric-semanticmodel` normalises inside its `invoke` middleware, so `output` is already a discriminated result rather than the raw service envelope: `{status: 'success', table, requestId}`, where `table.columns` are `{name, dataType}` and `table.rows` are column-aligned arrays. No caller-side conversion is needed, and the same shape comes back whether the operation ran locally or through the deployed item.
+
+A resolved call is **not** automatically a success, and the failure signal depends on the same distinction. A connector that normalises reports Power BI failures — expired token, missing Build permission, throttling — as `{status: 'error', error, requestId}`, where `error` carries `category`, `message`, and optional `code` and `details`. A connector that returns the raw envelope reports failure as `status: 'Failed'` instead. The CLI reads both, converts either into a non-zero exit, and surfaces the service-supplied request id for tracing.
+
+## Examples
+
+```bash
+# Inline payload, positional args
+npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOPN(10, Sales)"}'
+
+# Same thing with flag forms and a payload file
+npx rayfin connector invoke --name mymodel --operation executeQuery --file ./payload.json
+
+# Machine-readable (no --verbose allowed alongside)
+npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOPN(1, Sales)"}' --json
+```
+
+## Errors
+
+| Message                                                          | Fix                                                                                   |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `Missing required connector invoke arguments`                    | Supply both the connector name and the operation.                                     |
+| `Choose exactly one payload source` / `Missing payload input`    | Pass exactly one of `--input` or `--file`.                                            |
+| `Input file must be inside the project`                          | Use a relative path under the project root.                                           |
+| `Operation "<op>" is not allowed for connector "<name>"`         | Check the connector's `operations:` in `rayfin.yml`, or the type's allowlist.         |
+| `missing workspaceId/itemId in rayfin.yml`                       | Add both under `config:`, or re-run [`connector add`](./add.md).                      |
+| `Access token has the wrong audience for the Power BI query API` | Unset or replace `RAYFIN_TOKEN`, or re-run without `--json` to consent interactively. |
+| `No remote endpoint configured`                                  | The non-semantic-model transport needs a deployed item — run `npx rayfin up` first.   |

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

@@ -0,0 +1,66 @@
+---
+sidebar_position: 1
+---
+
+# connector search
+
+```bash
+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.
+
+Use it to find candidates for [`connector add`](./add.md). It never touches app data itself.
+
+## Scope resolution
+
+The search scope is resolved in priority order:
+
+1. `--workspace-id <id>` — search exactly one workspace. **Requires** `--type`: without it, every discoverable item type would be fetched with a separate request to that workspace.
+2. `--all-workspaces` — tenant-wide scan across every workspace the identity can access. **Requires** `--type` (the only server-side filter) to keep the scan bounded.
+3. No scope flag, run inside a Rayfin project with deployments — defaults to the union of every workspace recorded in the project's deployments registry (dev, prod, and so on), without switching the active deployment. This is the only scope that does **not** require `--type`.
+
+Only one of `--workspace-id` and `--all-workspaces` may be given. Outside a Rayfin project with zero deployments, one of them is required; omitting both fails with `workspace scope is required`.
+
+## Filtering
+
+| Flag                                       | Purpose                                                                                                                                              |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[query]` (positional) or `--query <text>` | Case-insensitive name filter. Omit to list every connectable source in scope. `--query` wins if both are given.                                      |
+| `--type <types>`                           | Comma-separated subset of connector types, for example `fabric-warehouse,fabric-sqldatabase`. Required with `--workspace-id` and with `--all-workspaces`.                      |
+| `--limit <n>`                              | Caps the rows shown. Ignored in interactive mode, where the picker paginates the full result set instead; applies only to plain and `--json` output. |
+
+## Output modes
+
+- **Interactive** (default on a TTY) — a paginated picker. Page size comes from `RAYFIN_CONNECTOR_SEARCH_PAGE_SIZE`, default 30. Picking a source runs a pre-flight access check (SQL endpoint, Kusto endpoint, or semantic model probe, depending on type) before handing off to [`connector add`](./add.md); a failed check re-shows the picker instead of aborting. `--yes` and `--verbose` are forwarded to the `connector add` it runs.
+- **Plain** (non-TTY) — prints the list and exits, with no prompt.
+- **`--json`** — a machine-readable envelope on stdout: `{status, query, scope, count, sources}`. Each row carries `workspaceId`, `itemId`, and `connectorType`, plus `suggestedName` (the sanitized display name to use as the connector name) and `addCommand` (the exact `rayfin connector add …` string to run). Skips both the picker and the access-check pre-flight.
+
+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.
+
+## Examples
+
+```bash
+# Query text as a positional argument, scoped to one workspace (--type is required with --workspace-id)
+npx rayfin connector search "sales" --workspace-id <ws-id> --type fabric-warehouse
+
+# Tenant-wide scan, narrowed to one or more types (--type is required with --all-workspaces)
+npx rayfin connector search --all-workspaces --type fabric-warehouse,fabric-sqldatabase
+
+# No scope flag inside a deployed project — searches every deployment workspace, no --type needed
+npx rayfin connector search
+
+# Machine-readable output, capped to 5 rows, skips the interactive picker
+npx rayfin connector search --workspace-id <ws-id> --type fabric-warehouse --json --limit 5
+```
+
+## Errors
+
+| Message                                              | Fix                                                                                                               |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `Command incomplete: workspace scope is required`    | No `--workspace-id` or `--all-workspaces` and no deployments found. Pass one of those flags.                      |
+| `--type is required with --all-workspaces`           | Add a `--type` filter to bound the tenant-wide scan.                                                              |
+| `--type is required with --workspace-id`             | Add a `--type` filter so a single request is made instead of one per discoverable item type.                      |
+| `You don't have the required permission on <source>` | The pre-flight access check failed during the interactive add handoff. Pick a different source or request access. |

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

@@ -10,8 +10,9 @@ The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to
 
 | Variable | Description | Populated by |
 | --- | --- | --- |
-| `RAYFIN_PUBLIC_API_URL` | Rayfin backend URL (`http://localhost:5168` for local dev). | `rayfin up` |
-| `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | Public key for Rayfin SDK initialization. | `rayfin up` |
+| `RAYFIN_PUBLIC_API_URL` | Rayfin backend URL selected for the development or deployed environment. | `rayfin dev` / `rayfin up` |
+| `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | Public key for Rayfin SDK initialization. | `rayfin dev` / `rayfin up` |
+| `RAYFIN_PUBLIC_FUNCTIONS_URL` | URL of the local Functions host started by `rayfin dev`. Removed when functions are disabled so local clients do not retain a stale host. | `rayfin dev` |
 | `RAYFIN_PUBLIC_ITEM_ID` | Fabric AppBackend item ID. Used for Fabric brokered auth. | `rayfin up` |
 | `RAYFIN_PUBLIC_WORKSPACE_ID` | Fabric workspace ID. Used for Fabric brokered auth. | `rayfin up` |
 | `RAYFIN_PUBLIC_TENANT_ID` | Entra ID tenant for workspace disambiguation. | `rayfin up` |
@@ -27,6 +28,7 @@ The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to
 | --- | --- | --- | --- |
 | `RAYFIN_PUBLIC_API_URL` | `VITE_RAYFIN_API_URL` | `NEXT_PUBLIC_RAYFIN_API_URL` | `API_URL` |
 | `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | `VITE_RAYFIN_PUBLISHABLE_KEY` | `NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY` | `PUBLISHABLE_KEY` |
+| `RAYFIN_PUBLIC_FUNCTIONS_URL` | `VITE_RAYFIN_FUNCTIONS_URL` | `NEXT_PUBLIC_RAYFIN_FUNCTIONS_URL` | `FUNCTIONS_URL` |
 | `RAYFIN_PUBLIC_ITEM_ID` | `VITE_FABRIC_ITEM_ID` | `NEXT_PUBLIC_FABRIC_ITEM_ID` | `ITEM_ID` |
 | `RAYFIN_PUBLIC_WORKSPACE_ID` | `VITE_FABRIC_WORKSPACE_ID` | `NEXT_PUBLIC_FABRIC_WORKSPACE_ID` | `WORKSPACE_ID` |
 | `RAYFIN_PUBLIC_TENANT_ID` | `VITE_FABRIC_TENANT_ID` | `NEXT_PUBLIC_FABRIC_TENANT_ID` | `TENANT_ID` |
@@ -40,6 +42,37 @@ Custom `RAYFIN_PUBLIC_*` variables you add follow a generic pattern: `RAYFIN_PUB
 The sample `vite.config.ts` files pin the server to it with `strictPort`, so if the assigned port is already taken the dev server fails fast instead of silently drifting to another port.
 To run on a different port, set `RAYFIN_PUBLIC_FRONTEND_PORT` in `rayfin/.env` (then re-run `rayfin env`); `rayfin up` registers whatever value is assigned in the deployed redirect allow-list.
 
+### Bare development runtime wiring
+
+`npx rayfin dev` runs the local frontend against the Fabric backend by default.
+Use `npx rayfin dev --provider fabric` to select the same provider explicitly.
+The CLI reuses a registered deployment or provisions and records a missing AppBackend.
+Set `RAYFIN_WORKSPACE_ID` to target a specific workspace; otherwise the active registered deployment or My workspace is used.
+
+The CLI starts `npm run dev:frontend` when that script exists and falls back to `npm run dev` for existing projects.
+This lets bundled templates expose `npm run dev` as the complete session without recursively starting the CLI.
+When migrating an existing project to `"dev": "rayfin dev"`, also add a non-recursive child such as `"dev:frontend": "vite"`; otherwise the CLI fails with an actionable recursion error.
+Scripts are resolved from `services.staticHosting.path` when configured, otherwise from the project root.
+For a nested frontend package, declare `dev:frontend` (or the legacy `dev` fallback) in that package's `package.json`.
+
+When `services.functions.enabled` is `true`, the same command builds and starts the configured functions package with Azure Functions Core Tools.
+The CLI reserves the nearest available Functions port starting at `7071` and writes its URL to `RAYFIN_PUBLIC_FUNCTIONS_URL` before starting the frontend.
+When functions are disabled, the CLI removes any stale `RAYFIN_PUBLIC_FUNCTIONS_URL` from `rayfin/.env` and regenerates the framework environment file without it.
+
+The local functions setup makes these workspace changes:
+
+- Merges backend coordinates and the Node inspector argument into the configured functions package's `local.settings.json`.
+- Adds a `Functions: Attach` configuration to the root `.vscode/launch.json` after the Functions host becomes ready.
+- Leaves JSON-with-comments launch files unchanged and reports that the attach configuration must be added manually.
+- Patches recognized `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` template files once so `functionsBaseUrl` reads `VITE_RAYFIN_FUNCTIONS_URL`.
+- Regenerates the framework `.env.local` file unless `--no-emit-env` is set.
+
+The Node inspector defaults to port `9229` and slides to the nearest available port when needed.
+Use the `Functions: Attach` launch configuration after the host is ready to debug local function code.
+
+To run the managed backend locally instead, enable the Docker preview and use `npx rayfin dev --provider docker`.
+Frontend and functions code still run as local processes; only the managed Rayfin backend moves from Fabric to Docker.
+
 ## Tooling overrides
 
 These variables configure CLI and extension behavior.
@@ -146,14 +179,15 @@ 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 `storage`, `functions`, and `postgresql`. |
-| `RAYFIN_WEBSERVICE_IMAGE_NAME` | **Experimental.** Override the webservice container image used by `rayfin dev` and `docker compose`. Both `rayfin dev` and this variable are experimental and may change. Defaults to `ghcr.io/microsoft/project-rayfin/webservice:cli-<version>`. |
+| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized values include `docker-local-dev`, `storage`, `functions`, and `postgresql`. |
+| `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. |
 
 ### Recognized `RAYFIN_FEATURE_FLAGS` values
 
 | 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. |
 | `storage` | Exposes storage commands (`rayfin dev storage *`) and storage prompts during `rayfin init`. |
 | `functions` | Exposes Functions service prompts during `rayfin init`. |
 | `postgresql` | Adds PostgreSQL as a selectable dialect during `rayfin init` and `rayfin init` with bundled templates. |

package/assets/docs/cli/index.md

@@ -16,10 +16,12 @@ see [CLI Installation](./installation.md).
 ```bash
 npm create @microsoft/rayfin@latest my-app   # 1. Create a project from a template
 cd my-app
-npx rayfin up                                 # 2. Start backend services
-npm run dev                                   # 3. Run the frontend dev server
+npm run dev                                   # 2. Start the complete development session
 ```
 
+The scaffolded `dev` script runs `rayfin dev`.
+It provisions or reuses a Fabric backend, applies the declared services and schema, and starts the frontend and enabled Functions locally.
+
 > **Existing or empty projects:** Use `npx rayfin init` instead of `npm create` to add Rayfin to a project that already has source code or an empty directory.
 > The init command walks you through enabling services, choosing a database dialect, and configuring static hosting without scaffolding a new template.
 
@@ -41,6 +43,13 @@ For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Buil
 > Use this to enable or disable services, switch the database dialect, or toggle static hosting without editing `rayfin.yml` by hand.
 > The CLI preserves your data model files under `rayfin/data/` during reconfiguration.
 
+### Development
+
+| Command | Description |
+| --- | --- |
+| `npx rayfin dev` | Start the development session. Uses the Fabric backend provider by default, provisions a missing AppBackend, applies declared state, and starts frontend and Functions code locally. |
+| `npx rayfin dev --provider docker` | Run the managed backend through the preview Docker provider while keeping frontend and Functions code local. |
+
 ### Deployment
 
 | Command | Description |
@@ -55,6 +64,20 @@ For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Buil
 | `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. |
 
+### Connectors
+
+Connectors let a Rayfin app read from existing Fabric sources. The `connector` command group is only registered when `RAYFIN_FEATURE_FLAGS` contains `connectors`. See [Connectors](./connectors/index.md) for the full guide.
+
+| Command | Description |
+| --- | --- |
+| `npx rayfin connector search [query]` | Discover Fabric sources you can connect to. See [Searching for sources](./connectors/search.md). |
+| `npx rayfin connector add` | Declare a connector in `rayfin.yml` and run schema discovery. See [Adding a connector](./connectors/add.md). |
+| `npx rayfin connector list` | List the connectors declared in the current project. |
+| `npx rayfin connector remove <name>` | Remove a connector's `rayfin.yml` entry and its `rayfin/connectors/<name>/` directory. |
+| `npx rayfin connector inspect` | Run a read-only sample query against a connector's source. See [Inspecting a source](./connectors/inspect.md). |
+| `npx rayfin connector invoke <name> <operation>` | Run one named operation against a configured connector. See [Invoking an operation](./connectors/invoke.md). |
+| `npx rayfin up connector apply` | Re-apply connector configuration to the remote Rayfin item. |
+
 ## Update the CLI
 
 To get the latest version of the Rayfin CLI and its dependencies:

package/assets/docs/cli/installation.md

@@ -60,15 +60,14 @@ npx rayfin --help
 
 ## First steps
 
-Start the backend services:
+Start the complete development session:
 
 ```bash
-npx rayfin up
+npm run dev
 ```
 
-This launches the enabled services,
-runs health checks, and applies the database configuration.
-Wait for the deployment to complete before continuing.
+The bundled templates' script runs `rayfin dev`.
+It provisions or reuses the Fabric backend, applies declared state, generates framework environment variables, and starts the frontend and enabled Functions locally.
 
 Apply schema changes after updating your data models:
 
@@ -76,12 +75,6 @@ Apply schema changes after updating your data models:
 npx rayfin up db apply
 ```
 
-Run your frontend dev server in a separate terminal:
-
-```bash
-npm run dev
-```
-
 ## Update the CLI
 
 To get the latest version:

package/assets/docs/cli/quickstart.md

@@ -34,6 +34,19 @@ npx rayfin init
 
 This installs the CLI and runs the interactive setup to create the `rayfin/` directory with starter configuration files.
 
+## Develop locally
+
+```bash
+npx rayfin dev
+```
+
+- Uses the Fabric backend provider by default and provisions a missing AppBackend.
+- Applies runtime settings and database schema before starting user code.
+- Starts the frontend and enabled Functions as local processes.
+- Press `Ctrl+C` to end the session.
+
+Bundled templates expose the same workflow as `npm run dev`.
+
 ## Deploy to Fabric
 
 ```bash
@@ -69,8 +82,9 @@ npx rayfin up db apply [--force]
 
 If `staticHosting` is enabled in `rayfin/rayfin.yml`, `npx rayfin up` automatically builds, packages, and deploys your static assets.
 
-When iterating locally with Vite, opt out of the static deploy phase with `npx rayfin up --exclude-services staticHosting`.
-This is what the scaffolded `npm run dev` script does so the backend deploys but the local Vite server keeps serving your frontend.
+`rayfin dev` never publishes static content, so Vite can serve the frontend without a static deployment.
+
+The lower-level `npx rayfin up --exclude-services staticHosting` command remains available for existing scripts and automation that need to run the deployment workflow while skipping only static content.
 
 To redeploy static content independently without running the full `rayfin up` flow:
 

package/assets/docs/data/permissions.md

@@ -26,7 +26,7 @@ Apply `@role` at the class level to control which roles can perform which action
 | --- | --- |
 | `roleName` | The role name (`'anonymous'` or `'authenticated'`). |
 | `actions` | A single action or array of actions: `'create'`, `'read'`, `'update'`, `'delete'`, or `'*'` for all. |
-| `options` | Optional object with `check`, `include`, and `exclude` properties. |
+| `options` | Optional object with `policy`, `include`, and `exclude` properties. |
 
 ## Basic example
 
@@ -38,7 +38,7 @@ import { entity, role, uuid, text } from '@microsoft/rayfin-core';
 @entity()
 @role('anonymous', 'read')
 @role('authenticated', ['create', 'read', 'update', 'delete'], {
-  check: (claims, item) => claims.sub.eq(item.user_id),
+  policy: (claims, item) => claims.sub.eq(item.user_id),
 })
 export class Todo {
   @uuid() id!: string;
@@ -52,11 +52,11 @@ In this example, authenticated users can only access Todo items where `user_id`
 
 ## Type-safe policy expressions
 
-The `check` callback provides typed access to both claims and entity fields.
+The `policy` callback provides typed access to both claims and entity fields.
 TypeScript infers the entity type from the decorated class, so you get autocompletion and refactor safety with no extra configuration.
 
 ```typescript
-check: (claims, item) => claims.sub.eq(item.user_id)
+policy: (claims, item) => claims.sub.eq(item.user_id)
 ```
 
 ### Supported claims
@@ -78,7 +78,7 @@ check: (claims, item) => claims.sub.eq(item.user_id)
 Combine expressions with `.and()` and `.or()`:
 
 ```typescript
-check: (claims, item) =>
+policy: (claims, item) =>
   claims.sub.eq(item.user_id).and(item.isActive.eq(true))
 ```
 
@@ -86,7 +86,7 @@ Both sides are parenthesized automatically, so grouping is always explicit:
 
 ```typescript
 // (claims.role eq 'admin') or (claims.sub eq @item.owner_id)
-check: (claims, item) =>
+policy: (claims, item) =>
   claims.role.eq('admin').or(claims.sub.eq(item.owner_id))
 ```
 
@@ -100,7 +100,7 @@ Only allow the `Title` field during create:
 
 ```typescript
 @role('authenticated', 'create', {
-  check: (claims, item) => claims.sub.eq(item.createdBy),
+  policy: (claims, item) => claims.sub.eq(item.createdBy),
   include: ['Title'],
 })
 ```
@@ -111,7 +111,7 @@ Hide sensitive fields from read operations:
 
 ```typescript
 @role('authenticated', 'read', {
-  check: (_claims, item) => item.IsAdmin.eq(false),
+  policy: (_claims, item) => item.IsAdmin.eq(false),
   exclude: ['last_login'],
 })
 ```
@@ -127,14 +127,14 @@ Apply different rules per action by using multiple `@role` decorators with singl
 @entity()
 @role('anonymous', 'read')
 @role('authenticated', 'create', {
-  check: (claims, item) => claims.sub.eq(item.createdBy),
+  policy: (claims, item) => claims.sub.eq(item.createdBy),
   include: ['Title'],
 })
 @role('authenticated', 'read', {
-  check: (claims, item) => claims.sub.eq(item.createdBy),
+  policy: (claims, item) => claims.sub.eq(item.createdBy),
 })
 @role('authenticated', 'update', {
-  check: (claims, item) => claims.sub.eq(item.createdBy),
+  policy: (claims, item) => claims.sub.eq(item.createdBy),
   exclude: ['adminContent'],
 })
 export class SecureDocument {
@@ -155,7 +155,7 @@ import { blob, role } from '@microsoft/rayfin-core';
 
 @blob()
 @role('authenticated', '*', {
-  check: (claims, item) => claims.sub.eq(item.owner_id),
+  policy: (claims, item) => claims.sub.eq(item.owner_id),
 })
 export class ProfileImage {
   owner_id!: string;
@@ -167,6 +167,7 @@ export class ProfileImage {
 - The `@role` decorator collects permission metadata at class definition time.
 - When you run `npx rayfin up db apply`, the CLI reads that metadata and generates DAB-compliant permission entries in the configuration.
 - Policy callbacks are compiled into DAB OData-style policy strings (for example `@claims.sub eq @item.user_id`).
+  In the generated DAB configuration the compiled expression appears under a `check` key; `policy` is the name you author with.
 - Field `include`/`exclude` arrays map directly to DAB field permission configuration.
 - Multiple `@role` decorators on the same class are aggregated per role.
   Conflicting declarations produce a warning at generation time.

package/assets/docs/getting-started/create-app-with-cli.md

@@ -14,13 +14,15 @@ Run `npm create @microsoft/rayfin@latest` in a terminal window and select welcom
 
 ## Run the app
 
-1. In a terminal window, run `npx rayfin up` to start the Rayfin backend.
-2. In a second terminal window run `npm run dev` to start the frontend.
+1. Sign in to Fabric with `npx rayfin login`.
+In an environment without OS credential storage, use `npx rayfin login --encryption-fallback-enabled` only if you accept plaintext token caching for development.
+2. In the same terminal window, run `npm run dev`.
+The command provisions or reuses the Fabric backend, applies declared state, and starts the frontend locally.
 3. When the frontend starts, it will output the page to visit.
 Visit and ensure you can view the Timestamp Tracker.
 4. Click **Send Timestamp** to POST the current time to `/api/graphql/Timestamp`, then use **Refresh list** to pull back the newest 100 entries.
 5. All UI plus data-fetching logic lives in a single file: `src/main.ts`.
-6. To point at a different backend, set `RAYFIN_PUBLIC_API_URL` in `rayfin/.env` and re-run `npm run dev` (defaults to `http://localhost:5168`).
+6. To target a specific Fabric workspace, set `RAYFIN_WORKSPACE_ID` and re-run `npm run dev`.
 
 ## Update the data model
 
@@ -94,7 +96,7 @@ After updating your data models, test your app.
 npm run dev
 ```
 
-> NOTE: Any changes to `rayfin.yml` require you to run `npx rayfin up` again.
+> NOTE: Restart `npm run dev` after changing `rayfin.yml` so the backend receives the updated declared state.
 
 ## View your local database
 

package/assets/docs/getting-started/index.md

@@ -8,15 +8,15 @@ title: Getting Started
 Rayfin supports two development paths.
 Choose the one that matches how you want to get started.
 
-### Local development
+### Inner-loop development
 
-Run the full Rayfin stack on your machine using Docker.
-This path is ideal for building and testing your application before deploying.
+Run frontend and Functions code locally against a managed Rayfin backend.
+Fabric is the default backend provider; the Docker provider is available separately as a preview.
+The default path requires a Microsoft account with Fabric access, an accessible workspace, and the tenant settings needed to create an AppBackend.
 
 1. Install prerequisites.
 1. Scaffold a project with `npm create @microsoft/rayfin@latest` or [add Rayfin to an existing app](../cli/quickstart.md#add-rayfin-to-an-existing-project).
-1. Start backend services with `npx rayfin up`.
-1. Run your frontend with `npm run dev`.
+1. Start the complete development session with `npm run dev` or `npx rayfin dev`.
 
 **Start here:** [Build your first Rayfin app](./create-app-with-cli.md)
 
@@ -34,7 +34,10 @@ This path requires a Microsoft account with Fabric access and tenant admin setti
 ## Prerequisites
 
 Install these tools before you begin with either path.
-Rayfin requires Node.js 20 or later, Docker Desktop (or Docker Engine on Linux), and the GitHub CLI.
+Rayfin requires Node.js 20 or later and the GitHub CLI.
+Docker Desktop or Docker Engine is required only for `rayfin dev --provider docker`.
+Fabric development also requires OS credential storage for the token cache.
+In dev containers, Codespaces, or Linux environments without a keychain, run `npx rayfin login --encryption-fallback-enabled` to explicitly allow the development-only plaintext fallback.
 
 ### Windows
 

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

@@ -15,6 +15,7 @@ your-project/
 │   │   ├── schema.ts
 │   │   └── *.ts
 │   ├── .env
+│   ├── .project.json
 │   ├── rayfin.yml
 │   └── tsconfig.json
 ├── src/
@@ -184,6 +185,16 @@ Configure an email provider for magic links, password resets, and email verifica
 `rayfin/.env` is an optional environment file used to supply values to `rayfin.yml` via interpolation.
 Do not commit secrets, and prefer a `rayfin/.env.example` file for documentation.
 
+### rayfin/.project.json
+
+`rayfin/.project.json` contains a random project-origin identifier created by `create-rayfin` when anonymous telemetry is enabled.
+The CLI uses it to correlate the original scaffold event with later `rayfin up` deployment events without storing user, machine, workspace, or project names.
+Commit this file so the project keeps the same scaffold lineage across machines, clones, and CI environments.
+You should not need to edit it.
+If you do not want deployments to share the scaffold lineage, you can safely delete `rayfin/.project.json`.
+Deployments continue to work and stop reporting the origin correlation.
+To keep the marker local, add it to `.gitignore` before committing it; if it is already tracked, remove it from source control.
+
 ### rayfin/data/*.ts
 
 Files in `rayfin/data/` define your entities.
@@ -280,7 +291,8 @@ export default defineConfig({
 ### Environment variables
 
 Rayfin manages environment variables through `rayfin/.env` using the `RAYFIN_PUBLIC_*` prefix convention.
-When you run `npm run dev`, the `predev` hook calls `rayfin env --framework vite` to generate a `.env.local` file with framework-specific variable names.
+When you run `rayfin dev` (or the scaffolded `npm run dev` wrapper), the CLI prepares backend wiring and generates a `.env.local` file with framework-specific variable names before starting the frontend child script.
+The file is written under `services.staticHosting.path` for nested frontends, or at the project root when no path is configured.
 When the CLI detects a Vite or Next.js project automatically, you can omit `--framework`.
 
 The following Vite variables are available in your frontend code after generation:
@@ -290,4 +302,5 @@ The following Vite variables are available in your frontend code after generatio
 - `VITE_RAYFIN_PUBLISHABLE_KEY` — Publishable key used for Rayfin client authentication.
   Sourced from `RAYFIN_PUBLIC_PUBLISHABLE_KEY` in `rayfin/.env`.
 
-To override values, edit `rayfin/.env` directly and re-run `rayfin env --framework vite` (or `npm run dev`, which triggers it automatically).
+To override values, edit `rayfin/.env` directly and restart `rayfin dev`.
+You can also run `rayfin env --framework vite` directly when you only need to regenerate the framework file.

package/assets/docs/hosting/index.md

@@ -69,14 +69,21 @@ After deployment, the CLI prints the hosting URL and stores it in `rayfin/.deplo
 
 #### Skip static deployment during local dev
 
-When iterating locally with `npm run dev` (Vite serves the frontend), pass `--exclude-services staticHosting` to deploy the backend without rebuilding and uploading the static bundle:
+Use `rayfin dev` for the normal inner loop.
+It provisions or reuses the backend and starts Vite locally without publishing static content:
+
+```bash
+rayfin dev
+```
+
+Existing scripts and automation can still run `up` while skipping the static build/package/deploy phase:
 
 ```bash
 rayfin up --exclude-services staticHosting
 ```
 
 This skips only the static build/package/deploy phase — runtime settings are still posted, so previously deployed static content keeps serving from Fabric.
-The scaffolded `npm run dev` script in every sample and template uses this flag.
+Rayfin's bundled samples and templates use `rayfin dev` instead.
 
 ### Standalone static deployment
 

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

@@ -5,15 +5,18 @@
 
 ## Overview
 
-The `rayfin dev` command provides a Docker Compose–based local development environment.
-It launches containers for enabled services, runs health checks, and auto-applies the database configuration.
+Bare `rayfin dev` uses the Fabric provider by default.
+Pass `--provider docker` to run the managed Rayfin backend and its services through Docker Compose instead.
+
+The provider changes only the backend location.
+The frontend and enabled functions always run as local processes during `rayfin dev`.
 
 Docker and Docker Compose must be installed and running before using this command.
 
 ## Starting the environment
 
 ```bash
-npx rayfin dev
+npx rayfin dev --provider docker
 ```
 
 This command:
@@ -23,8 +26,29 @@ This command:
 - Allocates ports for each service.
 - Starts containers for enabled services (WebService, database, and optional storage).
 - Runs health checks and waits for all services to be healthy.
+- Applies the project's declared data and storage 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.
+- 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`.
+
+The command remains attached to the frontend and Functions processes.
+Press `Ctrl+C` to stop the session and tear down the provider-owned containers.
+
+## Local functions and debugger
+
+When functions are enabled, `rayfin dev --provider docker` reserves the nearest free Functions port starting at `7071` and starts Azure Functions Core Tools.
+It writes the selected URL to `RAYFIN_PUBLIC_FUNCTIONS_URL` in `rayfin/.env` and regenerates the framework `.env.local` file.
+When functions are disabled, it removes a stale Functions URL instead.
 
-Wait for the `All services healthy` message before continuing.
+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.
+- Patches recognized `src/services/rayfinClient.ts` and `src/services/bootstrap.ts` files to pass `VITE_RAYFIN_FUNCTIONS_URL` as `functionsBaseUrl`.
+
+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.
+Use `--no-emit-env` to leave a hand-managed `.env.local` file unchanged.
 
 ## Stopping and resetting
 
@@ -32,22 +56,31 @@ Wait for the `All services healthy` message before continuing.
 |------|----------|
 | `--stop` | Stop running containers without removing them |
 | `--down` | Stop and remove containers |
-| `--purge` | Stop, remove containers, and delete volumes (full reset) |
+| `--provider docker --purge` | Confirm deletion of provider-owned Docker volumes when the attached session ends |
+| `--down --purge` | Confirm immediate container and volume deletion without starting a session |
+| `--export-env` | Print the retained Docker provider environment in `.env` format |
 
 ```bash
 npx rayfin dev --stop
 npx rayfin dev --down
-npx rayfin dev --purge
+npx rayfin dev --down --purge
+npx rayfin dev --export-env
+npx rayfin dev --provider docker --purge
 ```
 
+The retained `--stop`, `--down`, and `--export-env` maintenance actions operate only on Docker state.
+They do not start a workflow session or contact Fabric.
+Purge always requires interactive confirmation or global `--yes` in automation.
+It cannot be combined with `--stop` or `--export-env`.
+
 ## Additional options
 
 | Flag | Behavior |
 |------|----------|
-| `--detach` | Run containers in the background |
-| `--pull` | Pull latest images before starting |
-| `--verbose` | Show detailed Docker output |
-| `--debug` | Enable debug logging |
+| `--provider docker` | Select the Docker backend instead of the default Fabric backend |
+| `--skip-db-apply` | Skip automatic data configuration apply |
+| `--no-emit-env` | Leave the existing framework `.env.local` file unchanged |
+| `--verbose` | Show detailed diagnostic output |
 
 ## Subcommands
 
@@ -96,7 +129,7 @@ Changes to `rayfin.yml` require restarting the environment:
 
 ```bash
 npx rayfin dev --down
-npx rayfin dev
+npx rayfin dev --provider docker
 ```
 
 ## Troubleshooting
@@ -105,7 +138,8 @@ npx rayfin dev
 - **`rayfin dev db apply` fails** — make sure services are healthy first (`npx rayfin dev status`).
 - **Stale services** — stop stale containers with `npx rayfin dev --down`, then restart.
 - **`unsupported UUID` errors** — stop stale services with `npx rayfin dev --down`.
-- **Port conflicts** — use `npx rayfin dev --purge` for a full reset.
+- **Port conflicts** — stop the process using the reported port; Rayfin automatically slides the frontend, Functions, and inspector ports within bounded ranges.
+- **Functions host missing** — install Azure Functions Core Tools by running `npx rayfin dev functions apply`, then retry.
 
 ## Enabling this feature
 
@@ -120,3 +154,6 @@ Or combine with other flags:
 ```bash
 export RAYFIN_FEATURE_FLAGS=docker-local-dev,storage
 ```
+
+This feature flag gates only Docker provider selection and Docker maintenance commands.
+Bare `rayfin dev` is available without preview flags and uses Fabric.

package/package.json

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