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

package/assets/docs/auth/fabric.md

@@ -0,0 +1,328 @@
+---
+sidebar_position: 2
+---
+
+# Fabric Auth
+
+Fabric authentication lets users sign in to your Rayfin application with their existing Microsoft Entra identity through the Fabric Portal.
+No separate login form is needed — users authenticate once in Fabric and your app inherits that session automatically.
+
+The SDK supports two modes:
+
+- **Popup flow** — your app opens the Fabric Portal in a new browser tab, the user authenticates, and the tab closes automatically.
+- **Embedded flow** — your app runs inside a Fabric iframe and inherits the session via `postMessage` with no popup, redirect, or user interaction.
+
+Both flows are secured with PKCE S256, `postMessage` origin validation, and state nonces.
+
+## How it works
+
+### Popup flow
+
+1. Your app opens the Fabric Portal in a new browser tab and registers a `postMessage` listener.
+2. The user authenticates through Entra ID inside the Fabric Portal.
+3. The Fabric extension sends the handoff code back to your app via `window.top.opener.postMessage()`.
+4. The SDK exchanges the handoff code for Rayfin session tokens and creates a session.
+5. The Fabric tab is closed automatically.
+
+No callback page or redirect is needed.
+
+### Embedded flow (Fabric iframe)
+
+1. The Fabric Shell loads your app inside an iframe with `?fabricEmbedded=true` in the URL.
+2. On startup your app detects embedded mode and calls `initEmbeddedAuth()`.
+3. The SDK generates PKCE parameters in memory and sends `auth.requestHandoff` to the parent frame via `postMessage`.
+4. The Fabric Extension Host responds with a handoff code.
+5. The SDK exchanges the handoff code for Rayfin session tokens and creates a session.
+
+No popup, redirect, or user click is needed.
+
+## Enable Fabric auth
+
+Add the `fabric` section and your app's origin to `rayfin/rayfin.yml`:
+
+```yaml
+services:
+  auth:
+    enabled: true
+    allowedRedirectUris:
+      - http://localhost:5173
+    fabric:
+      enabled: true
+```
+
+The `allowedRedirectUris` list must include your app's bare origin (e.g. `http://localhost:5173`).
+The Fabric brokered auth flow uses the origin as the `postMessage` target for the handoff code.
+
+After changing `rayfin.yml`, redeploy the backend:
+
+```bash
+npx rayfin up
+```
+
+For a remote deployment, re-deploy to push the updated settings:
+
+```bash
+npx rayfin up
+```
+
+## Install the provider package
+
+The Fabric auth provider is a separate companion package:
+
+```bash
+npm install @microsoft/rayfin-auth-provider-fabric
+```
+
+## Client-side usage
+
+### Popup flow: sign in with a button click
+
+Call `ensureSignedInWithFabric` from a user-gesture handler (for example, a button click).
+Step 4 of the waterfall calls `window.open()`, so a user gesture is required to avoid popup blockers.
+
+```typescript
+import { RayfinClient } from '@microsoft/rayfin-client';
+import { ensureSignedInWithFabric } from '@microsoft/rayfin-auth-provider-fabric';
+
+const client = new RayfinClient({
+  baseUrl: 'http://localhost:5168',
+  publishableKey: 'pk-commonSampleAppKey',
+});
+
+async function handleSignIn() {
+  const session = await ensureSignedInWithFabric(client.auth, {
+    workspaceId: '<your-fabric-workspace-id>',
+    projectId: '<your-rayfin-item-id>',
+    fabricPortalUrl: 'https://app.fabric.microsoft.com',
+    returnOrigin: window.location.origin,
+  });
+  console.log('Signed in:', session.user);
+}
+```
+
+### Embedded flow: automatic authentication on startup
+
+Call `initEmbeddedAuth()` once at app startup (for example, in a React `useEffect` or initialization routine).
+It is safe to call on every page load — it returns `null` immediately when not in embedded mode.
+
+```typescript
+import { RayfinClient } from '@microsoft/rayfin-client';
+import { initEmbeddedAuth } from '@microsoft/rayfin-auth-provider-fabric';
+
+const client = new RayfinClient({
+  baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+});
+
+const fabricOptions = {
+  workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
+  projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
+  fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
+  returnOrigin: window.location.origin,
+};
+
+// Safe to call on every page load — no-op when not embedded.
+const session = await initEmbeddedAuth(client.auth, fabricOptions);
+if (session) {
+  console.log('Embedded session established:', session.user);
+}
+```
+
+Import `@microsoft/rayfin-auth-provider-fabric` statically in your app entry module rather than only via dynamic `import()`.
+The package captures the `?fabricEmbedded=true` URL flag into `sessionStorage` as a side effect at module load, and that must happen on the initial page load before any client-side navigation strips the query string (for example, a post-logout redirect to `/login`).
+Apps that resume from a stored refresh token never enter the embedded auth path on first load, so a dynamic-only import would miss the URL flag and fall back to the popup on the next sign-in.
+
+### Detecting embedded mode
+
+The SDK detects embedded mode when any of these conditions is true:
+
+- The `fabricEmbedded` option is set to `true` in `FabricAuthOptions`.
+- The URL contains the `?fabricEmbedded=true` query parameter.
+- A previous call already stored the flag in `sessionStorage`.
+
+You can check this manually:
+
+```typescript
+import { isEmbeddedMode } from '@microsoft/rayfin-auth-provider-fabric';
+
+const embedded = isEmbeddedMode({
+  workspaceId: '...',
+  projectId: '...',
+  fabricPortalUrl: '...',
+  returnOrigin: window.location.origin,
+});
+```
+
+### Supporting both flows
+
+Most apps should support both embedded mode (iframe) and the popup flow (standalone browser).
+`ensureSignedInWithFabric()` handles this automatically — it tries embedded auth first, then falls back to the popup:
+
+1. Return existing session if already authenticated.
+2. Attempt refresh via refresh token.
+3. If embedded mode is detected, use `postMessage` handoff (no popup).
+4. Otherwise, open the Fabric Portal in a new tab and wait for the handoff.
+
+For page-load initialization (no user gesture), use `initEmbeddedAuth()` instead.
+It skips step 4 and returns `null` when no embedded session is available.
+
+### React hook example
+
+```typescript
+import { useState, useCallback } from 'react';
+import { ensureSignedInWithFabric } from '@microsoft/rayfin-auth-provider-fabric';
+import { client } from './lib/rayfin';
+
+const fabricOptions = {
+  workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
+  projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
+  fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
+  returnOrigin: window.location.origin,
+};
+
+export function useFabricAuth() {
+  const [session, setSession] = useState(client.auth.getSession());
+
+  const signIn = useCallback(async () => {
+    const result = await ensureSignedInWithFabric(
+      client.auth,
+      fabricOptions
+    );
+    setSession(result);
+    return result;
+  }, []);
+
+  return { session, signIn, isAuthenticated: session?.isAuthenticated ?? false };
+}
+```
+
+## API reference
+
+### ensureSignedInWithFabric
+
+```typescript
+function ensureSignedInWithFabric(
+  auth: Auth,
+  options: FabricAuthOptions
+): Promise<OpaqueSession>;
+```
+
+The primary API.
+Implements a four-step waterfall where the first successful step short-circuits the rest:
+
+1. **Already authenticated** — returns the existing session.
+2. **Refresh token** — attempts to refresh the session silently.
+3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`), uses `postMessage` to acquire a session without a popup.
+4. **Open Fabric broker** — opens the Fabric Portal in a new tab, listens for the handoff code via `postMessage`, exchanges the code for tokens, and creates a session.
+
+Steps 1–3 are safe to call on page load.
+Step 4 opens a new browser tab and must run inside a user-gesture handler.
+
+### initEmbeddedAuth
+
+```typescript
+function initEmbeddedAuth(
+  auth: Auth,
+  options: FabricAuthOptions
+): Promise<OpaqueSession | null>;
+```
+
+Call once at app startup.
+Returns the authenticated session when running in embedded mode, or `null` when not embedded.
+Never opens a popup or new tab — safe for page-load use.
+
+**Waterfall:**
+
+1. Return existing session if authenticated.
+2. Attempt refresh via refresh token.
+3. Request handoff from the parent frame via `postMessage` and exchange for tokens.
+
+### initiateFabricLogin
+
+```typescript
+function initiateFabricLogin(
+  auth: Auth,
+  options: FabricAuthOptions
+): Promise<void>;
+```
+
+Low-level function that opens the Fabric Portal and listens for the postMessage handoff.
+Called internally by `ensureSignedInWithFabric` in step 4.
+Most apps should use `ensureSignedInWithFabric` instead.
+
+### FabricAuthOptions
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `workspaceId` | `string` | The Fabric workspace ID. |
+| `projectId` | `string` | The Rayfin item ID (AppBackend artifact ID). |
+| `fabricPortalUrl` | `string` | The Fabric Portal base URL (for example, `https://app.fabric.microsoft.com`). |
+| `returnOrigin` | `string` | Your app's origin (for example, `window.location.origin`). Used as the `postMessage` target origin. |
+| `fabricEmbedded` | `boolean` (optional) | When `true`, force embedded mode. The SDK also auto-detects embedded mode when `?fabricEmbedded=true` is in the URL. |
+
+## Security
+
+- **PKCE S256** — Every flow generates a cryptographic code verifier and challenge to prevent authorization code interception.
+- **State nonce** — A random nonce ties the postMessage response to the originating flow, preventing CSRF.
+- **In-closure code verifier** — The PKCE `code_verifier` is held in memory (closure) and never persisted to localStorage.
+- **Origin validation** — The SDK validates `event.origin` on incoming messages against `fabricPortalUrl`.
+  The Fabric extension uses an explicit `targetOrigin` (not `"*"`) when sending the handoff code.
+- **Flow timeout** — The flow times out after 5 minutes if no postMessage is received.
+- **Session isolation** — In embedded mode, the iframe's `localStorage` stores the session tokens, isolated from the parent frame by the browser's same-origin policy.
+
+## 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`.
+
+| Source variable (`rayfin/.env`) | Vite variable (`.env.local`) | Description | Example |
+| --- | --- | --- | --- |
+| `RAYFIN_PUBLIC_ITEM_ID` | `VITE_FABRIC_ITEM_ID` | The Fabric item ID (Fabric data app artifact ID). Maps to `projectId`. | `21b98705-08d5-448c-ab32-d88a3d00af41` |
+| `RAYFIN_PUBLIC_WORKSPACE_ID` | `VITE_FABRIC_WORKSPACE_ID` | The Fabric workspace ID. Maps to `workspaceId`. | `b80c0e39-468a-4742-8f0a-458dc6b1c918` |
+| `RAYFIN_PUBLIC_PORTAL_URL` | `VITE_FABRIC_PORTAL_URL` | The Fabric Portal base URL. Maps to `fabricPortalUrl`. | `https://app.fabric.microsoft.com/` |
+
+For local development, add these to `rayfin/.env`:
+
+```text
+RAYFIN_PUBLIC_ITEM_ID=<your-rayfin-item-id>
+RAYFIN_PUBLIC_WORKSPACE_ID=<your-fabric-workspace-id>
+RAYFIN_PUBLIC_PORTAL_URL=https://app.fabric.microsoft.com/
+```
+
+Then read them in your application code:
+
+```typescript
+const fabricOptions = {
+  workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
+  projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
+  fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
+  returnOrigin: window.location.origin,
+};
+```
+
+## 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`:
+
+```text
+RAYFIN_PUBLIC_ITEM_ID=<guid>
+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`.
+
+## Troubleshooting
+
+- **Popup blocked** — Call `ensureSignedInWithFabric` from a synchronous user-gesture handler (for example, a button `onClick`).
+  Calling it on page load or inside an `async` chain before the user clicks triggers popup blockers.
+- **Session not persisting** — Confirm the `RayfinClient` is configured with the correct `baseUrl` and `publishableKey`.
+- **Timeout after 5 minutes** — The handoff code was not received.
+  Check that `returnOrigin` matches your app's actual origin and that the Fabric extension is sending to the correct origin.
+- **Origin mismatch** — The `fabricPortalUrl` origin must match the origin of the Fabric Portal tab.
+  Verify you are using the correct URL for your environment (production, PPE, or dev).
+- **`initEmbeddedAuth` returns `null`** — Ensure the URL contains `?fabricEmbedded=true` or set `fabricEmbedded: true` in the options.
+- **Embedded handoff timeout** — The parent frame did not respond.
+  Verify that `returnOrigin` matches the iframe's actual origin.
+- **State mismatch error** — The response state did not match the request.
+  This can indicate a replay attack or a stale response from a previous flow.

