handoff-app 2.0.0-10 → 2.0.0-12

package/README.md

@@ -24,8 +24,8 @@ registry-mode application is created automatically by a registry build.
 
 ## Requirements
 
-- Node.js 18.18 or newer; Node.js 20 LTS or newer is recommended
-- npm 8 or newer
+- Node.js 22 or newer; Node.js 24 LTS is recommended
+- npm 10 or newer
 - A paid Figma account when fetching a Figma library
 - PostgreSQL when running a registry
 
@@ -53,6 +53,11 @@ npm run db:migrate  # registry database migrations
 npm run validate
 ```
 
+## Upgrade from version 1.x.x to version 2.x.x
+
+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.
+
 ## Project layout
 
 Every command runs against a working directory: the directory holding
@@ -69,13 +74,13 @@ Every command runs against a working directory: the directory holding
 ├─ public/api/     # generated docs API; gitignored
 ├─ out/            # build output; gitignored
 ├─ .vercel/        # `--package vercel` output; gitignored
-└─ .handoff/       # saved CLI login; gitignored
+└─ .handoff/       # local Handoff state; 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
+## Adding Handoff to an existing application
 
 Declarations sit beside the components they document, so the catalog points
 into the application source:
@@ -313,8 +318,6 @@ 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
@@ -336,10 +339,7 @@ export default defineConfig({
 });
 ```
 
-### Upgrade from version 1.x.x to version 2.x.x
-
-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.
@@ -358,6 +358,23 @@ HANDOFF_FIGMA_PROJECT_ID=figma-file-id
 HANDOFF_DEV_ACCESS_TOKEN=figma-personal-access-token
 ```
 
+These are the defaults of `integrations.figma` in `handoff.config`. Set the block
+only to use other variable names, to commit the file ID, or to change the file
+for a profile. The access token accepts only an environment reference:
+
+```ts
+integrations: {
+  figma: {
+    projectId: fromEnv("HANDOFF_FIGMA_PROJECT_ID", { default: null }),
+    accessToken: fromEnv("HANDOFF_DEV_ACCESS_TOKEN", { default: null }),
+  },
+},
+```
+
+If a value is empty, `fetch` asks for it in a terminal and can save it to `.env`,
+or to `.env.<profile>` when a profile is selected. Without a terminal, such as
+in CI, `fetch` stops with an error that names the missing variable.
+
 The `file_content:read` and `library_content:read` scopes must be granted to the
 personal access token. The configured library is fetched with:
 
@@ -369,9 +386,9 @@ 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
+`exported/`. 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`;
+by checking for generated token data such as `exported/tokens.json`;
 an empty foundation route does not prove that the fetch succeeded.
 
 ## Workspace
@@ -404,9 +421,20 @@ A static documentation site is built with:
 npm run build
 ```
 
-Static output is written below `out/<projectId>` and can be served by any
+Static output is written below `out/static` and can be served by any
 static file server or CDN.
 
+Components whose files have not changed since the last build are not built
+again. The build cache in `.handoff/.cache/` records the files of each
+component and every file that its last build read, Sass partials included.
+Files under `node_modules` are covered by the lockfile instead. Assets that a
+stylesheet loads through `url()` are not tracked. Every component is built
+again with:
+
+```bash
+npm run build -- --force
+```
+
 A standalone registry application is built with:
 
 ```bash
@@ -418,6 +446,83 @@ 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`.
 
+## 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` | 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 |
+| `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_CREATE_ASSETS_ZIP_FILES` | Set to `false` to skip the icon and logo zip files in `fetch` |
+| `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 |
+
+## 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`.
+
+`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.
+
+Arrays replace, so a profile that declares `catalog.include` also decides what
+`make` and `checkout` register.
+
+`.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.
+
 ## Registry setup
 
 ### 1. Database migrations
