handoff-app 2.0.0-1 → 2.0.0-10

package/README.md

@@ -7,434 +7,862 @@
   <img alt="" src="https://img.shields.io/npm/l/handoff-app?style=for-the-badge&labelColor=000000">
 </a>
 
-Handoff is a design system runtime. It turns the source of truth for your design
-system, the tokens, components, and patterns, into dev-ready artifacts and living
-documentation, and serves both through one consistent runtime whether you are
-authoring locally or running a shared, deployed catalog.
-
-## Table of contents
-
-* [What is Handoff?](#what-is-handoff)
-* [How it works](#how-it-works)
-* [Requirements](#requirements)
-* [Quick start](#quick-start)
-* [Project layout](#project-layout)
-* [Authoring components and patterns](#authoring-components-and-patterns)
-* [Fetching design tokens](#fetching-design-tokens)
-* [Running locally](#running-locally)
-* [Building artifacts](#building-artifacts)
-  * [Static site (default)](#static-site-default)
-  * [Registry app](#registry-app)
-* [Publishing and checkout](#publishing-and-checkout)
-* [Configuration](#configuration)
-  * [The runtime block](#the-runtime-block)
-  * [Environment variables](#environment-variables)
-  * [Hooks](#hooks)
-* [CLI reference](#cli-reference)
-* [Further reading](#further-reading)
-* [Maintainers](#maintainers)
-* [Contributing](#contributing)
-* [License](#license)
-
-## What is Handoff?
-
-Handoff is an open source design system runtime that closes the gap between
-design and development. By automating the delivery of your design system, it
-helps eliminate the bottlenecks between the two.
-
-It brings a few pieces together:
-
-* **Token extraction.** Pull standardized foundations from your design source and
-  store them as JSON. Figma is supported out of the box through the Figma REST
-  API.
-* **Transformation pipeline.** Produce SCSS, CSS, Style Dictionary, and preview
-  snippets from that data.
-* **Documentation runtime.** Render live, working previews of your components,
-  tokens, and styles, served through a stable docs read API.
-* **Delivery tooling.** Build and ship the deliverables, either as a static site
-  or as a deployed, database-backed catalog.
-
-Out of the box Handoff ships SCSS and CSS maps for [Bootstrap 5](https://getbootstrap.com/).
-If you use another framework or custom CSS, you can write your own map files to
-connect the generated tokens to your project.
-
-You install `handoff-app` as a project-local dependency and run its commands in
-your project's context, so every project pins its own toolchain version.
-
-## How it works
-
-Handoff has two runtime modes. Mode is resolved solely from `runtime.mode` in
-your config and defaults to `workspace`. It is never inferred from environment
-variables or token presence, so setting `DATABASE_URL` can never silently flip
-your app into another mode. The app chrome shows a `Workspace` or `Registry`
-badge so the active mode is always clear.
-
-* **Workspace mode (default).** Your local filesystem is the source of truth.
-  You author components, patterns, and tokens locally, preview them with a dev
-  server, and build a static documentation snapshot. Local authoring stays fast
-  and self-contained, with no database or registry required.
-* **Registry mode.** A deployed, dynamic Next.js app backed by PostgreSQL serves
-  a shared catalog. It only ever serves what a workspace published to it. The
-  registry never compiles or materializes workspace source.
-
-A **connected workspace** is workspace mode plus a registry connection. It still
-renders only your local files and still reads as `Workspace`, but it gains two
-commands: `publish` to push a locally built component or pattern up to a
-registry, and `checkout` to pull one back down into your workspace.
-
-Under the hood, documentation in every mode is consumed through one stable docs
-read API and one canonical artifact URL scheme (`/api/docs/artifacts/{path}`),
-so the same UI serves workspace, static, and registry backings without knowing
-which store is behind it.
+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.
+
+## Runtime modes
+
+- **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.
+
+Workspace mode is used by local projects for authoring. A separate
+registry-mode application is created automatically by a registry build.
 
 ## Requirements
 
-* Node 18.17+
-* npm 8+
-* A paid Figma account, if you fetch tokens from a Figma library
-* PostgreSQL (or a Postgres-compatible service such as Neon) for registry mode
+- 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
 
 ## Quick start
 
-Scaffold a new project with the interactive wizard:
+A project is created with the interactive wizard:
 
 ```bash
 npx handoff-app init
+cd my-handoff-project
 ```
 
-The wizard asks for a project name, whether to include sample components, your
-preferred language (TypeScript or JavaScript), and optionally your Figma project
-ID and access token. It then creates the project directory, writes the config
-and starter files, and installs dependencies.
+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:
 
 ```bash
-cd my-handoff-project
-npm run fetch    # pull design tokens from Figma (optional if no Figma creds yet)
-npm run start    # author locally with live preview at http://localhost:3000
+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 db:migrate  # registry database migrations
+npm run validate
+```
+
+## Project layout
+
+Every command runs against a working directory: the directory holding
+`handoff.config.ts`. Generated output is written there.
+
+```text
+<working directory>/
+├─ handoff.config.ts
+├─ .env
+├─ components/
+├─ patterns/
+├─ pages/
+├─ exported/       # fetched tokens and assets; commit this directory
+├─ public/api/     # generated docs API; gitignored
+├─ out/            # build output; gitignored
+├─ .vercel/        # `--package vercel` output; gitignored
+└─ .handoff/       # saved CLI login; gitignored
+```
+
+In a repository of its own, which is what `init` scaffolds, the working
+directory is the repository root.
+
+### Adding Handoff to an existing application
+
+Declarations sit beside the components they document, so the catalog points
+into the application source:
+
+```ts
+catalog: { include: ['src/components', 'src/blocks'] },
 ```
 
-The generated `package.json` wires up the common scripts:
+**`handoff-app` must be a dependency of the package holding those
+`*.handoff.ts` files.** They import `handoff-app/react`, which resolves from the
+directory of the declaration, not from the directory of the config. Under npm a
+missing dependency is usually hidden by hoisting. Under pnpm it is not: the
+affected items are skipped with `Could not resolve "handoff-app/react"` and the
+build still exits 0.
+
+Two `tsconfig.json` files do different jobs:
+
+- The config nearest the declarations type checks them. For files in `src/`
+  that is the one at the project root. An editor reads the nearest config only,
+  so a config in another directory that includes `src/` does not count, and
+  neither the editor nor the application build reports errors in a declaration.
+- The config at the working directory generates the property tables. Without
+  it, Handoff warns `TypeScript config not found` and every table is empty.
+
+Both files are needed when the working directory is not the project root.
+
+Three placements work, all keeping one dependency tree so the catalog renders
+the real components against the same React instance. A separate install with its
+own `node_modules` outside that tree is not supported.
+
+**Handoff in a subdirectory — recommended.** Nothing in the application changes.
+`handoff-app` is a dependency of the application package, and
+`HANDOFF_WORKING_PATH` keeps the generated directories in `handoff/`:
+
+```json
+{ "scripts": { "handoff:dev": "HANDOFF_WORKING_PATH=handoff handoff-app start" } }
+```
+
+An inline variable does not work in an npm script on Windows, where `cross-env`
+is used instead.
+
+**Handoff in the project root.** The working directory is the project root, so
+one `tsconfig.json` does both jobs. Handoff writes to `public/api`, so a bundler
+already serving static files from `public/` must be pointed elsewhere:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  publicDir: 'static',
+});
+```
+
+Without that change the generated documentation API is copied into the
+production build of the application. A Next.js application cannot use this
+placement: `sitesOutputDirectory` moves `out/` away from its export directory,
+but its `public` directory is a fixed convention with no setting to move it.
+
+**Handoff as a workspace package.** For a repository that is already a
+workspace. `handoff/` gets its own `package.json` and scripts, generated output
+lands in `handoff/`, and the root forwards to it:
 
 ```json
 {
-  "scripts": {
-    "start": "handoff-app start",
-    "dev": "handoff-app dev",
-    "build": "handoff-app build",
-    "fetch": "handoff-app fetch"
-  }
+  "workspaces": ["handoff"],
+  "scripts": { "handoff:dev": "npm run dev --workspace handoff" }
 }
 ```
 
-Any other command can be run with `npx handoff-app <command>` or added as a
-script of your own.
+The dependency rule is easiest to get wrong here: the declarations in `src/`
+belong to the application package, not to the workspace, so both packages
+declare `handoff-app`.
 
-## Project layout
+### pnpm
 
-A typical workspace project looks like this:
+`build` and `build --package vercel` work with the default pnpm layout.
+`build --target registry` cannot follow pnpm symlinks when it traces its runtime
+dependencies into a standalone bundle, so it needs a flat layout:
 
+```yaml
+# pnpm-workspace.yaml
+nodeLinker: hoisted
 ```
-my-handoff-project/
-├─ handoff.config.ts        # project + runtime configuration
-├─ .env                     # Figma credentials and other secrets
-├─ components/
-│  └─ button/
-│     ├─ Button.tsx         # component implementation
-│     └─ button.handoff.ts  # component declaration
-├─ patterns/                # multi-component compositions
-├─ sass/                    # optional global SCSS entry
-├─ js/                      # optional global JS entry
-├─ exported/                # generated tokens and artifacts (gitignored)
-└─ out/                     # build output (gitignored)
+
+## 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.
+
+### React
+
+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.
+
+```tsx
+// components/example/Component.tsx
+export type ComponentProps = {
+  label: string;
+  onSelect?: () => void;
+};
+
+export default function Component({ label, onSelect }: ComponentProps) {
+  return <div onClick={onSelect}>{label}</div>;
+}
+```
+
+```tsx
+// components/example/example.handoff.ts
+import { defineCatalogItem, type Preview } from 'handoff-app/react';
+import Component from './Component';
+
+const item = defineCatalogItem({
+  id: 'component-id',
+  name: 'Component name',
+  description: 'Usage guidance for the component.',
+  group: 'Group name',
+  implementation: Component,
+});
+
+export default item;
+
+type ComponentPreview = Preview<typeof item>;
+
+export const Default = {
+  args: { label: 'Example' },
+} satisfies ComponentPreview;
+```
+
+The export name is the preview name. Use `name` to set a different display title.
+
+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`.
+
+```tsx
+export const Interactive = {
+  render: function Interactive() {
+    const [label, setLabel] = useState('Example');
+    return <Component label={label} onSelect={() => setLabel('Selected')} />;
+  },
+} satisfies ComponentPreview;
+```
+
+### Handlebars
+
+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' },
+};
 ```
 
-## Authoring components and patterns
+A CSF preview is rendered on the server and is not hydrated. A direct React implementation is
+hydrated in the browser.
 
-A component is a directory with an implementation file and a declaration. The
-declaration is discovered as `*.handoff.{ts,js,cjs,json}` (the legacy
-`{dirname}.{js,cjs,json}` form keeps working too). List the directories you want
-built under `entries.components` in your config.
+### Compositions
 
-Declarations are written with the typed helpers exported from `handoff-app`:
+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`.
 
 ```ts
-import { defineReactComponent } from 'handoff-app';
-import Button from './Button';
-
-export default defineReactComponent(Button, {
-  id: 'button',
-  name: 'Button',
-  description: 'Interactive button used for primary and secondary actions.',
-  group: 'Atomic Elements',
-  entries: {
-    component: './Button.tsx',
+// patterns/example/example.handoff.ts
+import { defineCatalogItem } from 'handoff-app/pattern';
+
+export default defineCatalogItem({
+  id: 'pattern-id',
+  name: 'Pattern name',
+  description: 'Purpose and usage of the composition.',
+  group: 'Group name',
+  composition: [
+    { ref: 'component-id', preview: 'Default' },
+    { ref: 'badge', args: { children: 'Send' } },
+  ],
+});
+```
+
+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.
+
+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.
+
+
+### 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.
+
+```ts
+// handoff.config.ts
+import { defineConfig } from 'handoff-app';
+
+export default defineConfig({
+  catalog: {
+    include: ['components', 'patterns'],
   },
-  previews: {
-    primary: {
-      title: 'Primary',
-      args: { type: 'primary', children: 'Click me!' },
+  runtime: {
+    workspace: {
+      declarationFormat: 'ts',
     },
   },
 });
 ```
 
-The available helpers are:
+### Upgrade from version 1.x.x to version 2.x.x
 
-* `defineReactComponent` for React components
-* `defineHandlebarsComponent` for Handlebars templates
-* `defineCsfComponent` for Component Story Format stories
-* `defineComponent` for a generic, renderer-agnostic declaration
-* `definePattern` for compositions that reference several components by `id`
+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.
 
-Every component and pattern has a stable `id` (explicit `id` field, otherwise the
-directory name). The display `name`/`title` is independent of the `id`, so you
-can rename freely without breaking references. Identity is matched by `id`
-during publish and checkout.
+Custom documentation pages are Markdown files under `pages/`. Their relative
+paths become their routes and registry IDs.
 
-## Fetching design tokens
+## Figma foundations
 
-Handoff fetches tokens from Figma out of the box. Set your Figma credentials in
-`.env`:
+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.
+
+When that step is skipped or the Figma source must be changed, these values can
+be added or updated in `.env`:
 
 ```bash
-HANDOFF_FIGMA_PROJECT_ID=your-figma-file-id
-HANDOFF_DEV_ACCESS_TOKEN=your-figma-personal-access-token
+HANDOFF_FIGMA_PROJECT_ID=figma-file-id
+HANDOFF_DEV_ACCESS_TOKEN=figma-personal-access-token
 ```
 
-Then pull the latest foundations and component data:
+The `file_content:read` and `library_content:read` scopes must be granted to the
+personal access token. The configured library is fetched with:
 
 ```bash
 npm run fetch
 ```
 
-To get a personal access token in Figma, open the Figma menu, go to
-`Help and Account` then `Account Settings`, scroll to `Personal Access Token`,
-name a token, and copy it. Republish your Figma library after design changes and
-run `fetch` again to pick them up.
+After design changes, the Figma library should be republished and the command
+should be run again so the latest foundations are pulled.
+
+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.
 
-## Running locally
+## Workspace
 
-Both commands run a workspace-first local server with live preview.
+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:
 
 ```bash
-handoff-app dev     # development server with the live docs read API
-handoff-app start   # dev server plus file watchers that rebuild on change
+npm run start
 ```
 
-`start` is the day-to-day authoring loop: edit a component, save, and the
-preview updates. The site boots at http://localhost:3000 by default.
+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.
+
+The following should be visible at http://localhost:3000:
 
-## Building artifacts
+- 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.
 
-`handoff-app build` accepts a `--target` flag. The target, not `NODE_ENV`,
-decides what gets produced.
+## Build outputs
 
-### Static site (default)
+A static documentation site is built with:
 
 ```bash
-handoff-app build                  # static target (default)
-handoff-app build --target static  # explicit, identical output
+npm run build
 ```
 
-The static target builds your workspace components, patterns, and tokens,
-materializes the docs read model into route-shaped static files, and runs a
-static export to `out/<projectId>` (respecting `sitesOutputDirectory`). The
-output is plain static files: it renders list, detail, preview, and inspect
-pages and loads previews through canonical artifact URLs with no live server. It
-works on a managed host like Vercel and on a plain static file server with no
-host-specific rewrites.
+Static output is written below `out/<projectId>` and can be served by any
+static file server or CDN.
 
-The build fails clearly if a required artifact referenced by generated HTML
-cannot be materialized, and it fails if the runtime is registry-only (there is
-no local workspace to export).
-
-### Registry app
+A standalone registry application is built with:
 
 ```bash
-handoff-app build --target registry
+npm run build -- --target registry
 ```
 
-The registry target packages a deployable, dynamic Next.js app to
-`<sitesOutputDirectory>/registry` (default `out/registry`) as a Next.js
-standalone bundle. It never builds or bundles workspace source and has no
-workspace-source runtime dependency. It serves the docs read API and the
-registry API from the database and published artifacts.
+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 setup
+
+### 1. Database migrations
 
-The bundle is self-hostable on a Node server, VPS, or container. Start it with
-`node server.js` from the output directory and supply the database connection at
-deploy time:
+Migrations are run from the source workspace or CI checkout, where the project
+dependency and configuration are available:
 
 ```bash
-DATABASE_URL="postgres://…" node out/registry/server.js
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/handoff?schema=public" \
+npm run db:migrate
 ```
 
-A generated `README.md` next to the bundle documents the required env vars and
-Docker/Vercel specifics. Apply database migrations from the CLI as a controlled
-release step (e.g. in CI/CD) before deploying:
+Migrations are a controlled release step and are separate from the build,
+server startup, and browser installer.
+
+### 2. Registry runtime
+
+The generated registry bundle uses 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"
+```
+
+`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.
+
+### Vercel and Neon
+
+Vercel packaging and the Neon PostgreSQL driver are supported independently.
+Either integration can be used without the other.
+
+#### Vercel packaging
+
+A registry bundle that follows the Vercel Build Output API is produced with:
 
 ```bash
-handoff-app db:migrate
+npm run build -- --target registry --package vercel
 ```
 
-`db:migrate` reads your project config and DB env vars, applies the
-package-owned migration set, and runs independently of `build`. The database
-adapter (`pg` or `neon`) is chosen with `runtime.registry.database.adapter`, and
-both adapters ship with the package.
+The generated deployment output is written to `.vercel/output`. The registry
+runtime variables listed above are supplied through the deployment environment.
 
-## Publishing and checkout
+#### Neon PostgreSQL
 
-Connect a workspace to a registry by adding a `registryConnection` block to your
-config and setting the access token env var:
+Import `fromEnv` from `handoff-app`. Select the Neon connection driver in `handoff.config.ts`:
 
 ```ts
 runtime: {
-  mode: 'workspace',
-  registryConnection: {
-    url: 'https://registry.example.com',
-    accessTokenEnv: 'HANDOFF_REGISTRY_ACCESS_TOKEN',
+  registry: {
+    databaseUrl: fromEnv('DATABASE_URL'),
+    database: {
+      driver: 'neon',
+    },
+  },
+},
+```
+
+A Neon PostgreSQL connection string is supplied through `DATABASE_URL`. The
+same explicit database migration step is required before deployment.
+
+#### Optional Vercel Blob storage
+
+Registry assets are stored in PostgreSQL by default. Vercel Blob can be selected
+when external asset storage is required:
+
+```ts
+runtime: {
+  registry: {
+    assetStorage: {
+      adapter: 'vercel-blob',
+    },
   },
 },
 ```
 
+The associated `BLOB_READ_WRITE_TOKEN` is supplied through the deployment
+environment.
+
+### 3. Installation
+
+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.
+
+An uninstalled registry can be claimed by the first visitor. A new deployment
+should not be left unattended before installation is complete.
+
+### 4. Workspace authorization
+
+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.
+
+#### Device login
+
+CLI authorization is started from the source workspace with:
+
 ```bash
-# .env
-HANDOFF_REGISTRY_ACCESS_TOKEN=your-registry-token
+npm run login -- --url http://localhost:4000
 ```
 
-Then push and pull entities by `id`:
+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.
+
+One credential is saved per profile, so a workspace can stay signed in to
+several registries at the same time:
 
 ```bash
-handoff-app publish component button     # build locally, upload that entity's package
-handoff-app checkout pattern hero        # pull a registry entity into this workspace
+npm run login -- --profile staging --url https://staging.example.com
+npm run publish -- all --profile staging
 ```
 
-`publish` runs a fresh targeted build of the selected entity and uploads only
-that entity's package: normalized metadata, source files referenced by its
-`entries`, rendered docs artifacts (including required shared artifacts like
-`component/main.css` and `component/main.js`), and build metadata. It fails
-before upload if required artifacts are missing, stale, or incompatible, and it
-never touches unrelated entities' artifacts. Declaration files are never
-uploaded.
+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.
 
-`checkout` reads the registry record and source files, writes them in standard
-authoring form, and synthesizes a local declaration in your configured
-`runtime.workspace.declarationFormat` (defaulting to `js`). Declarations are a
-workspace-only concern, so they are always synthesized locally and never read
-from the registry. Overwriting existing local files requires `--force` or an
-interactive confirmation.
+`npm run logout` revokes and removes the login of the selected profile. The
+`--all` option removes every saved login.
 
-## Configuration
+#### Environment variables
 
-Project configuration lives in `handoff.config.{ts,js,cjs,json}` (resolved in
-that precedence order). TypeScript and ESM configs use `defineConfig` for typed
-authoring; plain CommonJS configs that never call `defineConfig` keep working
-unchanged.
+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`:
 
-```ts
-import { defineConfig } from 'handoff-app';
+```dotenv
+HANDOFF_REGISTRY_URL=http://localhost:4000
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_...
+```
 
-export default defineConfig({
-  app: {
-    title: 'Acme Design System',
-    client: 'Acme Corp',
-    basePath: '',
-  },
-  entries: {
-    scss: './sass/main.scss',
-    js: './js/main.js',
-    components: ['components/button', 'components/badge'],
-    patterns: ['patterns'],
-  },
-});
+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.
+
+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.
+
+### 5. Content publishing
+
+Every kind in the workspace is published in dependency order with:
+
+```bash
+npm run publish -- all
 ```
 
-### The runtime block
+A single kind is published on its own:
 
-The `runtime` block selects the mode and carries mode-specific settings. It is
-optional and deep-merged into the defaults, so a partial block never wipes them.
+```bash
+npm run publish -- catalog
+npm run publish -- pages
+npm run publish -- tokens
+npm run publish -- assets
+```
 
-```ts
-runtime: {
-  // Sole determinant of runtime mode. Defaults to 'workspace'.
-  mode: 'workspace', // 'workspace' | 'registry'
+`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.
 
-  workspace: {
-    // Format for newly generated / checkout-synthesized declarations.
-    declarationFormat: 'ts', // 'ts' | 'js' | 'cjs' | 'json'
-  },
+Publishing tokens or assets runs the Figma data pipeline before upload, so the
+documented Figma credentials must be available.
+
+One or more IDs can be appended to narrow a publish to 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:
+
+```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 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.
 
-  // Connect a workspace to a remote registry (publish/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`):
+
+```ts
+runtime: {
   registryConnection: {
     url: 'https://registry.example.com',
-    accessTokenEnv: 'HANDOFF_REGISTRY_ACCESS_TOKEN',
+    accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN'),
   },
+},
+```
 
-  // Registry deployment settings (build --target registry, db:migrate).
-  registry: {
-    databaseUrlEnv: 'DATABASE_URL',
-    apiTokenEnv: 'HANDOFF_REGISTRY_API_TOKEN',
-    database: { adapter: 'pg' }, // 'pg' | 'neon'
+## 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.
+
+| 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 |
+
+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.
+
+The endpoint is served unless a project turns it off:
+
+```ts
+runtime: {
+  mcp: false,
+},
+```
+
+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.
+
+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:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "type": "http",
+      "url": "https://registry.example.com/api/mcp/",
+      "headers": { "Authorization": "Bearer hnd_..." }
+    }
+  }
+}
+```
+
+## AI assistant
+
+The documentation app can answer questions about the design system. The
+assistant reads through the same MCP tools, so every answer comes from the
+catalog and links to the pages and components it read. Open it from the search
+control in the header, or with `⌘K`.
+
+The deployment chooses the provider:
+
+```ts
+runtime: {
+  ai: {
+    connections: [
+      // Service key: the deployment pays for every reader.
+      {
+        id: 'gateway',
+        label: 'Acme LiteLLM',
+        baseUrl: 'https://llm.acme.internal/v1',
+        apiKey: fromEnv('LITELLM_API_KEY'),
+        models: ['gpt-4o', 'claude-sonnet-4-5', 'grok-4'],
+      },
+      // No credential: the endpoint needs none.
+      { id: 'local', label: 'Ollama', baseUrl: 'http://127.0.0.1:11434/v1', models: ['llama3.1'] },
+      // User key: the config fixes the endpoint and models. Each reader adds their own key.
+      {
+        id: 'openai',
+        label: 'OpenAI',
+        baseUrl: 'https://api.openai.com/v1',
+        credential: 'user',
+        models: ['gpt-4o', 'o3'],
+      },
+    ],
+    defaultModel: 'gateway/claude-sonnet-4-5',
   },
 },
 ```
 
-Secrets are always referenced by environment-variable name, never written as
-values, and are redacted from API responses.
+The `ai` block turns the assistant on, and `ai: { enabled: false }` turns it
+back off. Like `runtime.mcp`, that flag is baked at build time, so a build
+without it serves no chat route and shows no control.
+
+**The declared connections are the whole surface.** A reader can only add a key
+for a connection the config already declares, so the server never calls a URL a
+reader chose. Without a `credential: 'user'` connection, there is no
+reader-facing setting.
+
+Every connection speaks the OpenAI-compatible `/chat/completions` API. This does
+not limit which models a reader can use. Ollama serves an OpenAI-compatible API
+at `/v1`, and LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI each front
+Anthropic, Google and xAI models. A provider that fits nothing else names a
+server-only module that default-exports `defineAiProvider()`, the way
+`runtime.registry.assetStorage.module` does.
+
+### Reader keys
+
+A connection marked `credential: 'user'` asks each reader for their own key,
+under Account → AI providers. Keys are encrypted with `HANDOFF_AI_KEY_SECRET`,
+not hashed, because the server must send them to the provider. Set that variable
+to a random value of at least 32 characters. A key is write-only across the API:
+after a save, a read reports only that a key is in place.
+
+This applies to registry mode only. A workspace has one user, whose config file
+and `.env` are their user layer, so a workspace supplies a key through `apiKey`.
+
+### Changing connections without a rebuild
 
-### Environment variables
+The connection list is deployment data, not build shape, so a registry can
+change it without a rebuild. `HANDOFF_AI_CONNECTIONS` holds a JSON array, read
+at request time and merged over the baked list by `id`. It names each key
+instead of holding its value:
+
+```json
+[{ "id": "gateway", "label": "Acme LiteLLM", "baseUrl": "https://llm.acme.internal/v1",
+   "apiKeyEnv": "LITELLM_API_KEY", "models": ["gpt-4o"] }]
+```
+
+Spend control belongs to the gateway. LiteLLM and OpenRouter both enforce
+budgets and rate limits per key. The assistant caps only how many steps one
+question can take.
+
+## Configuration
+
+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.
+
+Useful environment variables:
 
 | 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` | Default env var for a connected workspace's registry URL |
-| `HANDOFF_REGISTRY_ACCESS_TOKEN` | Connected-workspace access token for publish/checkout |
-| `DATABASE_URL` | Registry database connection string (name is configurable) |
-| `HANDOFF_REGISTRY_API_TOKEN` | Bearer token guarding registry management mutations |
+| `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_AI_KEY_SECRET` | Encrypts reader-supplied AI provider keys, at least 32 characters |
+| `HANDOFF_AI_CONNECTIONS` | JSON array of AI connections, merged over the baked list by `id` |
+| `HANDOFF_OUTPUT_DIR` | Override the fetched output directory |
+| `HANDOFF_SITES_DIR` | Override the build output directory |
+| `HANDOFF_WORKING_PATH` | Directory holding `handoff.config.ts`; defaults to the current 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.
+
+```bash
+npx handoff-app build --target registry --profile registry
+```
+
+`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`.
 
-### Hooks
+`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.
 
-Pipeline customization is done in your config under `hooks` (camelCase names such
-as `validateComponent`, `jsBuildConfig`, `registerHandlebarsHelpers`). For
-example, `registerHandlebarsHelpers` runs after Handoff registers the built-in
-`field` and `eq` helpers, so you can register your own helpers for `.hbs`
-preview templates.
+Arrays replace, so a profile that declares `catalog.include` also decides what
+`make` and `checkout` register.
 
-See [docs/api.md](docs/api.md#hooks) for hook arguments and examples.
+`.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.
 
 ## CLI reference
 
 | Command | Description |
 | --- | --- |
-| `init` | Scaffold a new workspace project with the interactive wizard |
-| `fetch` | Fetch design tokens from Figma |
-| `dev` | Start the local dev server with the live docs read API |
-| `start` | Start the dev server with file watchers for live authoring |
-| `build [--target static\|registry]` | Build the static site (default) or package the registry app |
-| `build:components [component]` | Build components without building the full app |
-| `publish <component\|pattern> <id>` | Build and publish an entity to the connected registry |
-| `checkout <component\|pattern> <id>` | Pull an entity from the connected registry |
-| `db:migrate` | Run registry database migrations (Drizzle / PostgreSQL) |
-| `make:component <name>` | Scaffold a new component |
-| `make:page <name> [parent]` | Scaffold a documentation page |
-| `make:template <component> [state]` | Scaffold a preview template |
-| `eject:config` | Eject the default config to the project |
-| `eject:pages` | Eject the default documentation pages |
-| `eject:theme` | Eject the default theme |
-| `validate:components` | Run component validation |
-
-Global flags: `-c, --config <file>`, `-d, --debug`, `-f, --force`,
-`-h, --help`, `-v, --version`. See [docs/cli.md](docs/cli.md) for the full
-reference.
-
-## Further reading
-
-* [Configure your project](https://www.handoff.com/docs/customization)
-* [Customize the content](https://www.handoff.com/docs/customization/content)
-* [Integrate tokens with your project](https://www.handoff.com/docs/tokens/integration)
-* [Build to static assets](https://www.handoff.com/docs/tokens/publishing)
-* [GitHub Actions CI/CD](https://www.handoff.com/docs/infrastructure/github/)
-* [Bitbucket Pipelines CI/CD](https://www.handoff.com/docs/infrastructure/bitbucket/)
+| `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 |
+
+Every command except `init` accepts `-c, --config`, `--profile`, `-d, --debug`,
+and `-f, --force`. `publish` and `checkout` additionally 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).
 
 ## Maintainers
 
@@ -446,8 +874,8 @@ reference.
 
 ## Contributing
 
-Feel free to dive in. [Open an issue](https://github.com/Convertiv/handoff-app/issues/new)
-or submit a PR.
+[Issues](https://github.com/Convertiv/handoff-app/issues/new) and pull requests
+are welcome.
 
 Handoff follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/)
 Code of Conduct.