handoff-app 2.0.0-9 → 2.0.0

package/README.md

@@ -3,80 +3,436 @@
 <a aria-label="NPM version" href="https://www.npmjs.com/package/handoff-app">
   <img alt="" src="https://img.shields.io/npm/v/handoff-app?style=for-the-badge&labelColor=000000">
 </a>
-<a aria-label="License" href="https://github.com/convertiv/handoff-app/blob/main/License.md">
+<a aria-label="License" href="https://github.com/convertiv/handoff-app/blob/main/LICENSE.md">
   <img alt="" src="https://img.shields.io/npm/l/handoff-app?style=for-the-badge&labelColor=000000">
 </a>
 
-Design tokens, components, and patterns are turned by Handoff into working
-documentation and distributable artifacts. A local workspace, a static site,
-or a shared PostgreSQL-backed registry can be used.
+Handoff turns design tokens, components, and patterns into working
+documentation and distributable artifacts. You can serve the documentation
+from a local workspace, a static site, or a shared registry with a PostgreSQL
+database.
 
-## Runtime modes
+> **Recipes:** [RECIPES.md](RECIPES.md) has complete examples for project
+> layouts, catalog items, profiles, registry hosting, asset storage, email, and
+> the AI assistant.
 
-- **Workspace** is the default. Local files are the source of truth and no
-  database is required.
-- **Registry** is a deployed catalog backed by PostgreSQL.
-- A **connected workspace** remains in workspace mode but can publish to and
-  check out from a registry.
+> **Upgrade from version 1.x.x:** read the
+> [migration guide](UPGRADE.md#version-1xx-to-version-2xx) for the breaking
+> changes and the migration steps.
 
-Workspace mode is used by local projects for authoring. A separate
-registry-mode application is created automatically by a registry build.
+## Contents
+
+- [How Handoff works](#how-handoff-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Authoring](#authoring)
+- [Running the workspace](#running-the-workspace)
+- [Building](#building)
+- [Registry](#registry)
+- [Connecting a workspace to a registry](#connecting-a-workspace-to-a-registry)
+- [MCP](#mcp)
+- [AI assistant](#ai-assistant)
+- [CLI reference](#cli-reference)
+
+## How Handoff works
+
+### Runtime modes
+
+- **Workspace** is the default mode. Local files are the source of truth, and
+  no database is necessary. You use it to author content.
+- **Registry** is a deployed catalog with a PostgreSQL database. It stores and
+  serves only the content that a workspace publishes to it.
+- A **connected workspace** is a workspace that can publish to a registry and
+  check out from it. It is not a third mode.
+
+The `runtime.mode` value in the config sets the mode. A registry build sets
+registry mode automatically, so the base config stays in workspace mode.
+
+### Workflow
+
+```text
+Figma            ── fetch ──▶  exported/      tokens, CSS, Sass, assets
+catalog, pages   ── start ──▶  local documentation at http://localhost:3000
+                 ── build ──▶  out/static (static site) or out/registry (registry server)
+workspace        ── publish ─▶ registry ── checkout ─▶ workspace
+```
+
+The workspace is the only place that builds content. A registry never builds
+and never reads workspace source.
+
+### Terms
+
+- **Working directory:** the directory that holds `handoff.config.ts`. Every
+  command runs against it.
+- **Catalog item:** one documented UI entry. It has a declaration file, a
+  stable id, and previews.
+- **Component:** a catalog item with an implementation (React, Handlebars, or
+  CSF).
+- **Pattern:** a catalog item that is a composition of other catalog items.
+- **Foundations:** the tokens and assets that `fetch` gets from Figma.
+- **Page:** a Markdown documentation page under `pages/`.
+- **Profile:** a config file that merges onto the base config for one
+  environment.
 
 ## Requirements
 
-- Node.js 18.18 or newer; Node.js 20 LTS or newer is recommended
-- npm 8 or newer
-- A paid Figma account when fetching a Figma library
-- PostgreSQL when running a registry
+- Node.js 22 or newer. We recommend Node.js 24 LTS.
+- npm 10 or newer.
+- A paid Figma account, to fetch a Figma library.
+- PostgreSQL, to run a registry.
 
-## Quick start
+## Installation
 
-A project is created with the interactive wizard:
+### New project
+
+Create a project with the interactive wizard:
 
 ```bash
 npx handoff-app init
 cd my-handoff-project
 ```
 
-The project name, sample content, JavaScript or TypeScript, optional Vercel
-setup, and optional Figma credentials are requested by the wizard. Starter
-files are created and `handoff-app` is installed locally. Generated npm scripts
-are used for project operations so the pinned project version is shared by
-local development and CI:
+The wizard asks for the project name, sample content, JavaScript or
+TypeScript, an optional Vercel setup, and optional Figma credentials. It
+creates the starter files and installs `handoff-app` in the project.
+
+Use the generated npm scripts. They run the project version of `handoff-app`,
+so local development and CI use the same version:
 
 ```bash
 npm run fetch       # optional: fetch Figma foundations
 npm run start       # local server with Handoff file watchers
 npm run dev         # local development server without Handoff file watchers
 npm run build       # static build by default
+npm run publish     # publish to a registry
+npm run checkout    # check out from a registry
+npm run login       # sign in to a registry
+npm run logout      # sign out of a registry
 npm run db:migrate  # registry database migrations
-npm run validate
 ```
 
-## Project layout
+### Project layout
 
 ```text
-my-handoff-project/
+<working directory>/
 ├─ handoff.config.ts
 ├─ .env
 ├─ components/
 ├─ patterns/
 ├─ pages/
 ├─ exported/       # fetched tokens and assets; commit this directory
-└─ out/            # build output; gitignored
+├─ public/api/     # generated docs API; gitignored
+├─ out/            # build output; gitignored
+├─ .vercel/        # `--package vercel` output; gitignored
+└─ .handoff/       # local Handoff state; gitignored
+```
+
+In a project that `init` creates, the working directory is the repository
+root. `HANDOFF_WORKING_PATH` sets a different working directory.
+
+### Adding Handoff to an existing application
+
+Declarations sit next to the components that they document. Thus the catalog
+points into the application source:
+
+```ts
+catalog: { include: ['src/components', 'src/blocks'] },
+```
+
+Two rules apply to every layout.
+
+**`handoff-app` must be a dependency of the package that holds the
+`*.handoff.ts` files.** A declaration imports `handoff-app/react`. Handoff
+resolves that import from the directory of the declaration, not from the
+directory of the config. With npm, hoisting usually hides a missing dependency.
+With pnpm, Handoff skips the affected items with
+`Could not resolve "handoff-app/react"`, and the build still exits with code 0.
+In a workspace-package layout, the application package and the `handoff/`
+package must both declare `handoff-app`.
+
+**Two `tsconfig.json` files do different jobs:**
+
+- The config nearest to the declarations type checks them. An editor reads
+  only the nearest config. A config in a different directory that includes
+  `src/` does not count.
+- The config in the working directory makes the property tables. Without it,
+  Handoff shows `TypeScript config not found`, and every table is empty.
+
+If the working directory is not the project root, you need both files.
+
+Three layouts work. Each keeps one dependency tree, so the catalog renders the
+real components with the same React instance. Handoff does not support a
+separate install with its own `node_modules` outside that tree.
+
+| Layout | Working directory | Use when |
+| --- | --- | --- |
+| Subdirectory (recommended) | `handoff/`, set by `HANDOFF_WORKING_PATH` | The application must not change |
+| Project root | The project root | The bundler can move its `public/` directory (not Next.js) |
+| Workspace package | `handoff/`, with its own `package.json` | The repository is already a workspace |
+
+In the project-root layout, Handoff writes the generated documentation API to
+`public/api`. Thus a bundler that serves `public/` copies it into the
+production build of the application. Move the bundler to a different
+directory. A Next.js application cannot move its `public` directory, so it
+cannot use this layout.
+
+With pnpm, `build --target registry` cannot follow the pnpm symlinks. Set
+`nodeLinker: hoisted` in `pnpm-workspace.yaml`. The other builds work with the
+default pnpm layout.
+
+To add Handoff in the recommended subdirectory layout:
+
+1. Install `handoff-app` in the application package:
+
+   ```bash
+   npm install handoff-app
+   ```
+
+2. Create `handoff/handoff.config.ts`. Point the catalog at the application
+   source, and load the global stylesheet of the application into the
+   previews:
+
+   ```ts
+   import { defineConfig } from 'handoff-app';
+
+   export default defineConfig({
+     app: { title: 'Acme Design System' },
+     catalog: { include: ['../src/components'] },
+     entries: { scss: '../src/styles/main.scss' },
+   });
+   ```
+
+   Paths are relative to the working directory. `npx handoff-app eject:config`
+   writes the full default config instead.
+
+3. Create `handoff/tsconfig.json`, so that Handoff can make the property
+   tables:
+
+   ```json
+   { "extends": "../tsconfig.json", "include": ["../src", "handoff.config.ts"] }
+   ```
+
+4. Add the scripts to the `package.json` of the application:
+
+   ```json
+   {
+     "scripts": {
+       "handoff:dev": "HANDOFF_WORKING_PATH=handoff handoff-app start",
+       "handoff:build": "HANDOFF_WORKING_PATH=handoff handoff-app build"
+     }
+   }
+   ```
+
+5. Write a declaration next to a component, for example
+   `src/components/button/button.handoff.ts`. The
+   [Catalog items](#catalog-items) section shows the format.
+
+6. Start the documentation:
+
+   ```bash
+   npm run handoff:dev
+   ```
+
+7. Add `handoff/public/api`, `handoff/out`, `handoff/.handoff`, and
+   `handoff/.vercel` to `.gitignore`. Commit `handoff/exported` if you fetch
+   from Figma.
+
+> **Recipes:** [Subdirectory](RECIPES.md#handoff-in-a-subdirectory) ·
+> [Project root](RECIPES.md#handoff-in-the-project-root) ·
+> [Workspace package](RECIPES.md#handoff-as-a-workspace-package) ·
+> [pnpm](RECIPES.md#pnpm) · [npm scripts on Windows](RECIPES.md#npm-scripts-on-windows)
+
+## Configuration
+
+### Config file
+
+Handoff reads `handoff.config.ts`, `.js`, `.cjs`, or `.json`, in that order.
+`-c, --config <file>` loads one specific file instead. `defineConfig` gives
+typed authoring:
+
+```ts
+// handoff.config.ts
+import { defineConfig, fromEnv } from 'handoff-app';
+
+export default defineConfig({
+  app: { title: 'Acme Design System' },
+  catalog: { include: ['components', 'patterns'] },
+  runtime: {
+    mode: 'workspace',
+    workspace: { declarationFormat: 'ts' },
+    registry: {
+      database: { url: fromEnv('DATABASE_URL'), driver: 'pg' },
+    },
+  },
+});
 ```
 
-## Catalog items
+Values merge onto the defaults. Plain objects merge recursively. Arrays,
+scalars, `null`, and functions replace the default.
+
+### Main settings
+
+| Setting | Purpose |
+| --- | --- |
+| `app.title`, `app.client` | Name of the documentation site and of the client |
+| `app.theme` | Theme of the documentation app. `npx handoff-app eject:theme` copies it so that you can change it. |
+| `app.basePath` | URL path of the site when you serve it under a sub-path, for example `/design-system` |
+| `app.breakpoints` | Preview widths. A declared block merges onto the defaults. |
+| `app.ports` | Workspace server ports, `{ app, websocket }`. The defaults are 3000 and 3001. |
+| `catalog.include` | Catalog directories. See [Registration](#registration). |
+| `entries.scss`, `entries.js` | Global stylesheet and script that Handoff builds and loads into every preview |
+| `integrations.figma` | Figma file and token. See [Figma foundations](#figma-foundations). |
+| `exportsOutputDirectory` | Directory for fetched foundations. The default is `exported`. |
+| `sitesOutputDirectory` | Directory for build output. The default is `out`. |
+| `runtime.mode` | `workspace` (default) or `registry` |
+| `runtime.workspace.declarationFormat` | Format of the declarations that `checkout` writes: `ts`, `js`, or `cjs` |
+| `runtime.registryConnection` | Registry URL and token of a connected workspace |
+| `runtime.registry` | Registry database, asset storage, and email. See [Registry](#registry). |
+| `runtime.mcp` | MCP endpoint on or off. See [MCP](#mcp). |
+| `runtime.ai` | AI assistant. See [AI assistant](#ai-assistant). |
+| `hooks` | Build hooks, documented in [docs/api.md](docs/api.md) |
+
+The `Config` type documents every setting. Several settings read an environment
+variable by default. [Environment variables](#environment-variables) lists them.
+
+### Build-time and runtime values
+
+`fromEnv('NAME')` refers to an environment variable. It does not copy the
+value into the config.
+
+- A literal value is baked into the build.
+- For a `fromEnv()` value, the build keeps only the variable name. A deployed
+  registry reads the value at request time. Thus you can change it without a
+  rebuild.
+- Secrets must use `fromEnv()`.
+
+Some settings change the shape of the build. These settings are baked, so a
+change to a deployed registry needs a rebuild:
+
+- `runtime.mode`
+- `runtime.mcp`
+- `runtime.ai.enabled`
+- The database driver
+- The asset storage provider and the email provider
+- Every custom server module
+
+### Profiles
+
+A profile is a config file that merges onto the base config. It holds only what
+changes between environments. Thus a project keeps one shared config, not a
+second full copy.
+
+- The base config is `handoff.config.ts`, `.js`, `.cjs`, or `.json`. When no
+  profile is selected, Handoff loads only this file.
+- A profile file is `handoff.config.<profile>.*`, with the same four
+  extensions.
+- Select a profile with `--profile <name>` or with `HANDOFF_PROFILE`.
+  `--profile` has priority over `HANDOFF_PROFILE`.
+- Profile names are not predefined. A name can contain lowercase letters,
+  numbers, and hyphens.
+- A selected profile must exist. If no `handoff.config.<name>.*` file exists,
+  the command stops with an error.
+- `login`, `logout`, `publish`, and `checkout` also accept a profile that has
+  only a saved registry login. For these commands, the profile selects the
+  registry. Every other command needs the config file.
+- Layers apply in this order: defaults, base config, profile, then
+  programmatic config. The [merge rules](#config-file) apply to each layer.
+- A selected profile also reads `.env.<profile>` on top of `.env`, if that file
+  exists. Handoff reads both files from the directory where the command runs. A
+  variable that is already in the environment has priority over both files.
+
+```bash
+npx handoff-app build --target registry --profile registry
+```
+
+A profile is a good place for the registry build settings: the database
+driver, the database variable name, the asset storage, the email provider, and
+MCP. `build --target registry` always builds a registry-mode application, so
+the profile does not set `runtime.mode`. A hosting provider or a CI job selects
+the profile with `HANDOFF_PROFILE`.
+
+`defineConfig` types a profile and a base config the same way. The generated
+`.gitignore` lists `handoff.config.local.*`. Thus `local` is the usual name for
+a profile that stays on one machine.
+
+Arrays replace. Thus a profile that declares `catalog.include` also controls
+what `make:component` and `checkout` register.
+
+Handoff reads `.env.<profile>` once at startup and does not watch it. It cannot
+set `HANDOFF_WORKING_PATH`, because Handoff finds the working path before it
+knows the profile.
+
+> **Recipes:** [Local profile](RECIPES.md#local-profile) ·
+> [Registry build profile](RECIPES.md#registry-build-profile) ·
+> [One workspace, several registries](RECIPES.md#one-workspace-several-registries)
+
+### Environment variables
+
+Handoff reads two kinds of variables:
+
+- **Fixed variables.** Handoff always reads these names.
+- **Setting defaults.** Each one is the default `fromEnv()` name of a setting.
+  To use a different name, set the setting to `fromEnv('YOUR_NAME')`.
+
+This section does not list the variables that you name in the config. Examples
+are the keys of a custom asset storage provider or of an AI connection. A
+standalone registry build writes `out/registry/README.md`, which lists every
+variable that the build needs, with the names from your config.
+
+**Fixed variables**
+
+| Variable | Purpose |
+| --- | --- |
+| `HANDOFF_PROFILE` | Config profile merged onto the base config |
+| `HANDOFF_WORKING_PATH` | Directory that holds `handoff.config.ts`. The default is the current directory. |
+| `HANDOFF_LOG_LEVEL` | `debug`, `info`, `warn`, `error`, or `silent`. The default is `info`. |
+| `HANDOFF_LOG_SCOPES` | Comma-separated log sources: `handoff`, `vite`, `next`. The default is all three. |
+| `HANDOFF_LOGIN_NO_BROWSER` | Set to `true` to stop `login` from opening a browser, the same as `--no-browser` |
+| `HANDOFF_CREATE_ASSETS_ZIP_FILES` | Set to `false` to skip the icon and logo zip files in `fetch` |
+| `HANDOFF_SYNC_SECRET` | Optional deployment-wide credential with read and write access. The registry accepts it. A workspace uses it only when it has no token and no login. |
+| `AUTH_SECRET` | Registry session-signing secret, at least 32 characters. Required by a registry. |
+| `AUTH_URL` | Canonical public registry URL, with the base path. Required by a registry. |
+| `PORT` | Standalone registry server port |
+| `HOSTNAME` | Standalone registry server bind hostname |
+| `HANDOFF_AI_KEY_SECRET` | Encrypts the AI provider keys of readers, at least 32 characters |
+| `HANDOFF_AI_CONNECTIONS` | JSON array of AI connections, merged over the built-in list by `id` |
+
+**Setting defaults**
+
+| Variable | Setting | Purpose |
+| --- | --- | --- |
+| `HANDOFF_FIGMA_PROJECT_ID` | `integrations.figma.projectId` | Figma file ID that `fetch` uses |
+| `HANDOFF_DEV_ACCESS_TOKEN` | `integrations.figma.accessToken` | Figma personal access token that `fetch` uses |
+| `HANDOFF_REGISTRY_URL` | `runtime.registryConnection.url` | Registry URL of a connected workspace |
+| `HANDOFF_REGISTRY_ACCESS_TOKEN` | `runtime.registryConnection.accessToken` | Registry access token of a connected workspace |
+| `DATABASE_URL` | `runtime.registry.database.url` | PostgreSQL connection string. Required by a registry. |
+| `HANDOFF_APP_PORT` | `app.ports.app` | Workspace documentation server port. The default is 3000. |
+| `HANDOFF_WEBSOCKET_PORT` | `app.ports.websocket` | Workspace live-reload server port. The default is 3001. |
+| `HANDOFF_OUTPUT_DIR` | `exportsOutputDirectory` | Fetched output directory. The default is `exported`. |
+| `HANDOFF_SITES_DIR` | `sitesOutputDirectory` | Build output directory. The default is `out`. |
+
+Keep the name `HANDOFF_OUTPUT_DIR`. The documentation app also reads this
+variable directly.
+
+## Authoring
+
+### Catalog items
 
-Every documented UI entry is a catalog item. Each item declares either an implementation or a composition of other items.
-An implementation names its renderer. `defineCatalogItem` comes from the module for that renderer.
-The declaration supplies stable identity, documentation metadata, source entries, and previews.
+Every documented UI entry is a catalog item. An item declares one of these:
 
-### React
+- An `implementation`, which names a renderer: React, Handlebars, or CSF.
+  The registry stores the item as a component.
+- A `composition` of other items. The registry stores the item as a pattern.
 
-Handoff finds the implementation file from its import, so you do not need to repeat the path, and
-builds the item's CSS from the stylesheets that import chain pulls in, descendants included.
-Previews are named exports. `Preview<typeof item>` gives them the implementation's argument type.
+An item never declares both. `defineCatalogItem` comes from the module of the
+renderer. The declaration gives the stable id, the documentation metadata, the
+source entries, and the previews.
+
+**React.** Handoff finds the implementation file from its import, so you do not
+repeat the path. Handoff builds the CSS of the item from the stylesheets that
+the import chain loads, descendants included. Previews are named exports.
+`Preview<typeof item>` gives them the argument type of the implementation.
 
 ```tsx
 // components/example/Component.tsx
@@ -112,88 +468,23 @@ export const Default = {
 } satisfies ComponentPreview;
 ```
 
-The export name is the preview name. Use `name` to set a different display title.
+The export name is the preview name. `name` sets a different display title.
+Handoff serializes the arguments. Thus a preview that needs an icon, a
+callback, JSX children, or its own state declares a `render` function. A
+declaration that holds JSX must use the `.handoff.tsx` extension.
 
-Arguments are serialized, so a preview that needs an icon, a callback, JSX children, or its own
-state declares `render` instead. It renders as a component, so a capitalized name lets it use hooks, and the item keeps
-documenting the implementation rather than a wrapper. Name a declaration that holds JSX
-`example.handoff.tsx`.
+**Handlebars.** The implementation is the path to the template:
+`implementation: './Badge.hbs'`, from `handoff-app/handlebars`.
 
-```tsx
-export const Interactive = {
-  render: function Interactive() {
-    const [label, setLabel] = useState('Example');
-    return <Component label={label} onSelect={() => setLabel('Selected')} />;
-  },
-} satisfies ComponentPreview;
-```
-
-### Handlebars
+**CSF.** A React item uses an existing story file with
+`implementation: fromCSF('./Card.stories.tsx')`. The story file does not
+change, and its named exports are the previews. The server renders a CSF
+preview, and the browser does not hydrate it. The browser hydrates a direct
+React implementation.
 
-The implementation is the path to the template. Arguments are `Record<string, unknown>` by default;
-an explicit argument type is supplied through `defineCatalogItem<BadgeArgs>`.
-
-```ts
-// components/badge/badge.handoff.ts
-import { defineCatalogItem, type Preview } from 'handoff-app/handlebars';
-
-const item = defineCatalogItem({
-  id: 'badge',
-  name: 'Badge',
-  implementation: './Badge.hbs',
-});
-
-export default item;
-
-type BadgePreview = Preview<typeof item>;
-
-export const Primary = {
-  args: { variant: 'primary', children: 'New' },
-} satisfies BadgePreview;
-```
-
-### CSF
-
-CSF is a source format. A story file uses the renderer from the module that declares it. A React item references an existing CSF file with `fromCSF`.
-The CSF file stays unchanged and defines its previews through named exports. Each story's `args` merge with and override `meta.args`.
-Handoff preserves story names, `argTypes`, and `render` functions.
-It finds the React component through `meta.component`, then documents and publishes it with the story file.
-
-```ts
-// components/card/card.handoff.ts
-import { defineCatalogItem, fromCSF } from 'handoff-app/react';
-
-export default defineCatalogItem({
-  id: 'card',
-  name: 'Card',
-  implementation: fromCSF('./Card.stories.tsx'),
-});
-```
-
-`Meta` and `StoryObj` are exported from `handoff-app/react`, so a story file type-checks without a
-Storybook dependency. A project that already has Storybook keeps using its own types.
-
-```tsx
-// components/card/Card.stories.tsx
-import { type Meta, type StoryObj } from 'handoff-app/react';
-import Card from './Card';
-
-const meta = { component: Card } satisfies Meta<typeof Card>;
-export default meta;
-
-export const Primary: StoryObj<typeof meta> = {
-  args: { title: 'Example' },
-};
-```
-
-A CSF preview is rendered on the server and is not hydrated. A direct React implementation is
-hydrated in the browser.
-
-### Compositions
-
-A composition references other items by stable id. A named preview can be selected and its arguments
-can be overridden by each reference. A composition needs no renderer, so it is declared with
-`defineCatalogItem` from `handoff-app/pattern`.
+**Compositions.** A composition references other items by stable id. Each
+reference can select a named preview and override its arguments. A composition
+needs no renderer, so it uses `defineCatalogItem` from `handoff-app/pattern`:
 
 ```ts
 // patterns/example/example.handoff.ts
@@ -211,233 +502,353 @@ export default defineCatalogItem({
 });
 ```
 
-An item declares `implementation` or `composition`, never both. Terms such as atom, element, and
-block stay optional classification metadata on `type` and `categories`.
-
-The `id` addresses the item everywhere: its artifacts, its documentation URL, and its publish and
-checkout commands. Components and patterns share one namespace, so each id must be unique across
-both.
+**Ids.** The `id` addresses the item everywhere: its artifacts, its
+documentation URL, and the `publish` and `checkout` commands. Components and
+patterns share one namespace, so each id must be unique across both. If two
+declarations use one id, Handoff keeps the first, skips the second, and names
+both files in a warning. `publish` does not run until each id is unique.
 
-If two declarations claim one id, Handoff keeps the first and skips the second. The warning names
-both files. `publish` refuses to run until each id is unique.
+Terms such as atom, element, and block are optional classification metadata on
+`type` and `categories`.
 
+> **Recipes:** [React preview with a render function](RECIPES.md#react-preview-with-a-render-function) ·
+> [Handlebars item](RECIPES.md#handlebars-item) · [CSF stories](RECIPES.md#csf-stories) ·
+> [Composition with preview overrides](RECIPES.md#composition-with-preview-overrides)
 
 ### Registration
 
-Catalog directories are registered in one place. A path is either an item directory or a collection
-directory whose subdirectories are each treated as an item.
+`catalog.include` in the config registers the catalog directories. Each path is
+one of these:
 
-```ts
-// handoff.config.ts
-import { defineConfig } from 'handoff-app';
+- An item directory.
+- A collection directory. Each subdirectory is an item.
 
-export default defineConfig({
-  catalog: {
-    include: ['components', 'patterns'],
-  },
-  runtime: {
-    workspace: {
-      declarationFormat: 'ts',
-    },
-  },
-});
+```ts
+catalog: {
+  include: ['components', 'patterns'],
+},
 ```
 
-### Upgrade from version 1.x.x to version 2.x.x
+`npx handoff-app make:component <name>` creates a Handlebars item and adds its
+directory to `catalog.include` when necessary.
 
-See the [version 1.x.x to version 2.x.x migration guide](UPGRADE.md#version-1xx-to-version-2xx)
-for breaking changes, migration steps, and upgrade verification.
+### Pages
 
-Custom documentation pages are Markdown files under `pages/`. Their relative
-paths become their routes and registry IDs.
+Custom documentation pages are Markdown files under `pages/`. The relative
+path of a page is its route and its registry id.
+`npx handoff-app make:page <name> [parent]` creates a page.
+`npx handoff-app eject:pages` copies the default pages so that you can change
+them.
 
-## Figma foundations
+### Figma foundations
 
-Figma integration is optional. When Figma credentials are entered during
-`init`, they are written to `.env` by the wizard and the fetch command can be
-run directly.
+The Figma integration is optional. If you enter Figma credentials during
+`init`, the wizard writes them to `.env`, and `fetch` is ready to run.
 
-When that step is skipped or the Figma source must be changed, these values can
-be added or updated in `.env`:
+To add or change the Figma source, set these values in `.env`:
 
-```bash
+```dotenv
 HANDOFF_FIGMA_PROJECT_ID=figma-file-id
 HANDOFF_DEV_ACCESS_TOKEN=figma-personal-access-token
 ```
 
-The `file_content:read` and `library_content:read` scopes must be granted to the
-personal access token. The configured library is fetched with:
+The personal access token must have the `file_content:read` and
+`library_content:read` scopes. Fetch the library:
 
 ```bash
 npm run fetch
 ```
 
-After design changes, the Figma library should be republished and the command
-should be run again so the latest foundations are pulled.
+`fetch` writes tokens, CSS, Sass, and the available assets to `exported/`.
+Commit `exported/` so that local builds and CI builds use the same inputs. To
+make sure that the fetch worked, look for `exported/tokens.json`. An empty
+foundation page does not prove that the fetch worked.
+
+If a value is empty, `fetch` asks for it in the terminal. It can save the value
+to `.env`, or to `.env.<profile>` when a profile is selected. Without a
+terminal, for example in CI, `fetch` stops with an error that names the
+missing variable.
+
+After a design change, publish the Figma library again. Then run `fetch` again
+to get the latest foundations.
+
+These variable names are the defaults of `integrations.figma`. Set the block
+only to use different variable names, to commit the file ID, or to change the
+file for a profile. The access token accepts only an environment reference:
 
-Generated tokens, CSS, Sass, and available assets are written below
-`exported/<projectId>`. The `exported/` directory should be committed so the
-same inputs are used by local and CI builds. A successful fetch can be verified
-by checking for generated token data such as `exported/<projectId>/tokens.json`;
-an empty foundation route does not prove that the fetch succeeded.
+```ts
+integrations: {
+  figma: {
+    projectId: fromEnv('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
+    accessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
+  },
+},
+```
 
-## Workspace
+## Running the workspace
 
-Components, patterns, pages, styles, and configuration are authored as local
-workspace files. For day-to-day authoring, the documentation server and file
-watchers are started with:
+Start the documentation server and the Handoff file watchers:
 
 ```bash
 npm run start
 ```
 
-Changes are rebuilt and reflected in the documentation while the command is
-running. When Handoff file watchers are not required, the development server
-can be started with `npm run dev` instead.
+While the command runs, Handoff rebuilds changed files and updates the
+documentation. If you do not need the file watchers, run `npm run dev`
+instead.
 
-The following should be visible at http://localhost:3000:
+Open http://localhost:3000 and make sure that:
 
-- the app reports `Workspace` as the active runtime mode;
-- components appear in the component list;
-- component detail pages render every configured preview;
-- patterns render their referenced components; and
-- foundation pages contain the fetched values.
+- The app shows `Workspace` as the active runtime mode.
+- The component list shows your components.
+- Each component page renders all of its previews.
+- Each pattern renders the components that it references.
+- The foundation pages show the fetched values.
 
-## Build outputs
+## Building
 
-A static documentation site is built with:
+**Static site.** Build the documentation as a static site:
 
 ```bash
 npm run build
 ```
 
-Static output is written below `out/<projectId>` and can be served by any
-static file server or CDN.
+The output goes to `out/static`. A static file server or a CDN can serve it. A
+static site has no API routes. Thus it has no MCP endpoint and no AI
+assistant.
 
-A standalone registry application is built with:
+**Build cache.** Handoff does not build a component again if its files did not
+change since the last build. The cache in `.handoff/.cache/` records the files
+of each component and every file that its last build read, Sass partials
+included. The lockfile covers files under `node_modules`. The cache does not
+track assets that a stylesheet loads through `url()`. Build every component
+again:
 
 ```bash
-npm run build -- --target registry
+npm run build -- --force
 ```
 
-The generated application is automatically configured for registry mode by the
-command. The database-backed Next.js bundle is written to `out/registry`, and
-workspace source is not compiled or served. A Vercel Build Output bundle can be
-produced for either target by adding `--package vercel`.
+**Registry server.** Build a standalone registry application:
 
-## Registry setup
+```bash
+npm run build -- --target registry
+```
 
-### 1. Database migrations
+The command sets registry mode in the generated application. It writes the
+Next.js server bundle to `out/registry`. It does not compile or serve the
+workspace source. The [Registry](#registry) section explains how to deploy it.
 
-Migrations are run from the source workspace or CI checkout, where the project
-dependency and configuration are available:
+**Vercel.** Add `--package vercel` to either target to make a Vercel Build
+Output bundle in `.vercel/output`:
 
 ```bash
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/handoff?schema=public" \
-npm run db:migrate
+npm run build -- --target registry --package vercel
 ```
 
-Migrations are a controlled release step and are separate from the build,
-server startup, and browser installer.
+## Registry
 
-### 2. Registry runtime
+A registry is a deployed catalog with a PostgreSQL database. It serves only
+the records that a workspace publishes. It never reads the workspace
+directly.
 
-The generated registry bundle uses these environment variables:
+### Deploy a registry
 
-```dotenv
-PORT=4000
-HOSTNAME=0.0.0.0
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/handoff?schema=public"
-AUTH_SECRET="replace-with-at-least-32-random-characters"
-AUTH_URL="http://localhost:4000"
-```
+1. Apply the database migrations from the workspace or a CI checkout, where the
+   project config is available:
 
-`DATABASE_URL`, `AUTH_SECRET`, and `AUTH_URL` are required. The standalone
-server also reads `PORT` and `HOSTNAME`. The generated entrypoint is
-`out/registry/server.js`; how it is started and hosted depends on the deployment
-environment.
+   ```bash
+   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/handoff?schema=public" \
+   npm run db:migrate
+   ```
 
-### Vercel and Neon
+   Migrations are a controlled release step. The build, the server start, and
+   the installer never run them. Run `db:migrate` again each time you upgrade
+   `handoff-app`, before you deploy the new registry build.
 
-Vercel packaging and the Neon PostgreSQL driver are supported independently.
-Either integration can be used without the other.
+2. Select the [database driver](#database), the [asset storage](#asset-storage),
+   and the [email provider](#email). The build bakes these choices, so set them
+   before you build. The defaults work without more configuration.
 
-#### Vercel packaging
+3. Build the registry:
 
-A registry bundle that follows the Vercel Build Output API is produced with:
+   ```bash
+   npm run build -- --target registry
+   ```
 
-```bash
-npm run build -- --target registry --package vercel
-```
+4. Start `out/registry/server.js` with these environment variables:
+
+   ```dotenv
+   PORT=4000
+   HOSTNAME=0.0.0.0
+   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/handoff?schema=public"
+   AUTH_SECRET="replace-with-at-least-32-random-characters"
+   AUTH_URL="http://localhost:4000"
+   ```
 
-The generated deployment output is written to `.vercel/output`. The registry
-runtime variables listed above are supplied through the deployment environment.
+   `DATABASE_URL`, `AUTH_SECRET`, and `AUTH_URL` are required. The standalone
+   server also reads `PORT` and `HOSTNAME`. For Vercel, build with
+   `--package vercel` and set these variables in the deployment environment.
 
-#### Neon PostgreSQL
+5. Open http://localhost:4000/install and create the first administrator. The
+   installer examines the deployment, but it never runs migrations.
 
-Import `fromEnv` from `handoff-app`. Select the Neon connection driver in `handoff.config.ts`:
+CAUTION: Complete the installation immediately after the deployment. The first
+visitor can claim a registry that is not installed.
+
+> **Recipes:** [Local registry](RECIPES.md#local-registry) ·
+> [Vercel and Neon](RECIPES.md#vercel-and-neon)
+
+### Database
+
+PostgreSQL is the supported database. `driver` selects how the registry
+connects. The default is `pg`. Use `neon` for Neon PostgreSQL:
 
 ```ts
 runtime: {
   registry: {
-    databaseUrl: fromEnv('DATABASE_URL'),
     database: {
+      url: fromEnv('DATABASE_URL'),
       driver: 'neon',
     },
   },
 },
 ```
 
-A Neon PostgreSQL connection string is supplied through `DATABASE_URL`. The
-same explicit database migration step is required before deployment.
+Both drivers use the same schema and the same `db:migrate` step.
+
+### Asset storage
 
-#### Optional Vercel Blob storage
+By default, the registry stores asset blobs in PostgreSQL. Each blob can be at
+most 4 MB. `assetStorage.maxInlineBytes` changes this limit.
 
-Registry assets are stored in PostgreSQL by default. Vercel Blob can be selected
-when external asset storage is required:
+A [custom server module](#custom-server-modules) can store blobs in a
+different service:
 
 ```ts
 runtime: {
   registry: {
     assetStorage: {
-      adapter: 'vercel-blob',
+      provider: 'custom',
+      module: './server/storage/s3.mjs',
+      options: { bucket: 'handoff-assets', secretKey: fromEnv('S3_SECRET_KEY') },
     },
   },
 },
 ```
 
-The associated `BLOB_READ_WRITE_TOKEN` is supplied through the deployment
-environment.
+The module default-exports a `defineStorageProvider()` result with these
+methods:
+
+- `put` stores a blob and returns the `storageRef` that the registry records.
+- `get` returns a blob by its `storageRef`, as `{ kind: 'stream', stream }`,
+  `{ kind: 'bytes', bytes }`, or `{ kind: 'redirect', url }`.
+- `delete` removes a blob by its `storageRef`.
+- `createUpload` is optional. It enables direct uploads.
+
+**Upload paths.** `publish` uploads only the blobs that the registry does not
+have. The active provider decides which of two paths each blob takes. No
+setting changes the path.
+
+| Path | When | Hash check | Size limit |
+| --- | --- | --- | --- |
+| Through the registry | The `database` provider, or a custom provider without `createUpload` | The registry | The request limit of the host, about 4.5 MB on Vercel. The `database` provider also applies `maxInlineBytes`. |
+| Direct to storage | A custom provider with `createUpload` | Storage, through the signed URL | The limit of the storage |
 
-### 3. Installation
+For a direct upload, the registry gives the CLI a signed URL, and the CLI sends
+the blob to storage. The registry records the blob only after `get` finds the
+stored object.
 
-The installer is opened at http://localhost:4000/install, where the first
-administrator is created. The deployment is verified by the installer, but
-migrations are never run by it.
+- The machine that runs `publish` must be able to connect to the storage URL.
+- If a direct upload fails, `publish` stops. It does not try again through the
+  registry.
+- The signed URL must make storage reject bytes that do not match `hash`.
+- The registry does not delete an uploaded object that it never records.
 
-An uninstalled registry can be claimed by the first visitor. A new deployment
-should not be left unattended before installation is complete.
+**Download paths.** The result of `get` controls how a reader receives a blob.
+With `{ kind: 'redirect' }`, the registry sends the reader to storage. With
+`bytes` or `stream`, the registry sends the blob itself.
 
-### 4. Workspace authorization
+**Changing the provider.** The registry records which provider stores each blob.
+Blobs in PostgreSQL stay readable after you select a custom provider. A publish
+does not move blobs. If you change the custom provider or its storage, copy the
+stored objects first. The new provider must find each object by the
+`storageRef` that the previous provider returned. After a change back to
+`database`, the registry cannot read the blobs of the custom provider.
 
-A workspace reaches a registry with a registry URL and an access token. There
-are two ways to supply them. Both use the same kind of token, and both are
-listed and revoked under Account → Access tokens in the registry.
+> **Recipes:** [S3-compatible storage](RECIPES.md#s3-compatible-storage) ·
+> [Vercel Blob](RECIPES.md#vercel-blob)
 
-#### Device login
+### Email
 
-CLI authorization is started from the source workspace with:
+The registry sends invitation and password-reset emails when `email.from` is
+set. Without it, an administrator sees each invitation link one time and sends
+it manually, and password reset is not available.
+
+```ts
+runtime: {
+  registry: {
+    email: {
+      from: 'Handoff <no-reply@example.com>',
+      provider: 'smtp',
+      options: { host: fromEnv('SMTP_HOST') },
+    },
+  },
+},
+```
+
+`provider` selects the delivery service. It is required when you set `email`.
+
+- `smtp` sends through an SMTP server, for example Amazon SES, SendGrid, or
+  Microsoft 365.
+- `custom` names a [custom server module](#custom-server-modules) that
+  default-exports `defineEmailProvider()`. Use it for an HTTP API, for example
+  Resend or Postmark.
+
+`apiKey` and `password` must use `fromEnv()`. A profile can set a different
+sender or provider. When a profile changes the provider, it replaces
+`options`.
+
+> **Recipes:** [SMTP](RECIPES.md#smtp) · [Resend](RECIPES.md#resend) ·
+> [Custom email provider](RECIPES.md#custom-email-provider)
+
+### Custom server modules
+
+Asset storage, email, and AI connections can name a custom server module. Each
+module must obey these rules:
+
+- The path is relative to the working directory.
+- The file is `.js` or `.mjs`.
+- The default export is the object, or a factory that returns it.
+- The module imports its define helper from `handoff-app/providers`. The registry
+  build stops when a module imports `handoff-app`.
+- The project installs the packages that the module imports. The registry
+  build copies them into the bundle.
+
+The factory gets `options` with each `fromEnv()` value resolved at request
+time.
+
+## Connecting a workspace to a registry
+
+A connected workspace publishes content to a registry and checks content out
+from it. It needs a registry URL and an access token. You can supply them with
+a [device login](#device-login) or with [environment variables](#access-token).
+Both use the same kind of token. You can see and revoke tokens under
+Account → Access tokens in the registry.
+
+### Device login
+
+Start the authorization from the workspace:
 
 ```bash
 npm run login -- --url http://localhost:4000
 ```
 
-Registry sign-in, entry of the displayed device code, and CLI approval are
-completed in the browser. The issued credential is saved in
-`.handoff/cli-auth.json` for that exact registry URL.
+In the browser, sign in to the registry, enter the device code, and approve the
+CLI. The CLI saves the credential in `.handoff/cli-auth.json` for that exact
+registry URL.
 
-One credential is saved per profile, so a workspace can stay signed in to
-several registries at the same time:
+The CLI saves one credential for each profile. Thus a workspace can stay signed
+in to several registries:
 
 ```bash
 npm run login -- --profile staging --url https://staging.example.com
@@ -446,44 +857,55 @@ npm run publish -- all --profile staging
 
 A login profile name is free. It needs no `handoff.config.<name>.*` file, and
 `login` is the only command that accepts a new name. A profile without its own
-login falls back to the default login, so one `npm run login` is still enough
-for a workspace with one registry.
+login uses the default login. Thus one `npm run login` is enough for a
+workspace with one registry.
 
-`npm run logout` revokes and removes the login of the selected profile. The
-`--all` option removes every saved login.
+`npm run logout` revokes and removes the login of the selected profile.
+`--all` removes every saved login.
 
-#### Environment variables
+### Access token
 
-A token is created in the registry under Account → Access tokens. Read and
-write access is required to publish; read access is enough to check out. The
-token and the registry URL are then set in `.env`:
+Create a token in the registry under Account → Access tokens. To publish, the
+token needs read and write access. To check out, read access is enough. Set the
+token and the registry URL in `.env`:
 
 ```dotenv
 HANDOFF_REGISTRY_URL=http://localhost:4000
 HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_...
 ```
 
-No configuration file entry is needed, because these two variables are the
-defaults for `runtime.registryConnection`. A selected profile reads
-`.env.<profile>` on top of `.env`, so one workspace can address a different
-registry per profile. In CI, the job environment supplies the same two
-variables instead of a file.
+These two variables are the defaults of `runtime.registryConnection`, so no
+config entry is necessary. A selected profile reads `.env.<profile>` on top of
+`.env`. Thus each profile can address a different registry. In CI, the job
+environment supplies the same two variables.
 
-Environment values win over a saved device login, so a CI job stays
-deterministic on a machine where a developer is signed in. A token is only used
-for the registry URL it was issued for. If the environment names a different
-registry than the login of the selected profile, publish and checkout report
-which login was skipped and why.
+Environment values have priority over a saved device login. Thus a CI job gives
+the same result on a computer where a developer is signed in. A token works
+only for the registry URL that issued it. If the environment names a different
+registry than the login of the selected profile, `publish` and `checkout`
+report which login they skipped and why.
 
-### 5. Content publishing
+A config block is necessary only to keep the URL in the repository, or to read
+the values from variables with different names:
 
-Every kind in the workspace is published in dependency order with:
+```ts
+runtime: {
+  registryConnection: {
+    url: 'https://registry.example.com',
+    accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN'),
+  },
+},
+```
+
+### Publishing
+
+Publish every kind of content in dependency order:
 
 ```bash
 npm run publish -- all
 ```
 
-A single kind is published on its own:
+Publish one kind:
 
 ```bash
 npm run publish -- catalog
@@ -492,201 +914,186 @@ npm run publish -- tokens
 npm run publish -- assets
 ```
 
-`catalog` covers every catalog item. An item is stored as a component or as a
-pattern, and its declaration decides which. The command names items and never a
-kind.
+`catalog` covers every catalog item. The declaration of each item decides if
+the registry stores it as a component or as a pattern. Thus the command names
+items, not component or pattern kinds.
 
-Publishing tokens or assets runs the Figma data pipeline before upload, so the
-documented Figma credentials must be available.
+`tokens` and `assets` run the Figma pipeline before the upload. Thus the
+[Figma credentials](#figma-foundations) must be available.
 
-One or more IDs can be appended to narrow a publish to those entities:
+Add one or more ids to publish only those entities:
 
 ```bash
 npm run publish -- catalog item-id another-id
 ```
 
-`--dry-run` reports what would be uploaded and contacts no registry at all, so
-it needs neither a registry URL nor a token. It still runs the build, which
-refreshes generated output on disk; `--no-build` skips the build and publishes
-the existing output, and the two combine to leave the workspace untouched:
+`--dry-run` lists the content that a real publish uploads. It does not connect
+to a registry. Thus it needs no registry URL and no token. It still runs the build,
+which updates the generated output on disk. `--no-build` skips the build and
+publishes the existing output. Together, the two options do not change the
+workspace:
 
 ```bash
 npm run publish -- all --dry-run
 npm run publish -- catalog --no-build
 ```
 
-`checkout` takes the same `all`, multi-ID, and `--dry-run` forms. A dry-run
-checkout reads from the registry, lists the files it would create or overwrite,
-and writes nothing.
+After a publish, reload the registry to see the published items and
+foundations.
 
-After the registry is reloaded, the published catalog items and foundations are
-visible. Published database records are read by registry pages; the local
-workspace is never read directly.
+### Checkout
 
-For CI, supply `HANDOFF_REGISTRY_URL` and `HANDOFF_REGISTRY_ACCESS_TOKEN`
-through the job environment, as described under
-[Workspace authorization](#4-workspace-authorization). A connection block in
-`handoff.config.ts` is needed only to pin the URL in the repository, or to read
-the values from differently named variables (`fromEnv` is imported from
-`handoff-app`):
+`checkout` writes registry content into the workspace. It takes the same
+`all`, kind, id, and `--dry-run` forms as `publish`:
 
-```ts
-runtime: {
-  registryConnection: {
-    url: 'https://registry.example.com',
-    accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN'),
-  },
-},
+```bash
+npm run checkout -- all
+npm run checkout -- catalog item-id
+npm run checkout -- all --dry-run
 ```
 
+A dry-run checkout reads from the registry and lists the files that a real
+checkout creates or overwrites. It writes nothing. Checkout writes declarations in the
+format that `runtime.workspace.declarationFormat` sets.
+
+> **Recipes:** [One workspace, several registries](RECIPES.md#one-workspace-several-registries) ·
+> [Publish from GitHub Actions](RECIPES.md#publish-from-github-actions)
+
 ## MCP
 
-The documentation app serves a Model Context Protocol endpoint at `/api/mcp/`, so
-coding agents can look up the pages, components and tokens that already exist instead
-of inventing markup and values. It is stateless Streamable HTTP over `POST`;
-there is nothing to start and no extra port. Keep the trailing slash: the app
-sets `trailingSlash: true`, so `/api/mcp` answers with a 308 redirect.
+The documentation app serves a Model Context Protocol endpoint at `/api/mcp/`.
+Coding agents use it to find the pages, components, and tokens that exist. Thus
+they do not invent markup and values. The endpoint uses stateless Streamable
+HTTP over `POST`. There is nothing to start and no extra port.
 
 | Target | Endpoint | Credential |
 | --- | --- | --- |
-| Workspace (`dev` / `start`) | `http://localhost:3000/api/mcp/` | none, as with `/api/docs/*` |
-| Registry (standalone or Vercel) | `<registry url>/api/mcp/` | an access token, read-only is enough |
-| Static export | not available, a static site has no API routes | n/a |
+| Workspace (`dev` / `start`) | `http://localhost:3000/api/mcp/` | None, as with `/api/docs/*` |
+| Registry (standalone or Vercel) | `<registry url>/api/mcp/` | An access token. Read access is enough. |
+| Static site | Not available | Not applicable |
+
+Keep the trailing slash. The app sets `trailingSlash: true`, so `/api/mcp`
+answers with a 308 redirect. Registry tokens come from `handoff-app login` or
+from Account → Access tokens in the registry.
+
+The documentation app shows its endpoint and a ready-made client config for
+Claude Code, Cursor, and VS Code behind the plug icon in the header.
+
+MCP is on by default. To turn it off, set `runtime.mcp: false`. The build bakes
+this value. A build with MCP off answers 404 on the route, leaves the MCP SDK
+out of the bundle, and shows no connect control.
 
-Registry tokens come from `handoff-app login` or Account settings in the
-registry itself, and are the same credentials the rest of the registry API takes.
+> **Recipes:** [Connect a client by hand](RECIPES.md#connect-a-client-by-hand) ·
+> [Turn off MCP](RECIPES.md#turn-off-mcp)
 
-The endpoint is served unless a project turns it off:
+## AI assistant
+
+The documentation app can answer questions about the design system. The
+assistant reads through the same MCP tools. Thus each answer comes from the
+catalog and links to the pages and components that it read. Open the assistant
+from the search control in the header, or with `⌘K`.
+
+The `ai` block turns on the assistant, and the deployment selects the
+provider:
 
 ```ts
 runtime: {
-  mcp: false,
+  ai: {
+    connections: [
+      {
+        id: 'gateway',
+        label: 'Acme LiteLLM',
+        baseUrl: 'https://llm.acme.internal/v1',
+        apiKey: fromEnv('LITELLM_API_KEY'),
+        models: ['gpt-4o', 'claude-sonnet-4-5'],
+      },
+    ],
+    defaultModel: 'gateway/claude-sonnet-4-5',
+  },
 },
 ```
 
-Like `runtime.mode`, this is config-only and baked at build time, so changing it
-in a deployed registry means a rebuild. A disabled build answers 404 on the route,
-drops the MCP SDK from the packaged bundle, and shows no connect affordance at all
-rather than one that fails.
+`ai: { enabled: false }` turns off the assistant. The build bakes this flag.
+A build without the assistant serves no chat route and shows no control.
 
-The documentation app carries its own endpoint and a ready-made client config
-for Claude Code, Cursor and VS Code behind the plug icon in the header. By hand:
+Each connection uses one of these credentials:
 
-```json
-{
-  "mcpServers": {
-    "handoff": {
-      "type": "http",
-      "url": "https://registry.example.com/api/mcp/",
-      "headers": { "Authorization": "Bearer hnd_..." }
-    }
-  }
-}
-```
+- **Service key:** `apiKey` names a deployment key. The deployment pays for
+  every reader.
+- **No credential:** the endpoint needs no key, for example a local Ollama.
+- **Reader key:** `credential: 'user'` asks each reader for their own key.
 
-## Configuration
+**The declared connections are the full surface.** A reader can add a key only
+for a connection that the config declares. Thus the server never calls a URL
+that a reader selected. Without a `credential: 'user'` connection, readers have
+no AI setting.
 
-Configuration is read from `handoff.config.ts`, `.js`, `.cjs`, or `.json`, in
-that order. `defineConfig` provides typed authoring. Values merge onto the
-defaults: plain objects merge recursively, and arrays, scalars, `null`, and
-functions replace.
+Each connection uses the OpenAI-compatible `/chat/completions` API. This does
+not limit the models. Ollama serves an OpenAI-compatible API at `/v1`. LiteLLM,
+OpenRouter, vLLM, LM Studio, and Azure OpenAI each give access to Anthropic,
+Google, and xAI models. For a provider without this API, name a
+[custom server module](#custom-server-modules) that default-exports
+`defineAiProvider()`, instead of `baseUrl`.
 
-Useful environment variables:
+The gateway controls cost. LiteLLM and OpenRouter both apply budgets and rate
+limits for each key. The assistant limits only the number of steps for one
+question.
 
-| Variable | Purpose |
-| --- | --- |
-| `HANDOFF_PROFILE` | Config profile merged onto the base config |
-| `HANDOFF_FIGMA_PROJECT_ID` | Figma file ID used by `fetch` |
-| `HANDOFF_DEV_ACCESS_TOKEN` | Figma personal access token used by `fetch` |
-| `HANDOFF_REGISTRY_URL` | Connected workspace registry URL |
-| `HANDOFF_REGISTRY_ACCESS_TOKEN` | Registry access token used by a connected workspace |
-| `HANDOFF_SYNC_SECRET` | Optional deployment-wide registry credential |
-| `DATABASE_URL` | Registry PostgreSQL connection string |
-| `AUTH_SECRET` | Registry session-signing secret, at least 32 characters |
-| `AUTH_URL` | Canonical public registry URL |
-| `PORT` | Standalone registry server port |
-| `HOSTNAME` | Standalone registry bind hostname |
-| `BLOB_READ_WRITE_TOKEN` | Credential for the Vercel Blob asset adapter |
-| `HANDOFF_OUTPUT_DIR` | Override the fetched output directory |
-| `HANDOFF_SITES_DIR` | Override the build output directory |
-| `HANDOFF_APP_PORT` | Workspace documentation server port |
-| `HANDOFF_WEBSOCKET_PORT` | Workspace live-reload server port |
-
-Registry assets are stored in PostgreSQL by default with a 4 MB per-blob limit.
-Vercel Blob or a custom adapter can be selected through
-`runtime.registry.assetStorage`. The `pg` or `neon` connection driver can be
-selected through `runtime.registry.database.driver`; PostgreSQL is used by
-both.
-
-## Profiles
-
-A profile is a sidecar config file that merges onto the base config. It holds
-only what changes between environments, so a project keeps one shared config
-instead of a second complete copy of it.
-
-- The base config is `handoff.config.ts`, `.js`, `.cjs`, or `.json`. It is the
-  only config file loaded when no profile is selected.
-- A profile file is `handoff.config.<profile>.*`, with the same four
-  extensions.
-- Select a profile with `--profile <name>` or with `HANDOFF_PROFILE`.
-  `--profile` takes precedence over `HANDOFF_PROFILE`.
-- Profile names are not predefined. A name can contain lowercase letters,
-  numbers, and hyphens.
-- A selected profile must exist. If no `handoff.config.<name>.*` file is found,
-  the command stops with an error.
-- `login`, `logout`, `publish`, and `checkout` also accept a profile that has
-  only a saved registry login, because there the profile selects the registry.
-  Every other command still needs the config file.
-- Layers resolve as defaults, base config, profile, then programmatic config,
-  with the merge rules described under [Configuration](#configuration).
-- A selected profile also reads `.env.<profile>` on top of `.env`, when that
-  file exists. Both are read from the directory the command runs in, and a
-  variable already set in the environment beats both files.
+### Reader keys
 
-```bash
-npx handoff-app build --target registry --profile registry
-```
+A reader adds a key under Account → AI providers. The registry encrypts keys
+with `HANDOFF_AI_KEY_SECRET`. It does not hash them, because the server must
+send them to the provider. Set this variable to a random value of at least 32
+characters. A key is write-only through the API. After a save, a read reports
+only that a key exists.
+
+Reader keys work only in registry mode. A workspace has one user, whose config
+file and `.env` hold their keys. Thus a workspace supplies a key through
+`apiKey`.
 
-`build --target registry` always packages a registry-mode application, so a
-profile does not need to set `runtime.mode`. This makes a profile a good place
-for the registry build settings: the database driver, the database
-environment-variable name, the asset storage, and whether MCP is enabled. A
-hosting provider or a CI job selects the profile through `HANDOFF_PROFILE`.
+### Changing connections without a rebuild
 
-`defineConfig` types a profile as well as a base config. The generated
-`.gitignore` lists `handoff.config.local.*`, which makes `local` the usual name
-for a profile that stays on one machine.
+The connection list is deployment data, not build shape. Thus a registry can
+change it without a rebuild. `HANDOFF_AI_CONNECTIONS` holds a JSON array. The
+registry reads it at request time and merges it over the built-in list by `id`.
+Each entry names its key variable with `apiKeyEnv`, not the key value.
 
-Arrays replace, so a profile that declares `catalog.include` also decides what
-`make` and `checkout` register.
+A connection in this list can use a `module` only if a connection in the config
+names the same module. The build copies only those modules into the registry.
 
-`.env.<profile>` is read once at startup rather than watched.
-`HANDOFF_WORKING_PATH` cannot be set from it, because the working path is
-resolved before any profile is known.
+> **Recipes:** [Service key through a gateway](RECIPES.md#service-key-through-a-gateway) ·
+> [Local Ollama](RECIPES.md#local-ollama) · [Reader keys](RECIPES.md#reader-keys) ·
+> [Custom AI provider](RECIPES.md#custom-ai-provider) ·
+> [Change connections without a rebuild](RECIPES.md#change-connections-without-a-rebuild)
 
 ## CLI reference
 
 | Command | Description |
 | --- | --- |
-| `npx handoff-app init` | A workspace is scaffolded with the interactive wizard |
-| `npm run fetch` | Design tokens and assets are fetched from Figma |
-| `npm run start` | The workspace server and Handoff file watchers are started |
-| `npm run dev` | The workspace development server is started |
-| `npm run build -- [--target static\|registry]` | The static site or standalone registry bundle is built |
-| `npm run db:migrate` | Registry database migrations are applied |
-| `npm run validate` | Configured components are validated |
-| `npm run publish -- <kind\|all> [id...]` | Catalog items, pages, tokens, or assets are published |
-| `npm run checkout -- <kind\|all> [id...]` | Published content is pulled into a workspace |
-| `npm run login -- [--profile <name>] --url <url>` | The CLI is authorized through the registry device flow |
-| `npm run logout -- [--profile <name>] [--all]` | Saved CLI credentials are revoked and removed |
+| `npx handoff-app init` | Create a project with the interactive wizard |
+| `npm run fetch` | Fetch design tokens and assets from Figma |
+| `npm run start` | Start the workspace server and the Handoff file watchers |
+| `npm run dev` | Start the workspace server without the file watchers |
+| `npm run build -- [--target static\|registry] [--package vercel]` | Build the static site or the registry server |
+| `npm run db:migrate` | Apply the registry database migrations |
+| `npm run publish -- <kind\|all> [id...]` | Publish catalog items, pages, tokens, or assets |
+| `npm run checkout -- <kind\|all> [id...]` | Write published content into the workspace |
+| `npm run login -- [--profile <name>] --url <url>` | Authorize the CLI through the registry device flow |
+| `npm run logout -- [--profile <name>] [--all]` | Revoke and remove saved CLI credentials |
+| `npx handoff-app validate:components` | Validate the catalog items |
+| `npx handoff-app make:component <name>` | Create a Handlebars catalog item |
+| `npx handoff-app make:page <name> [parent]` | Create a documentation page |
+| `npx handoff-app scaffold` | Create catalog item stubs for fetched Figma components |
+| `npx handoff-app eject:config` | Write the default config to the working directory |
 
 Every command except `init` accepts `-c, --config`, `--profile`, `-d, --debug`,
-and `-f, --force`. `publish` and `checkout` additionally accept `--dry-run`, and
+and `-f, --force`. `publish` and `checkout` also accept `--dry-run`, and
 `publish` accepts `--no-build`.
 
-Arguments after `--` are forwarded to the local CLI. Exact options can be shown
-by adding `--help` after the separator. Advanced configuration and hooks are
-documented in [docs/api.md](docs/api.md).
+npm forwards the arguments after `--` to the CLI. To see the options of a
+command, add `--help` after `--`. [docs/cli.md](docs/cli.md) lists every
+command and option. [docs/api.md](docs/api.md) documents the JavaScript API and
+the build hooks.
 
 ## Maintainers
 
@@ -706,4 +1113,4 @@ Code of Conduct.
 
 ## License
 
-[MIT](License.md) ©Convertiv
+[MIT](LICENSE.md) ©Convertiv