@microsoft/rayfin-guide 1.1.0 → 1.33.0-beta.1

package/assets/docs/cli/env-interpolation.md

@@ -0,0 +1,187 @@
+---
+sidebar_position: 2
+---
+
+# Environment Variable Interpolation
+
+Rayfin supports environment variable interpolation in `rayfin.yml` configuration files using Docker Compose-style syntax.
+This allows you to manage environment-specific values (connection strings, API keys, URLs) without hard-coding sensitive data in your configuration.
+
+## Syntax
+
+Rayfin supports two interpolation patterns:
+
+- `${VAR}` - Simple variable substitution (fails if variable is unset or empty).
+- `${VAR:-default}` - Substitution with default value if variable is unset or empty.
+
+Following Docker Compose semantics, the `:-` operator treats both undefined and empty string values as requiring the default.
+
+**Examples:**
+
+```bash
+# .env file
+DEFINED=value
+EMPTY=
+# UNDEFINED is not set
+```
+
+```yaml
+# rayfin.yml - Results:
+config1: ${DEFINED}             # → "value" (uses variable)
+config2: ${EMPTY:-fallback}     # → "fallback" (empty, uses default)
+config3: ${UNDEFINED:-fallback} # → "fallback" (unset, uses default)
+config4: ${DEFINED:-fallback}   # → "value" (defined, ignores default)
+config5: ${EMPTY}               # → Error! (empty without default)
+config6: ${UNDEFINED}           # → Error! (unset without default)
+```
+
+## Usage
+
+### Basic Substitution
+
+```yaml
+# rayfin.yml
+services:
+  data:
+    host: ${DB_HOST}
+    port: ${DB_PORT}
+```
+
+```bash
+# .env file (rayfin/.env)
+DB_HOST=localhost
+DB_PORT=5432
+```
+
+### Default Values
+
+Provide fallback values when environment variables are not set:
+
+```yaml
+services:
+  data:
+    host: ${DB_HOST:-localhost}
+    port: ${DB_PORT:-5432}
+```
+
+### Partial Interpolation
+
+Combine static text with variables:
+
+```yaml
+services:
+  auth:
+    issuer: https://${AUTH_DOMAIN}/oauth
+    connectionString: Server=${DB_HOST};Port=${DB_PORT};Database=${DB_NAME}
+```
+
+## .env File Location
+
+By default, Rayfin loads environment variables from `rayfin/.env`.
+You can customize this in three ways:
+
+1. **CLI argument** (highest priority):
+
+   ```bash
+   rayfin up --env-file /custom.env
+   rayfin up --env-file /production.env
+   ```
+
+2. **Environment variable**:
+
+   ```bash
+   export RAYFIN_ENV_FILE='/staging.env'
+   rayfin up
+   ```
+
+3. **Default**: `rayfin/.env`
+
+## Environment Priority
+
+When resolving variable values, Rayfin follows this priority:
+
+1. Shell environment variables (if non-empty).
+2. Variables from `.env` file (if non-empty).
+3. Default values (if specified with `:-` syntax and variable is unset or empty).
+4. Error if variable is unset or empty and no default is provided.
+
+## Type Coercion
+
+Rayfin automatically converts interpolated values to appropriate YAML types:
+
+```yaml
+# rayfin.yml
+services:
+  data:
+    port: ${DB_PORT}        # Becomes number 5432, not string "5432"
+    enabled: ${ENABLED}     # Becomes boolean true, not string "true"
+```
+
+```bash
+# .env
+DB_PORT=5432
+ENABLED=true
+```
+
+Type coercion only applies when the entire value is a variable reference.
+Partial interpolation always produces strings:
+
+```yaml
+url: http://localhost:${PORT}  # Results in string "http://localhost:5432"
+```
+
+## Example: Todo App Configuration
+
+```yaml
+# rayfin.yml
+id: ${PROJECT_NAME:-todo-app}
+
+services:
+  data:
+    enabled: ${DATA_ENABLED:-true}
+    connectionString: Server=${DB_HOST:-localhost};Port=${DB_PORT:-5432};Database=${DB_NAME:-tododb}
+
+  auth:
+    enabled: ${AUTH_ENABLED:-false}
+    issuer: ${AUTH_ISSUER}
+    audience: ${AUTH_AUDIENCE:-https://api.example.com}
+
+  storage:
+    enabled: ${STORAGE_ENABLED:-true}
+    accountName: ${STORAGE_ACCOUNT:-devstoreaccount1}
+```
+
+```bash
+# rayfin/.env
+PROJECT_NAME=my-todo-app
+DB_HOST=production-db.example.com
+DB_PORT=5432
+DB_NAME=todos_prod
+AUTH_ENABLED=true
+AUTH_ISSUER=https://auth.example.com
+STORAGE_ACCOUNT=prodstorageaccount
+```
+
+## Security Best Practices
+
+1. **Never commit `.env` files** - They contain secrets and environment-specific values.
+2. **Provide `.env.example`** - Document required variables for other developers.
+3. **Use shell environment in CI/CD** - Override `.env` with build and deployment secrets.
+4. **Validate required variables** - Omit default values for required configuration.
+
+## Error Handling
+
+Rayfin fails fast with clear error messages when variables are missing:
+
+```text
+❌ Environment variable 'DB_HOST' referenced in rayfin.yml (services.data.host) is not defined.
+   Set it in .env file or shell environment.
+```
+
+This prevents configuration errors from reaching runtime.
+
+## Environment Variable Reference
+
+### Special Variables
+
+- `RAYFIN_ENV_FILE` - Override default `.env` file path.