package/assets/docs/auth/index.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 20
+---
+
+# Auth
+
+Rayfin Auth gives you managed user authentication, session handling, and token management so you can focus on your application instead of building identity infrastructure.
+One call to `signIn()` replaces hundreds of lines of auth plumbing, and every subsequent data call is automatically authenticated.
+
+## Why use Rayfin Auth
+
+- **Zero auth infrastructure** — User management, sessions, and token handling work out of the box with no external identity service to deploy or configure.
+- **Auth and data are pre-integrated** — After sign-in, every `client.data.*` call automatically carries the authenticated context.
+  No manual header management or token passing between modules.
+- **Automatic per-user data isolation** — JWT claims drive row-level security policies defined declaratively in your data model decorators.
+  Each user sees only the data they own without writing RLS SQL.
+- **Works in every deployment mode** — The same auth code runs identically in local Docker development, self-hosted environments, and managed Fabric hosting.
+  No code changes required when you move between environments.
+
+## Auth methods
+
+Rayfin supports multiple authentication methods that you can enable independently:
+
+- **Email and password** — Traditional sign-up and sign-in with managed credentials.
+  Enabled by default in new projects.
+- **Magic link** — Passwordless sign-in via email links.
+- **Fabric brokered auth** — Single sign-on through the Microsoft Fabric Portal using the user's Entra identity.
+  See [Fabric Brokered Auth](./fabric.md) for setup and usage.
+
+## Next steps
+
+- [How to configure auth](./overview.md)
+- [Fabric brokered auth](./fabric.md)