@@ -450,57 +555,10 @@ 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
-npm run build -- --target registry --package vercel
-```
-
-The generated deployment output is written to `.vercel/output`. The registry
-runtime variables listed above are supplied through the deployment environment.
-
-#### Neon PostgreSQL
-
-Import `fromEnv` from `handoff-app`. Select the Neon connection driver in `handoff.config.ts`:
-
-```ts
-runtime: {
-  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.
+The defaults work without more configuration: asset blobs are stored in
+PostgreSQL, and email is not sent. Other providers are baked into the build, so
+they must be selected under [Registry providers](#registry-providers) before
+the registry is built.
 
 ### 3. Installation
 
@@ -632,6 +690,298 @@ runtime: {
 },
 ```
 
+## Registry providers
+
+### 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
+npm run build -- --target registry --package vercel
+```
+
+The generated deployment output is written to `.vercel/output`. The registry
+runtime variables listed above are supplied through the deployment environment.
+
+#### Neon PostgreSQL
+
+Import `fromEnv` from `handoff-app`. Select the Neon connection driver in `handoff.config.ts`:
+
+```ts
+runtime: {
+  registry: {
+    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.
+
+### Asset storage
+
+The registry stores asset blobs in PostgreSQL by default, with a limit of 4 MB
+for each blob. `maxInlineBytes` changes this limit.
+
+#### Custom adapter
+
+A [custom server module](#custom-server-modules) can store blobs in a
+different service. The module default-exports a `defineAssetStorage()` adapter
+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](#direct-uploads).
+
+Literals in `options` are baked into the build. The deployed registry reads
+each `fromEnv()` value at request time and gives the resolved `options` to the
+module. Thus secrets must use `fromEnv()`.
+
+The S3 and Vercel Blob examples that follow are complete adapters with direct
+uploads.
+
+##### Direct uploads
+
+By default, `publish` sends each blob to the registry, and the registry sends
+it to storage. A serverless host limits the size of one request. Vercel permits
+about 4.5 MB, so a larger blob fails.
+
+With `createUpload`, the registry gives the CLI a signed URL, and the CLI sends
+the blob directly to storage. The signed URL must make storage reject bytes
+that do not match `hash`. The registry records the blob only after `get` finds
+the stored object. The registry does not delete an uploaded object that it
+never records.
+
+The `database` provider always uploads through the registry, with its
+`maxInlineBytes` limit.
+
+##### S3-compatible storage
+
+This adapter works with Amazon S3, Cloudflare R2, MinIO, SeaweedFS, and other
+services with an S3 API. It uses `@aws-sdk/client-s3` and
+`@aws-sdk/s3-request-presigner`.
+
+```ts
+runtime: {
+  registry: {
+    assetStorage: {
+      adapter: 'custom',
+      module: './server/storage/s3.mjs',
+      options: {
+        endpoint: 'http://127.0.0.1:8333',
+        bucket: 'handoff-assets',
+        accessKey: fromEnv('S3_ACCESS_KEY'),
+        secretKey: fromEnv('S3_SECRET_KEY'),
+      },
+    },
+  },
+},
+```
+
+```js
+// server/storage/s3.mjs
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { defineAssetStorage } from 'handoff-app/define';
+
+export default defineAssetStorage(({ options }) => {
+  const client = new S3Client({
+    endpoint: options.endpoint,
+    region: 'us-east-1',
+    forcePathStyle: true,
+    credentials: { accessKeyId: options.accessKey, secretAccessKey: options.secretKey },
+  });
+  const Bucket = options.bucket;
+  return {
+    async put({ hash, bytes, contentType }) {
+      await client.send(new PutObjectCommand({ Bucket, Key: hash, Body: bytes, ContentType: contentType }));
+      return { storageRef: hash };
+    },
+    async get(storageRef) {
+      const result = await client.send(new GetObjectCommand({ Bucket, Key: storageRef }));
+      return { kind: 'stream', stream: result.Body, contentType: result.ContentType };
+    },
+    async delete(storageRef) {
+      await client.send(new DeleteObjectCommand({ Bucket, Key: storageRef }));
+    },
+    async createUpload({ hash, contentType }) {
+      const checksum = Buffer.from(hash, 'hex').toString('base64');
+      const command = new PutObjectCommand({ Bucket, Key: hash, ContentType: contentType, ChecksumSHA256: checksum });
+      const url = await getSignedUrl(client, command, {
+        expiresIn: 900,
+        unhoistableHeaders: new Set(['x-amz-checksum-sha256']),
+      });
+      return { url, headers: { 'Content-Type': contentType, 'x-amz-checksum-sha256': checksum }, storageRef: hash };
+    },
+  };
+});
+```
+
+`createUpload` signs a SHA-256 checksum header. Thus storage rejects bytes
+that do not match `hash`.
+
+##### Vercel Blob
+
+This adapter stores blobs in a private Vercel Blob store. It uses
+`@vercel/blob` 2.x. When the store is connected to the Vercel project, the SDK
+reads the store credentials from the deployment environment. Thus the adapter
+needs no `options`.
+
+```ts
+runtime: {
+  registry: {
+    assetStorage: {
+      adapter: 'custom',
+      module: './server/storage/vercel-blob.mjs',
+    },
+  },
+},
+```
+
+```js
+// server/storage/vercel-blob.mjs
+import { Readable } from 'node:stream';
+import { del, get, issueSignedToken, parseStoreIdFromDelegationToken, presignUrl, put } from '@vercel/blob';
+import { defineAssetStorage } from 'handoff-app/define';
+
+const access = 'private';
+const pathnameFor = (hash) => `assets/${hash}`;
+
+export default defineAssetStorage({
+  async put({ hash, bytes, contentType }) {
+    const blob = await put(pathnameFor(hash), bytes, { access, contentType, addRandomSuffix: false, allowOverwrite: true });
+    return { storageRef: blob.pathname };
+  },
+  async get(storageRef) {
+    const result = await get(storageRef, { access });
+    if (!result?.stream) {
+      throw new Error(`Blob "${storageRef}" does not exist.`);
+    }
+    return { kind: 'stream', stream: Readable.fromWeb(result.stream), contentType: result.blob.contentType };
+  },
+  async delete(storageRef) {
+    await del(storageRef);
+  },
+  async createUpload({ hash, size, contentType }) {
+    const pathname = pathnameFor(hash);
+    const token = await issueSignedToken({
+      pathname,
+      operations: ['put'],
+      validUntil: Date.now() + 15 * 60 * 1000,
+      allowedContentTypes: [contentType],
+      maximumSizeInBytes: size,
+    });
+    const { presignedUrl } = await presignUrl(token, { operation: 'put', pathname, access, allowOverwrite: true });
+    return {
+      url: presignedUrl,
+      headers: {
+        'x-api-version': '12',
+        'x-vercel-blob-store-id': parseStoreIdFromDelegationToken(token.delegationToken),
+        'x-vercel-blob-access': access,
+        'x-content-type': contentType,
+      },
+      storageRef: pathname,
+    };
+  },
+});
+```
+
+This adapter is different from the S3 example in these ways:
+
+- `get` converts the stream. The SDK returns a web stream, but the registry
+  needs a Node stream.
+- A private blob has no public URL. Thus the registry sends each blob to the
+  reader itself.
+- **Vercel Blob cannot reject bytes that do not match `hash`.** The signed URL
+  limits only the path, the size, and the content type. Thus the registry does
+  not verify a blob that the CLI uploads directly.
+- Without `createUpload`, each blob goes through the registry, which verifies
+  its hash. The Vercel limit of about 4.5 MB then applies to each blob.
+- The CLI sends a plain `PUT` request. Thus `createUpload` returns the headers
+  that the SDK sends for a presigned upload. These headers are not a documented
+  API, so a new version of `@vercel/blob` can change them.
+
+#### Changing the provider
+
+The registry records on each blob whether PostgreSQL or the custom adapter
+stores it. Blobs in PostgreSQL stay readable after you select a custom adapter.
+A publish does not move blobs. Thus, if you change the custom adapter or its
+storage, copy the stored objects first. The new adapter must find each object
+by the `storageRef` that the previous adapter returned. After a change back to
+`database`, the registry cannot read the blobs of the custom adapter.
+
+### Email delivery
+
+The registry sends invitation and password-reset emails when `email.from` is
+set. Without it, an administrator sees each invitation link once and delivers
+it manually, and password reset is not available.
+
+Resend is the default provider. It reads its key from `RESEND_API_KEY`, unless
+`options.apiKey` names a different variable:
+
+```ts
+runtime: {
+  registry: {
+    email: { from: 'Handoff <no-reply@example.com>' },
+  },
+},
+```
+
+For an SMTP server, for example Amazon SES, SendGrid, or Microsoft 365:
+
+```ts
+email: {
+  from: 'Handoff <no-reply@example.com>',
+  provider: 'smtp',
+  options: {
+    host: fromEnv('SMTP_HOST'),
+    port: 465, // default, uses TLS. 587 uses STARTTLS.
+    user: fromEnv('SMTP_USER'),
+    password: fromEnv('SMTP_PASSWORD'),
+  },
+},
+```
+
+For a different service, set `provider: 'custom'` and set `module` to a
+[custom server module](#custom-server-modules). The factory gets `options`
+with `fromEnv()` values resolved:
+
+```ts
+import { defineEmailProvider } from 'handoff-app/define';
+
+export default defineEmailProvider(({ options }) => ({
+  async send({ from, to, subject, html, text }) {
+    // Deliver the message. Throw an error if it is not accepted.
+  },
+}));
+```
+
+Literals in `options` are baked into the build. `fromEnv()` values are read at
+request time, so they can change without a rebuild. `apiKey` and `password`
+must use `fromEnv()`. A profile can set a different sender or provider. When a
+profile changes the provider, it replaces `options`.
+
+### Custom server modules
+
+Asset storage, email, and AI connections can name a custom server module. Each
+module obeys 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/define`. The registry build stops when a module imports `handoff-app`.
+- The packages that the module imports are installed in the project. The registry build copies them into the bundle.
+
 ## MCP
 
 The documentation app serves a Model Context Protocol endpoint at `/api/mcp/`, so
@@ -727,8 +1077,10 @@ 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.
+[custom server module](#custom-server-modules) that default-exports
+`defineAiProvider()`, in place of `baseUrl`. The factory gets `options` with
+`fromEnv()` values resolved. Literals in `options` are baked into the build, so
+secrets must use `fromEnv()`.
 
 ### Reader keys
 
@@ -753,93 +1105,13 @@ instead of holding its value:
    "apiKeyEnv": "LITELLM_API_KEY", "models": ["gpt-4o"] }]
 ```
 
+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.
+
 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` | 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`.
-
-`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.
-
-Arrays replace, so a profile that declares `catalog.include` also decides what
-`make` and `checkout` register.
-
-`.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 |