package/assets/docs/cli/env-migration.md

@@ -0,0 +1,135 @@
+# Environment file migration (CLI 1.17)
+
+Starting with Rayfin CLI 1.17.0, environment files are simplified from 10+ files across two directories down to **two runtime files**: `rayfin/.env` (gitignored) and `rayfin/.deployments.json` (gitignored).
+This guide covers what changed and what — if anything — you need to do.
+
+## Vite projects (most common)
+
+If your project uses Vite (the default for all Rayfin templates), **migration is automatic**.
+Run this command as you normally would:
+
+```bash
+npx rayfin up
+```
+
+The CLI does the rest:
+
+1. Detects `vite.config.ts` (or `vite` in `package.json`) and auto-generates `.env.local` with Vite-compatible variable names.
+2. Writes deployment or runtime values to `rayfin/.env` using the new `RAYFIN_PUBLIC_*` naming convention.
+
+**Your frontend code does not change.**
+`import.meta.env.VITE_RAYFIN_API_URL`, `import.meta.env.VITE_FABRIC_ITEM_ID`, and all other `VITE_*` variables resolve exactly as before.
+
+### After the first run
+
+You will see a warning listing leftover v1 files:
+
+```text
+⚠️  Detected env-strategy v1 artifacts. The Rayfin CLI no longer reads
+   these files; follow the steps below so your project keeps working.
+```
+
+Follow the printed instructions, then delete the stale files:
+
+```bash
+rm -f .env.fabric .env.fabric-*
+rm -f rayfin/.temp/.env
+```
+
+These files are harmless if left behind — the CLI ignores them — but removing them avoids confusion.
+
+### What the new layout looks like
+
+```text
+project-root/
+├── rayfin/
+│   ├── rayfin.yml               # committed (unchanged)
+│   ├── .env                     # gitignored — all runtime/deployment values
+│   ├── .env.example             # committed — documents expected variables
+│   └── .deployments.json        # gitignored — multi-deployment registry
+├── .env.local                   # gitignored — auto-generated by rayfin env
+└── vite.config.ts
+```
+
+## Next.js projects
+
+The same auto-detection applies.
+The CLI detects `next.config.*` (or `next` in `package.json`) and maps variables to `NEXT_PUBLIC_*` prefixes instead of `VITE_*`.
+
+## Projects without a detectable framework
+
+If the CLI cannot auto-detect your framework (no `vite.config.*`, `next.config.*`, or matching `package.json` dependency), pass the `--framework` flag explicitly:
+
+```bash
+npx rayfin env --framework vite
+```
+
+The CLI prints a hint when no framework is detected, so you will know if this step is needed.
+
+## Variable naming changes
+
+The underlying variable names changed from framework-specific (`VITE_*`) to framework-agnostic (`RAYFIN_PUBLIC_*`).
+The mapping is handled automatically by `rayfin env`:
+
+| `rayfin/.env` (new) | `.env.local` Vite output | `.env.local` Next.js output |
+|---|---|---|
+| `RAYFIN_PUBLIC_API_URL` | `VITE_RAYFIN_API_URL` | `NEXT_PUBLIC_RAYFIN_API_URL` |
+| `RAYFIN_PUBLIC_PUBLISHABLE_KEY` | `VITE_RAYFIN_PUBLISHABLE_KEY` | `NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY` |
+| `RAYFIN_PUBLIC_ITEM_ID` | `VITE_FABRIC_ITEM_ID` | `NEXT_PUBLIC_FABRIC_ITEM_ID` |
+| `RAYFIN_PUBLIC_WORKSPACE_ID` | `VITE_FABRIC_WORKSPACE_ID` | `NEXT_PUBLIC_FABRIC_WORKSPACE_ID` |
+| `RAYFIN_PUBLIC_PORTAL_URL` | `VITE_FABRIC_PORTAL_URL` | `NEXT_PUBLIC_FABRIC_PORTAL_URL` |
+
+You do not need to update your frontend code to use these names.
+The `.env.local` file emitted by `rayfin env` uses the framework-specific names your bundler expects.
+
+## Removed: `VITE_RAYFIN_HOSTING_URL`
+
+The `VITE_RAYFIN_HOSTING_URL` variable is no longer written to `.env.local`.
+The hosting URL is stored in `rayfin/.deployments.json` for reference only.
+If your frontend code reads this variable, replace it with a direct reference or remove the usage.
+
+## Multi-deployment management
+
+The per-workspace `.env.fabric-<workspace>` files are replaced by a single `rayfin/.deployments.json` registry.
+Two new commands manage deployments:
+
+```bash
+npx rayfin up list              # show all recorded deployments
+npx rayfin up switch staging    # switch active deployment, regenerate rayfin/.env
+```
+
+Switching a deployment regenerates both `rayfin/.env` and `.env.local` automatically.
+
+## Manual `rayfin env` usage
+
+If you need to regenerate `.env.local` without running `rayfin up`:
+
+```bash
+npx rayfin env --framework vite       # emit .env.local for Vite
+npx rayfin env --framework nextjs     # emit .env.local for Next.js
+npx rayfin env --show                 # print resolved variables without writing
+```
+
+When the `--framework` flag is omitted, `rayfin env` auto-detects from the project files:
+
+```bash
+npx rayfin env                        # auto-detects framework
+```
+
+## Edge cases
+
+### Custom variables in old `.env.fabric-*` files
+
+If you added custom variables (beyond the standard Rayfin set) to your old `.env.fabric-*` files, those are not migrated automatically.
+Add them to `rayfin/.env` after the first `rayfin up` run.
+
+### Existing Postgres password in `rayfin/.temp/.env`
+
+If you have a local database volume that depends on the generated `RAYFIN_POSTGRES_PASSWORD`, copy that value from `rayfin/.temp/.env` into `rayfin/.env` before running `rayfin up`.
+Otherwise the CLI generates a new password and the database connection fails until the volume is recreated.
+
+### `rayfin/.env` backup
+
+On the first CLI run after upgrading, the CLI backs up your existing `rayfin/.env` to `rayfin/.env.bak` before rewriting it in the new format.
+Variable values are preserved; comments and ordering are not.
+Diff the two files to recover any custom content.

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