package/assets/docs/auth/overview.md

@@ -0,0 +1,130 @@
+---
+sidebar_position: 1
+---
+
+# Configure Rayfin Auth
+
+This guide explains how to configure Rayfin authentication in your application.
+`signUp`, `signIn`, `signOut`, and `getSession` cover most flows and return opaque session data managed by Rayfin.
+
+## Features
+
+- **Token management** - Access tokens never exposed to application code.
+- **Session Management** - Automatic state tracking with localStorage, sessionStorage, or custom storage.
+- **Event System** - React-friendly session change notifications.
+- **Server-side Compatible** - Works in Node.js with custom storage.
+
+## Auth client API surface
+
+The auth client exposes the following methods for sign-up, sign-in, session management, and lifecycle events:
+
+| Method | Description |
+| --- | --- |
+| `signUp({ email, password })` | Register a new user. |
+| `signIn({ email, password })` | Authenticate an existing user. |
+| `signOut()` | End the current session. |
+| `getSession()` | Return the current session (opaque; check `isAuthenticated` or `user`). |
+| `onSessionChange(callback)` | Subscribe to session state changes; returns an unsubscribe function. |
+
+> **Important**
+> The method name is `onSessionChange`, not `onAuthStateChange`.
+> `onAuthStateChange` does not exist on Rayfin's auth client.
+
+Session objects are opaque.
+Gate UI logic on the `isAuthenticated` flag or the presence of a `user` property rather than inspecting internal session fields.
+
+Restart the backend (`npx rayfin up`) whenever you enable or disable auth in `rayfin.yml` so the correct endpoints are exposed.
+
+## Configure auth settings
+
+The `rayfin.yml` can be used to configure your authentication service.
+
+Example:
+
+```yaml
+services:
+  auth:
+    enabled: true
+    allowedRedirectUris:
+      - http://localhost:5173
+    customClaims:
+      tenant: default
+      app_version: 1.0.0
+    scopes:
+      - read:data
+      - write:data
+    password:
+      enabled: true
+    fabric:
+      enabled: false
+    email:
+      enabled: false
+      provider: smtp
+      senderName: Rayfin Platform
+      verificationTokenExpirationHours: 24
+      passwordResetTokenExpirationMinutes: 30
+      smtp:
+        host: localhost
+        port: 1025
+        senderEmail: noreply@rayfin.local
+        username: ""
+        password: ""
+        useSsl: false
+        useStartTls: false
+        webPort: 1080
+```
+
+- Set `services.auth.enabled` to `true` to expose Rayfin managed auth endpoints.
+- Define any custom claims that your frontend will read from the session (tenant, roles, release channels, and so on).
+- Toggle `email.enabled` to `true` plus SMTP metadata if you want verification or password reset flows.
+- Set `fabric.enabled` to `true` to enable Fabric brokered authentication (Entra SSO through the Fabric Portal).
+  See [Fabric Brokered Auth](./fabric.md) for the full setup and client-side integration guide.
+- Restart `npx rayfin up` whenever this file changes so configuration is reloaded.
+
+## Initialize auth
+
+1. Import RayfinClient and instantiate it with your backend base URL plus the publishable key so API calls route to the correct Rayfin environment.
+2. Call `client.auth.signIn({ email, password })` to authenticate the current user; Rayfin manages session cookies and tokens internally.
+3. Retrieve the active session via `client.auth.getSession()`; checking `session.isAuthenticated` or `session.user` lets you gate UI logic.
+4. Once signed in, the same client instance automatically attaches the auth context to data calls, so you can call `client.data.Todo.getAll()` (or any other entity) without re-supplying credentials.
+
+```typescript
+import { RayfinClient } from '@microsoft/rayfin-client';
+
+const client = new RayfinClient({
+  baseUrl: 'http://localhost:5168',
+  publishableKey: 'pk-commonSampleAppKey',
+});
+
+await client.auth.signIn({ email, password });
+const session = client.auth.getSession();
+
+// Data API automatically authenticated
+await client.data.Todo.getAll();
+```
+
+## Using custom hook for React
+
+That hook keeps React in sync with the Rayfin auth session.
+
+- Grab the current session once on mount via `auth.getSession()` and store it in component state so the UI can react to updates.
+- Register `auth.onSessionChange(setSession)` inside `useEffect` to subscribe to Rayfin’s session events; anytime the backend refreshes or invalidates the session, your state updates automatically.
+- Because everything funnels through one hook, any component can read `useAuth()` to gate routes, show user info, or trigger login/logout flows with minimal boilerplate.
+
+```typescript
+import { useState, useEffect } from 'react';
+import { auth } from './lib/rayfin';
+
+export function useAuth() {
+  const [session, setSession] = useState(auth.getSession());
+
+  useEffect(() => auth.onSessionChange(setSession), []);
+
+  return {
+    ...session,
+    isAuthenticated: session?.isAuthenticated ?? false,
+    signIn: auth.signIn.bind(auth),
+    signOut: auth.signOut.bind(auth),
+  };
+}
+```

