@microsoft/rayfin-guide 1.35.0-alpha.1315 → 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/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 |

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