@@ -0,0 +1,173 @@
+# Environment variables
+
+This page is the single reference for every environment variable that Rayfin tooling reads or writes.
+Variables are grouped by purpose and lifecycle.
+
+## Frontend-visible variables (`RAYFIN_PUBLIC_*`)
+
+These variables live in `rayfin/.env` and are the **only** variables exposed to frontend builds.
+The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to framework-specific names in `.env.local`.
+
+| 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_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` |
+| `RAYFIN_PUBLIC_PORTAL_URL` | Fabric Portal base URL (for example, `https://app.fabric.microsoft.com/`). | `rayfin up` |
+| `RAYFIN_PUBLIC_SERVICE_MODE` | `rayfin` (real backend) or `mock` (local testing). | User-set in `rayfin/.env` |
+
+### Framework mapping
+
+`rayfin env --framework <fw>` maps each `RAYFIN_PUBLIC_*` variable to a framework-specific name:
+
+| Source (`rayfin/.env`) | Vite (`.env.local`) | Next.js (`.env.local`) | Plain (`.env.local`) |
+| --- | --- | --- | --- |
+| `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_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` |
+| `RAYFIN_PUBLIC_PORTAL_URL` | `VITE_FABRIC_PORTAL_URL` | `NEXT_PUBLIC_FABRIC_PORTAL_URL` | `PORTAL_URL` |
+| `RAYFIN_PUBLIC_SERVICE_MODE` | `VITE_SERVICE_MODE` | `NEXT_PUBLIC_SERVICE_MODE` | `SERVICE_MODE` |
+
+Custom `RAYFIN_PUBLIC_*` variables you add follow a generic pattern: `RAYFIN_PUBLIC_FOO` becomes `VITE_RAYFIN_FOO` (Vite), `NEXT_PUBLIC_RAYFIN_FOO` (Next.js), or `FOO` (plain).
+
+## Tooling overrides
+
+These variables configure CLI and extension behavior.
+They are not exposed to the frontend (no `PUBLIC_` infix).
+Set them in `rayfin/.env` or as shell environment variables.
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `RAYFIN_FABRIC_API_URL` | Fabric REST API base URL the CLI calls. For canonical Fabric hosts (`*.fabric.microsoft.com`) accepts a bare origin (e.g. `https://api.fabric.microsoft.com`) or an `<origin>/v1` URL — extra path segments are stripped to maintain back-compat. For non-Fabric hosts (proxies, custom envs) accepts an origin plus path prefix (e.g. `https://my-proxy.example.com/cli-proxy/fabric/<id>`); the path prefix is preserved verbatim and `/v1` is appended only when the resolved path does not already end in `/v1`. Independent — set on its own, with `RAYFIN_FABRIC_PORTAL_URL`, or with the full authentication group. | `https://api.fabric.microsoft.com/v1` |
+| `RAYFIN_FABRIC_PORTAL_URL` | Fabric portal base URL used for deep links and `RAYFIN_PUBLIC_PORTAL_URL`. Independent — set on its own, with `RAYFIN_FABRIC_API_URL`, or with the full authentication group. | `https://app.fabric.microsoft.com/` |
+| `RAYFIN_ENV_FILE` | Path to an alternate `.env` file. Equivalent to `--env-file`. | `rayfin/.env` |
+
+When set on their own, the two Fabric endpoint variables apply only to the current process and are **not** persisted.
+Subsequent CLI invocations need the same shell or `rayfin/.env` value to keep using the override.
+
+Resolution precedence per variable: shell env var > value in `rayfin/.env` > persisted `environmentConfig` in `~/.rayfin/auth.json` > built-in default.
+
+### Routing through a credential proxy
+
+`RAYFIN_FABRIC_API_URL` accepts a non-Fabric origin with a path prefix on top, which lets you route the CLI's REST calls through a host that mounts the Fabric API under a sub-path (for example, a credential proxy that handles auth on the user's behalf).
+
+```sh
+export RAYFIN_FABRIC_API_URL="https://my-proxy.example.com/cli-proxy/fabric/<conn_id>"
+```
+
+For non-Fabric hosts, the CLI strips a trailing slash and appends `/v1` only when the resolved path does not already end in `/v1`, then composes the full request URL by appending `/workspaces/...` (and similar) to it.
+With the example above, a workspaces lookup goes to `https://my-proxy.example.com/cli-proxy/fabric/<conn_id>/v1/workspaces/...`.
+
+For canonical Fabric hosts (`*.fabric.microsoft.com`) the behavior is different: only the origin is honored and the path is replaced with `/v1`. This preserves the historical normalization for shapes like `https://api.fabric.microsoft.com/v1/workspaces/<id>` (which gets truncated back to `<origin>/v1` rather than producing a double-pathed result).
+
+The portal URL is **not** auto-derived from a non-`*.fabric.microsoft.com` host, so when you target a proxy you typically also want to set `RAYFIN_FABRIC_PORTAL_URL` to the portal you want deep links and `RAYFIN_PUBLIC_PORTAL_URL` to point at — usually production:
+
+```sh
+export RAYFIN_FABRIC_PORTAL_URL="https://app.fabric.microsoft.com/"
+```
+
+If your proxy also fronts the portal, point it there instead.
+
+> **Security: bearer token forwarding.** When `RAYFIN_FABRIC_API_URL` points at a non-`*.fabric.microsoft.com` host, the CLI sends the Fabric `Bearer <token>` it acquired (whether for the production scope or a custom `RAYFIN_FABRIC_SCOPE`) to that host on every REST call. Only set this to a host you trust to handle those tokens responsibly — typically a first-party credential proxy you operate. There is currently no startup warning or trusted-host allowlist; that is a known follow-up.
+>
+> **Known limitation: long-running operations.** Operations that return a `202` with a `Location` header are a known limitation in proxy mode. The CLI follows the absolute URL in `Location`, which usually points back at the upstream Fabric host and bypasses your proxy. End-to-end proxy support for these polled operations needs the proxy to rewrite `Location` headers (or the CLI to grow a host-rewrite pass on the polling target). Track the follow-up before relying on proxy mode for long-running ops.
+
+## Runtime port variables
+
+Written to `rayfin/.env` by `rayfin up` during port allocation.
+Each port starts at its default value and increments until a free port is found, so multiple projects can run side by side without conflict.
+Read via `${VAR:-default}` interpolation in the generated container configuration.
+
+| Variable | Default | Service | Docker profile |
+| --- | --- | --- | --- |
+| `RAYFIN_WEBSERVICE_HTTP_PORT` | 5168 | Rayfin WebService (HTTP) | always |
+| `RAYFIN_WEBSERVICE_HTTPS_PORT` | 7126 | Rayfin WebService (HTTPS) | always |
+| `RAYFIN_POSTGRES_PORT` | 5432 | PostgreSQL (admin database) | always |
+| `RAYFIN_POSTGRES_DATAAPI_PORT` | 5433 | PostgreSQL (Data API backend) | `data-api-postgresql` |
+| `RAYFIN_SQLSERVER_PORT` | 1433 | SQL Server (Data API backend) | `data-api-mssql` |
+| `RAYFIN_MAILDEV_SMTP_PORT` | 1025 | MailDev SMTP | `email` |
+| `RAYFIN_MAILDEV_WEB_PORT` | 1080 | MailDev web UI | `email` |
+| `RAYFIN_AZURITE_BLOB_PORT` | 10000 | Azurite Blob | `storage` |
+| `RAYFIN_AZURITE_QUEUE_PORT` | 10001 | Azurite Queue | `storage` |
+| `RAYFIN_AZURITE_TABLE_PORT` | 10002 | Azurite Table | `storage` |
+| `RAYFIN_FUNCTIONS_PORT` | 7071 | Azure Functions | `function` |
+| `RAYFIN_ASPIRE_UI_PORT` | 18888 | Aspire Dashboard UI | `telemetry` |
+| `RAYFIN_ASPIRE_OTLP_PORT` | 4317 | Aspire OTLP (gRPC) | `telemetry` |
+
+Port variables are cleaned up from `rayfin/.env` when `rayfin up` shuts down.
+
+## Database passwords
+
+Written to `rayfin/.env` by `rayfin up`.
+Passwords are generated on first run and preserved on subsequent runs so existing database volumes keep working.
+Never exposed to the frontend.
+
+| Variable | Default | Service |
+| --- | --- | --- |
+| `RAYFIN_POSTGRES_PASSWORD` | `YourStrong!Passw0rd` | PostgreSQL (admin database) |
+| `RAYFIN_SQLSERVER_PASSWORD` | `YourStrong!Passw0rd` | SQL Server |
+| `RAYFIN_POSTGRES_DATAAPI_PASSWORD` | `YourStrong!Passw0rd` | PostgreSQL (Data API backend) |
+
+## Service configuration flags
+
+Written to `rayfin/.env` by `rayfin up` based on `rayfin.yml` settings.
+Read by the Rayfin WebService container via the ASP.NET Core configuration system.
+
+| Variable | Source (`rayfin.yml`) | Values |
+| --- | --- | --- |
+| `Auth__Enabled` | `services.auth.enabled` | `true` / `false` |
+| `Data__Enabled` | `services.data.enabled` | `true` / `false` |
+| `Storage__Enabled` | `services.storage.enabled` | `true` / `false` |
+
+The following signing-key variables are set to dev-mode defaults by `rayfin up` and are not typically edited:
+
+- `Auth__AsymmetricKeys__Provider` — `local-file`
+- `Auth__AsymmetricKeys__Algorithm` — `ES256`
+- `Auth__AsymmetricKeys__KeySize` — `256`
+- `Auth__AsymmetricKeys__LocalFile__AutoGenerateKeys` — `true`
+
+## Shell-only variables
+
+These variables are read from the shell environment and are never written to files.
+
+| Variable | Description |
+| --- | --- |
+| `RAYFIN_TOKEN` | Pre-acquired Bearer token for headless or non-interactive usage. Bypasses interactive Entra ID login. Prefer `rayfin login --service-principal` which handles token acquisition automatically. Use `RAYFIN_TOKEN` when a token is already available from an external source (for example, `az account get-access-token`). |
+| `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_APPINSIGHTS_CONNECTION_STRING` | Override the telemetry endpoint for the CLI and VS Code extension. |
+
+### Recognized `RAYFIN_FEATURE_FLAGS` values
+
+| Flag | Effect |
+| --- | --- |
+| `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. |
+
+## File locations
+
+| Path | Purpose | Committed |
+| --- | --- | --- |
+| `rayfin/.env` | All runtime and deployment values. | No (gitignored) |
+| `rayfin/.env.example` | Documents expected variables with placeholder values. | Yes |
+| `rayfin/.deployments.json` | Multi-deployment registry (item IDs, API URLs, workspace IDs). | No (gitignored) |
+| `rayfin/rayfin.yml` | Project configuration, service toggles, frontend framework. | Yes |
+| `.env.local` | Framework-specific frontend variables, auto-generated by `rayfin env`. | No (gitignored) |
+| `~/.rayfin/auth-state.json` | CLI authentication state (tenant, account hints). | N/A (user home) |
+| `~/.rayfin/token-cache.json` | Encrypted token cache (OS-backed encryption). | N/A (user home) |
+
+## Resolution priority
+
+When the same variable is defined in multiple places, the value is resolved in this order (highest priority first):
+
+1. Shell environment variable.
+1. `--env-file <path>` CLI flag (or `RAYFIN_ENV_FILE`).
+1. `rayfin/.env` file.
+1. Default value (hardcoded or from `rayfin.yml` interpolation).

package/assets/docs/cli/index.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 40
+---
+
+# CLI
+
+Use the Rayfin CLI to scaffold projects, run local infrastructure, and apply schema changes.
+
+## Get started
+
+For installation instructions,
+see [CLI Installation](./installation.md).
+
+### Typical workflow
+
+```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
+```
+
+> **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.
+
+For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Build and deploy tutorial](../getting-started/create-app-with-cli.md).
+
+## Command reference
+
+### Project scaffolding
+
+| Command | Description |
+| --- | --- |
+| `npm install --save-dev @microsoft/rayfin-cli` | Install the Rayfin CLI as a dev dependency. Not needed if you scaffolded with `npm create @microsoft/rayfin@latest`. |
+| `npm create @microsoft/rayfin <name>` | Scaffold a new project from a template. Use `-t, --template <name>` to skip the interactive prompt or `--list-templates` to see available templates. |
+| `npx rayfin init [directory]` | Initialize a new Rayfin project interactively. Prompts for project name, services (Auth, Data), and auth methods. Creates the `rayfin/` directory with starter files. |
+| `npx rayfin init ai-files install` | Install or refresh the [agent context files](./ai-files.md) (`AGENTS.md`, `.mcp.json`, `.agents/skills/rayfin/SKILL.md`) so coding agents know how to work with your project. Idempotent; auto-runs as part of the scaffold pipeline. |
+| `npx rayfin init ai-files status` | Print the current state of each agent file. Add `--json` for machine-readable output. |
+
+> **Reconfiguring an existing project:** Running `npx rayfin init` in a project that already has a `rayfin/rayfin.yml` re-runs the interactive prompts and regenerates the configuration.
+> 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.
+
+### Deployment
+
+| Command | Description |
+| --- | --- |
+| `npx rayfin login` | Sign in with Entra ID for remote Fabric operations. The CLI stores auth state under `~/.rayfin/` and uses the OS keychain for token storage when available. Use `-t, --tenant <id>` to provide your Tenant ID for Fabric sign-in. Add `--select` to always show the MSAL account picker, ignoring any cached account. Pass `--encryption-fallback-enabled` only when login fails with a keychain error to allow plaintext token storage on systems without OS credential storage, such as some Linux distros, dev containers, and Codespaces. |
+| `npx rayfin login --service-principal` | Sign in as a service principal using client credentials. Requires `--client-id <id>`, `--client-secret <secret>`, and `-t, --tenant <id>`. Credentials are persisted so subsequent commands authenticate automatically. |
+| `npx rayfin login status` | Show the current sign-in status (account and tenant). |
+| `npx rayfin logout` | Sign out and clear cached auth state. |
+| `npx rayfin up` | Deploy the project to Microsoft Fabric. If you are not signed in, the CLI launches an interactive login flow. Use `-t, --tenant <id>` when your account spans multiple tenants, `-w, --workspace <name>` for a Fabric workspace display name, `-n, --dry-run` to preview without API calls, and `-v, --verbose` for detailed output. Pass `--encryption-fallback-enabled` only when login fails with a keychain error to allow plaintext token storage on systems without OS credential storage, such as some Linux distros, dev containers, and Codespaces. Use `--exclude-services staticHosting` to skip static content build/package/deploy while leaving runtime settings untouched — useful during local development when Vite serves the frontend. Applies runtime settings, database configuration, and static content when enabled. |
+| `npx rayfin up status` | Display the status of the Fabric deployment (add `--json` for machine-readable output). |
+| `npx rayfin up db apply` | Generate and apply DAB configuration to the remote Rayfin item. Add `--force` to allow changes that may cause data loss. |
+| `npx rayfin up staticapp deploy` | Build, package, and deploy static content to the remote Rayfin item. Add `--skip-build` to deploy existing build output without rebuilding. |
+
+## Update the CLI
+
+To get the latest version of the Rayfin CLI and its dependencies:
+
+```bash
+npm update --save
+npm install
+```
+
+Verify the installed version:
+
+```bash
+npx rayfin --version
+```
+
+## Telemetry
+
+The Rayfin CLI collects anonymous usage data to help improve the product.
+On the first run, the CLI displays a notice explaining what is collected and how to opt out.
+
+No personal data, parameter values, or file contents are collected.
+Only command names, execution status, execution duration, and environment metadata (OS, Node.js version) are recorded.
+
+To disable telemetry, set the following environment variable:
+
+```bash
+export RAYFIN_TELEMETRY_OPTOUT=1
+```

package/assets/docs/cli/installation.md

@@ -0,0 +1,107 @@
+---
+sidebar_position: 0
+---
+
+# CLI Installation
+
+The Rayfin CLI (`@microsoft/rayfin-cli`) scaffolds projects,
+runs local infrastructure, and deploys to Microsoft Fabric.
+This page covers how to install it and verify it is working.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20 or later
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+  (or Docker Engine on Linux) for local development
+
+## Installation
+
+### New project
+
+Scaffold a project from a template.
+This installs the CLI automatically as a dev dependency:
+
+```bash
+npm create @microsoft/rayfin@latest my-app
+cd my-app
+```
+
+### Existing project
+
+If you already have a project and want to add Rayfin,
+install the CLI as a dev dependency first:
+
+```bash
+npm install --save-dev @microsoft/rayfin-cli
+```
+
+Then run the interactive setup to create the `rayfin/`
+directory with starter configuration files:
+
+```bash
+npx rayfin init
+```
+
+## Verify the installation
+
+Confirm the CLI is available and check the installed version:
+
+```bash
+npx rayfin --version
+```
+
+You should see the version number printed to the terminal.
+
+Run `npx rayfin --help` to list all available commands:
+
+```bash
+npx rayfin --help
+```
+
+## First steps
+
+Start the backend services:
+
+```bash
+npx rayfin up
+```
+
+This launches the enabled services,
+runs health checks, and applies the database configuration.
+Wait for the deployment to complete before continuing.
+
+Apply schema changes after updating your data models:
+
+```bash
+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:
+
+```bash
+npm update --save
+npm install
+```
+
+Verify the update:
+
+```bash
+npx rayfin --version
+```
+
+## Next steps
+
+- [CLI Quickstart](./quickstart.md) for a full walkthrough
+  of creating, developing, and deploying a project.
+- [CLI command reference](./index.md) for the complete
+  list of commands and options.
+- [Build your first Rayfin app](../getting-started/create-app-with-cli.md)
+  for a step-by-step tutorial.