package/assets/docs/cli/ai-files.md

@@ -0,0 +1,146 @@
+---
+sidebar_position: 5
+---
+
+# Agent files (`rayfin init ai-files`)
+
+A "Rayfin agent file" is a piece of context that AI coding agents — Copilot CLI, GitHub Copilot in VS Code, Claude Code, Cursor, Gemini CLI, Codex, and friends — read on every task to know how to work with your project.
+
+The Rayfin CLI installs three of them in your project and keeps them in sync as the platform evolves:
+
+| File | Purpose | Who reads it |
+| --- | --- | --- |
+| `AGENTS.md` | Universal cross-agent instructions for your project. Plain English; lives at the project root. | Almost every modern coding agent. |
+| `.mcp.json` | Wires up the Rayfin MCP doc-lookup server so the agent can search Rayfin docs at task time. The CLI manages just the `mcpServers.rayfin` key — your other servers are preserved. | GitHub Copilot, VS Code Copilot, Claude Code, Cursor (some flavors). |
+| `.agents/skills/rayfin/SKILL.md` | A "Skill" that names Rayfin-specific rules and anti-patterns (decorators, permission rules, MSSQL constraints, deployment flow). | GitHub Copilot CLI, VS Code Copilot, Codex. |
+
+If you are new to coding agents, the short version is: **these three files together teach any agent how to work in a Rayfin project.** You drop them in once, they update with `rayfin-cli`, and you stop having to paste the same Rayfin context into chat over and over.
+
+## Quick start
+
+When you scaffold a project with `npm create @microsoft/rayfin@latest` or `rayfin init`, the CLI installs the agent files automatically as part of the post-scaffold pipeline. You usually do not need to run anything by hand.
+
+To install them in an existing project (or refresh them after upgrading the CLI):
+
+```bash
+npx rayfin init ai-files install
+```
+
+You will get an interactive checkbox picker the first time. Pass `--non-interactive` (or `--yes`) to accept defaults, or `--enable`/`--disable` to script it.
+
+To see what is installed and whether anything has drifted:
+
+```bash
+npx rayfin init ai-files status
+```
+
+To preview what `install` would do without touching disk:
+
+```bash
+npx rayfin init ai-files install -n --json
+```
+
+## What about my other agent config?
+
+The CLI is a careful neighbor:
+
+- `.mcp.json` is merged at the key level. Your other `mcpServers.<name>` entries are preserved on every install.
+- `AGENTS.md` is **one-time install**. If you (or your template) already wrote one, the CLI never overwrites it — even with `--force`. Add Rayfin-specific rules to it freely.
+- `.agents/skills/rayfin/SKILL.md` carries a `rayfin-managed: true` frontmatter sigil. If you remove that sigil, the CLI stops managing the file. That is the documented opt-out gesture for skills you want to fully customize.
+
+If you have hand-edited a managed file and do not want to lose your changes, the CLI flags it as `user-modified` and preserves your version with a warning. Choose either path:
+
+```bash
+# Keep your version, stop managing this item
+npx rayfin init ai-files install --disable skill:rayfin
+
+# Throw away your edits, accept the bundled version
+npx rayfin init ai-files install --force
+
+# Reset just one item (overwrite mcp; keep your edits to skill)
+npx rayfin init ai-files install --force mcp:rayfin
+```
+
+## Command reference
+
+### `rayfin init ai-files install`
+
+Installs or refreshes the Rayfin agent files. **Idempotent** — re-running auto-reconciles the project to the bundled content for your current CLI version. Re-running on an up-to-date project is a no-op (no disk writes).
+
+| Flag | Behavior |
+| --- | --- |
+| `--enable <id>` (repeatable) | Install/keep a specific item by its namespaced id (e.g. `--enable skill:rayfin`). Unknown ids are rejected with a clear error. |
+| `--disable <id>` (repeatable) | Stop managing a specific item — record the choice but do not delete the on-disk file. Also accepts orphan ids (items the lockfile remembers but the current CLI no longer ships). |
+| `--remove-files` | Modifier for `--disable`. Also removes the on-disk file. Cannot be passed alone. |
+| `--force [ids...]` | Overwrite items that have been hand-edited (`user-modified`), restore items that were deleted (`missing`), or rebuild after a malformed `.mcp.json`. Pass with no args to apply to every managed item. Pass one or more namespaced ids (e.g. `--force mcp:rayfin`) to scope force to those items only — others use default behavior. **Never** overwrites `AGENTS.md`. |
+| `--json` | Emit a `{status, schemaVersion, dryRun, report}` envelope to stdout instead of human progress lines. Implies non-interactive. |
+| `-n, --dry-run` | Classify what install would do and emit the report — no disk writes. Pairs with `--json` for previewability in scripts. |
+| `-y, --yes` / `--non-interactive` | Skip the interactive prompt and accept defaults. |
+
+#### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success, no warnings |
+| `1` | Hard error (invalid args, unknown id, malformed lockfile, write failure that was not isolated) |
+| `3` | Success, but warnings present (`user-modified` items preserved, `unreadable` sibling files, etc.). Distinct from `1` so agent consumers can tell "you should look at this" from "the command failed." |
+
+### `rayfin init ai-files status`
+
+Prints one line per managed item with its current state. Pass `--json` for `{status, schemaVersion, items: ItemStatus[]}` on stdout.
+
+States:
+
+| State | Meaning |
+| --- | --- |
+| `up-to-date` | On disk; sha matches lockfile and bundled content. Nothing to do. |
+| `update-available` | On disk; sha matches lockfile but the CLI now ships different bundled content. Run `install` to refresh. |
+| `user-modified` | On disk but the file hash does not match what the CLI last wrote. The CLI assumes you edited it intentionally. `install --force <id>` overwrites just that item; `install --disable <id>` keeps your version and stops managing. |
+| `missing` | The CLI installed it once, but the file is gone now. `install --force <id>` re-installs just that item. |
+| `not-installed` | The CLI knows about this item but it is not installed in the project yet. Plain `install` installs it. |
+| `disabled` | You opted out of managing this item (either via `install --disable <id>` or by removing the `rayfin-managed: true` sigil from a skill frontmatter). `install --enable <id>` re-enables. |
+| `orphaned` | The lockfile remembers an item the current CLI no longer ships. `install` cleans it up if it has not been touched, or warns if you have edited it. |
+| `unreadable` | The on-disk file exists but is malformed (e.g. invalid JSON in `.mcp.json`). Repair it by hand, or `install --force <id>` to rebuild just that item. |
+
+## How conflicts are resolved
+
+The CLI tracks what it wrote in a project-tracked lockfile at `rayfin/.lockfile.json` so re-runs know what they last installed and don't re-do work. Commit the lockfile so your team shares the same baseline.
+
+When you re-run `install`, the CLI compares the on-disk content against what it last wrote and against the bundled content for your current CLI version. That gives one of the eight states above. The conflict policy is:
+
+| State | Default | With `--force` |
+| --- | --- | --- |
+| `not-installed` | install | install |
+| `up-to-date` | no-op | no-op |
+| `update-available` | rewrite | rewrite |
+| `user-modified` | warn, preserve user content | overwrite with bundled |
+| `missing` | warn | re-install |
+| `disabled` (lockfile flag) | skip | skip — `--force` alone will not re-enable; pass `--enable <id>` |
+| `disabled` (sigil-removed skill) | skip | skip — pass `--enable <id> --force` to re-stamp the sigil |
+| `unreadable` | warn | overwrite (rebuilds from scratch) |
+| `orphaned` (clean) | delete (lockfile + disk) | delete |
+| `orphaned` (dirty) | warn, preserve | delete |
+| `orphaned` + `--disable <id>` | mark disabled, preserve file (does NOT enter cleanup) | mark disabled, preserve file |
+
+`--force` accepts an optional list of ids: `install --force mcp:rayfin` overwrites only `mcp:rayfin` and leaves the other items on default behavior. Useful when you want to refresh one file without losing intentional edits to others.
+
+When `install` warns about a `user-modified`, `missing`, or `unreadable` item, the warning recommends the per-item form (e.g. `rayfin init ai-files install --force skill:rayfin`). Following the warning's instruction will only touch that one item — unrelated user-modified items in the same project are not affected.
+
+## Drift nudge in `rayfin up`
+
+On every `rayfin up` startup, the CLI prints a one-line nudge if any managed item is out of date, modified, missing, unreadable, or newly-shipped. Refresh with `rayfin init ai-files install`. Upgrading `@microsoft/rayfin-cli` to a version that ships identical content does not produce a nudge — the check is content-based, not version-based.
+
+## Scripting and CI
+
+For agent or CI consumers, the structured `--json` output and exit code 3 (warning-only success) are first-class:
+
+```bash
+# Check if anything would change without writing
+npx rayfin init ai-files install -n --json
+
+# Idempotent install in CI; warnings exit 3, hard errors exit 1
+npx rayfin init ai-files install --yes --json
+
+# Inspect current state without writes
+npx rayfin init ai-files status --json
+```