@headband/cli 0.3.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZVN DEV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # @headband/cli
 
 Command-line tools for [Headband](https://headband.dev): project setup, login,
-API keys, indexes, documents, search, tasks, dedicated engines, schema
+branches, API keys, indexes, documents, search, tasks, dedicated engines, schema
 migrations and Sync. Every command works for a person at a terminal and for a
 script or coding agent with no terminal at all.
 
@@ -26,6 +26,9 @@ npx @headband/cli login
 --token <key>      API key for this call. Wins over HEADBAND_API_KEY and stored logins.
 --profile <name>   Stored login to use (else HEADBAND_PROFILE, else the current profile)
 --url <url>        Headband URL (else HEADBAND_URL, else the profile's, else https://headband.dev)
+--branch <name>    Work on this branch for one call, in the project from --project <id>,
+                   else the checkout's (see Branches). A branch id (br_...) is sent as it is.
+                   Without --branch or a checkout, calls reach the primary branches.
 --json             Print one JSON document on stdout; errors print one JSON object on stderr
 --yes, -y          Answer yes to confirmations (required when stdin is not a terminal)
 --help, -h         Show help for the CLI or a command
@@ -102,9 +105,10 @@ headband indexes list --json
 ```
 
 Which key to use: an admin key from `headband keys create <name> --type admin`
-covers indexes, documents, search, engines and Sync. Managing keys, projects
-and schema state needs a key minted by `headband login`, because only those
-carry `keys.manage`, `projects.manage` and `schema.manage`.
+covers indexes, documents, search, engines and Sync. Managing keys, projects,
+branches and schema state needs a key minted by `headband login`, because only
+those carry `keys.manage`, `projects.manage`, `branches.manage` and
+`schema.manage`.
 
 ## Scripts and agents
 
@@ -128,6 +132,11 @@ The CLI never waits for input it cannot get.
   `network_error`. `status` is the HTTP status, or `null` when no request was
   made.
 
+- **Rate limits.** A `429` whose `Retry-After` is 10 seconds or less is
+  retried up to twice after that wait (CLI 0.6.0). If it still fails, the
+  command exits `7` and the message keeps the server's hint, such as
+  "Retry after 1s.". A write where some documents were rejected names the
+  first rejected document and the engine's reason.
 - **Branch on exit codes**, not on message text. See the table below.
 
 ## Exit codes
@@ -135,7 +144,7 @@ The CLI never waits for input it cannot get.
 | Code  | Meaning          | Typical cause                                                                                                   |
 | ----- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
 | `0`   | Success          |                                                                                                                 |
-| `1`   | Error            | Anything not listed below; also `schema diff` when changes are pending                                          |
+| `1`   | Error            | Anything not listed below; also `schema diff` when changes are pending, `sync reconcile` when drift is left     |
 | `2`   | Usage            | Unknown command or option, missing or malformed value, HTTP 400/413/422, confirmation needed without a terminal |
 | `3`   | Authentication   | No key found, a `--profile` that does not exist, HTTP 401                                                       |
 | `4`   | Permission       | HTTP 403, or 402 (the plan does not allow it)                                                                   |
@@ -163,27 +172,144 @@ uses defaults. Running `headband` with no command runs `init`.
 ```bash
 headband projects list [--json]
 headband projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
-headband projects delete <id> [--force] [--yes] [--json]
+headband projects delete <id> [--yes] [--json]
 ```
 
 `projects delete` refuses a project that still has indexes (exit `6`, code
-`project_has_indexes`). `--force` deletes the project's indexes on its shared
-engine along with it. Even with `--force`, a project with an index on a
-dedicated engine, or an index being moved to one, is refused: delete or move
-those indexes first. Deleting a project also deletes the API keys scoped to it.
+`project_not_empty`). Delete its indexes first. Deleting a project
+also deletes the API keys scoped to it.
+
+### Branches
+
+A branch is one environment of a project: its primary branch `main`
+(production), plus others such as `staging` or `preview/pr-123`. Each branch
+has its own indexes and its own keys.
+
+```bash
+headband branch list [--project <id>] [--json]
+headband branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+headband branch delete <name> [--project <id>] [--yes] [--json]
+headband branch protect <name> [--project <id>] [--json]
+headband branch unprotect <name> [--project <id>] [--json]
+headband branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]
+headband branch checkout <name> [--project <id>] [--json]
+```
+
+- The project comes from `--project`, else the directory's checkout (below).
+  With neither, the command is a usage error.
+- `create` makes an empty branch. Without `--empty` it fails with exit `6`
+  (code `fork_not_available`): copying a parent's data into a new branch
+  arrives with bucket storage. Until branches other than main open on the
+  server, every `create` fails with exit `6` (code `branches_not_open`),
+  `--empty` or not. `--parent` records the branch it comes from
+  (default: the primary branch). `--expires-in` deletes the branch on its own
+  after that long.
+- `delete` removes the branch with its indexes, keys and engines. It asks
+  first. The primary branch, a protected branch, a branch with live child
+  branches and a branch with Sync-owned indexes are refused (exit `6`).
+- `protect` blocks delete and expiry; `unprotect` lifts it. The primary
+  branch (`main`) serves production and is always protected: `unprotect`,
+  `expire` and `delete` on it are refused (exit `6`, code `branch_is_primary`).
+- `expire` takes exactly one of `--in <duration>`, `--at <ISO time>` (in the
+  future) or `--clear`.
+- Durations are a number and a unit: `s`, `m`, `h`, `d` or `w`, such as `30m`,
+  `2h` or `7d`.
+- Creating, deleting, protecting and expiring need the key from
+  `headband login`. `branch list` works with any admin key that reaches the
+  project.
+
+**Working on a branch.** `checkout` makes a directory work on one branch:
+
+```bash
+headband branch checkout staging --project <project id>
+headband indexes list              # staging's indexes
+headband docs push products.json --index products
+headband search products shoes     # searches staging
+```
+
+`checkout` writes `.headband/project.json`: `{ "orgId", "projectId", "branch" }`,
+with file mode `0600`. It holds no key. Every later command in that directory,
+or in any directory below it, sends `Headband-Branch: <project id>/<branch>`
+with your login key. That key reaches every branch of your organization, so no
+key is minted. Checking out `main` writes the file too. `checkout` needs a
+stored login (`headband login`), because the file records your login's
+organization. `--token` and `HEADBAND_API_KEY` take the place of a stored
+login, so unset them to check out.
+
+Like git, the CLI uses the nearest `.headband/project.json` in the working
+directory or a parent, up to your home directory (or the filesystem root,
+outside it). `checkout` rewrites that nearest file, or writes one in the
+working directory when there is none. As in git, a file another user owns, or
+one in a `.headband` directory another user owns, is an error: every command
+that would send `Headband-Branch` stops and names the file, and the search goes
+no further. So a file planted in a shared directory such as `/tmp` never steers
+your commands. A symlink is judged by its own owner, as in git, so another
+user's link to your `.headband` is theirs. `checkout` then writes your own file
+in the working directory, and never rewrites the other user's. When the other
+user's file is in the working directory itself, remove it before you check out
+there.
+
+A checkout never falls back to production silently. Every command that would
+send `Headband-Branch` stops with an error when the nearest
+`.headband/project.json` cannot be read, holds a value that is not a valid
+project id, branch name or branch id, or was written for another organization
+than your stored login's. Run `headband branch checkout <name>` again to rewrite
+the file, or delete it to work on production. A token (`--token`,
+`HEADBAND_API_KEY`) names no organization, so the organization check applies
+only to stored logins.
+
+For one command, `--project <id> --branch <name>` picks another branch, and
+`--branch <name>` alone takes the checkout's project. A branch id
+(`--branch br_...`) names its own project, so it is sent as it is and needs no
+`--project`. With no checkout and no `--branch`, commands reach each project's
+primary branch, as before. A branch name with no project at all is a usage
+error, so a name is never matched across projects by accident.
+
+`--project` without `--branch` is a usage error, because these commands send no
+project of their own and would ignore it. The exception is `keys create`, which
+sends the project in its body (see Keys).
+
+Coming with bucket storage: `branch create` without `--empty` (a copy of its
+parent), `reset`, `rollback`, `restore` and `set-primary`.
 
 ### Keys
 
 ```bash
 headband keys list [--json]
-headband keys create <name> --type <admin|search> [--project <id>]
-                     [--permissions <a,b,...>] [--expires <30d|ISO date>] [--json]
+headband keys create <name> --type <admin|search> [--project <id>] [--branch <name>]
+                     [--instances <id,id>] [--permissions <a,b,...>] [--expires <30d|ISO date>] [--json]
 headband keys revoke <id> [--yes] [--json]
 ```
 
+A key belongs to one branch and reaches only that branch's indexes, for an app
+such as a preview deployment. `keys create` picks the branch in this order:
+
+1. `--branch <name>`, in the project from `--project`, else the checkout's. A
+   branch id (`--branch br_...`) needs no project.
+2. The checked-out branch, unless `--project` names another project.
+3. The primary branch of `--project`.
+
+With none of these, `--type admin` mints an org key, which reaches every branch
+of every project, and `--type search` is refused (exit `2`, code
+`branch_required`), because search keys ship in browsers. A key on the primary
+branch is a live key (`hb_adm_live_`, `hb_src_live_`); a key on any other
+branch is a test key (`hb_adm_test_`, `hb_src_test_`). `keys create` and
+`keys list` show each key's branch and environment.
+
 `keys create` is the only command that prints a raw API key. Store it when it is
 shown: Headband returns raw keys only once.
 
+`--instances <id,id>` also limits the key to those dedicated engines. It takes
+one comma-separated list of 1 to 50 ids (from `headband instances list`);
+repeating the flag does not add engines, only the last one counts. An org key then reaches only them, on every
+branch. A branch key reaches its branch's engines among them, and every id must
+sit on that branch. Any other index answers as if it did not exist, and
+endpoints that are not about those engines refuse the key. The list is fixed:
+to change it, create a new key and revoke the old one. `keys list` and
+`keys create` show each key's engines: `all` when it is not limited, the engine
+ids when it is, `none` when its list reaches nothing, and `unknown` when the
+API did not report them (never shown as `all`).
+
 `--permissions` limits the new key to the permissions you list. You can grant
 only permissions your own key holds, and only ones that fit the key type:
 
@@ -194,8 +320,8 @@ only permissions your own key holds, and only ones that fit the key type:
 
 Anything else is refused with exit `4` and the names it refused. Without
 `--permissions`, the key gets the type's defaults, cut down to what your key
-holds. `keys.manage`, `projects.manage` and `schema.manage` are never
-grantable here; only `headband login` mints them.
+holds. `keys.manage`, `projects.manage`, `branches.manage` and
+`schema.manage` are never grantable here; only `headband login` mints them.
 
 `--expires` sets when the key stops working: a duration from now (`12h`,
 `30d`, `2w`, `1y`) or an ISO date (`2027-01-31`). It must be in the future and
@@ -216,8 +342,18 @@ headband indexes settings set <uid> --file <settings.json>
 headband indexes stats <uid>
 ```
 
+`index` is an alias of `indexes` for every command here: `headband index list`
+and `headband index switch-engine <uid>` work the same.
+
 `settings get`, `settings set` and `stats` always print JSON.
 
+`indexes create` prints the project and branch the index went to (CLI 0.6.0).
+With the key from `headband login` and no `--project`, `--branch` or
+checkout, that is the org's Default project, main branch.
+
+Deleting an index that a `schema apply` reindex moved to `<uid>__v2` also
+removes that build's own index row, so nothing is left behind.
+
 `--instance <id>` creates the index on one of your dedicated engines (ids from
 `headband instances list`). The index takes that engine's type, so `--engine` is
 optional; if you pass it, it must match.
@@ -226,18 +362,43 @@ On the engine, the index has a longer name (`engineIndexUid`, such as
 `hbo_<org>_products`). `indexes create` and `indexes list` show it. Use that name,
 not the uid, with the engine's own client on the instance endpoint.
 
+#### Change an index's engine
+
+```bash
+headband indexes switch-engine <uid> --engine <engine> [--instance <id>] [--accept-drops] [--declare-key] [--dry-run] [--wait] [--json]
+headband indexes switch-engine <uid> --status [--json]
+```
+
+Moves the index to another engine. The
+uid, keys and URLs stay the same, and searches keep working until the switch.
+Writes are held for about a minute at the end (they answer 503 with `Retry-After`).
+
+- `--dry-run` shows how many documents would be copied, where the new index goes,
+  and which settings would not carry over. It changes nothing.
+- A setting the new engine cannot apply stops the switch with exit code 6 and a
+  list of what would not carry over, with a reason for each. `--accept-drops`
+  switches anyway.
+- `--wait` follows the switch until it ends and prints each phase. Without it the
+  command returns once the switch is queued; `--status` shows how it went.
+- `--declare-key` is for a Visor index over 1000 documents whose primary key is
+  not filterable and sortable: the key is declared while the index is read, which
+  rebuilds it.
+
 ### Documents
 
 ```bash
 headband docs push <file.json|file.jsonl> --index <uid> [--json]
 headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--json]
-headband docs delete <docId> --index <uid> [--json]
+headband docs delete <docId>... --index <uid> [--json]
 ```
 
+`docs delete` removes one or more documents by id, in one call to
+`DELETE /v1/documents?index=<uid>`.
+
 `docs push` accepts a JSON array or a JSONL file and sends documents to
 `/v1/bulk` in batches of 1000.
 
-`docs export` pages through `GET /v1/documents` and writes every document in
+`docs export` walks `GET /v1/documents` by cursor and writes every document in
 the index, one page in memory at a time:
 
 ```bash
@@ -251,37 +412,62 @@ headband docs export --index products | head -5
 - `--format` is `jsonl` (one document per line, the default) or `json` (one
   array). With `--out`, a `.json` file name picks `json`.
 - `--out` writes to `<file>.partial` and renames it when the export finishes,
-  so a failed export never leaves a truncated file under the real name.
-  `--json` with `--out` prints a summary: `{index, out, format, exported}`.
+  so a failed export never leaves a truncated file under the real name. If the
+  export stops on an error after some documents were written (CLI 0.6.0), they
+  stay in `<file>.partial`, as a whole JSONL file or a closed JSON array, and
+  stderr says how many. `--json` with `--out` prints a summary:
+  `{index, out, format, exported}`.
 - `--batch` is the page size. The default is 1000, or 250 for an index on
-  Typesense, which refuses larger pages.
-- Elasticsearch serves at most the first 10,000 documents by paging, so a
-  larger Elasticsearch index fails partway with exit `8`.
+  Typesense, which refuses larger pages. The server may answer fewer a page.
+- The cursor reaches every document on every engine: Visor past its first
+  1000 and Elasticsearch past its first 10,000. A server without cursors is
+  paged by offset, as before CLI 0.5.0.
+- A Visor index created before 2026-10-21 with more than 1000 documents may
+  not have its primary key declared filterable and sortable. The server then
+  refuses the walk (exit `2`, code `feature_not_supported`), and the CLI prints
+  the fix: `headband indexes settings get <uid> > settings.json`, add the key
+  to the lists it names, `headband indexes settings set <uid> --file
+settings.json` (Visor rebuilds the index), then export again. New Visor
+  indexes declare the key on their own.
 - Export needs an admin key with `documents.read`.
 
 ### Search
 
 ```bash
-headband search <index> <query> [--limit N] [--filter <expr>] [--json]
+headband search <index> [<query>] [--limit N] [--filter <expr>] [--mode <instant|retrieval>] [--json]
 ```
 
+Without a query, or with `""`, search browses the index (CLI 0.6.0): every
+document matches, and `--filter` and `--limit` pick what comes back.
+
+`--mode` picks Visor's ranking: `instant` (the default, typo-tolerant,
+as-you-type) or `retrieval` (BM25F, for longer queries). Indexes on the other
+engines ignore it.
+
 Plain output shows a compact table. `--json` prints the raw API response.
 
 ### Tasks
 
 ```bash
-headband tasks list [--json]
-headband tasks get <id>
+headband tasks list [--index <uid>] [--limit <n>] [--json]
+headband tasks get <id> [--index <uid>] [--json]
 ```
 
 `tasks list` prints a table, or the raw response with `--json`. `tasks get`
 prints JSON.
 
+Tasks live on the engine that holds the index. The key `headband login`
+creates is org-wide, so it must name the index with `--index`. So must a key
+of a branch other than production. A project key of the production branch may
+leave it out.
+
 ### Engines
 
-Dedicated engines are private Meilisearch, Elasticsearch or Typesense servers for
-your organization, reachable with each engine's own client. They are rolling out
-gradually. Until your organization has access, these commands say so.
+Dedicated engines are private Meilisearch, Elasticsearch, Typesense or Visor
+servers for your organization, reachable with each engine's own client (Visor over
+its HTTP API). They are rolling out gradually. Until your organization has access,
+these commands say so. Visor is offered in a region where a dedicated engine host
+runs it; elsewhere `instances create visor` answers `engine_not_available`.
 
 ```bash
 headband instances list [--json]
@@ -308,23 +494,29 @@ woke, the outcome and how long it took to be ready. `--limit` takes up to 200;
 the default is 50.
 
 `connect` prints the endpoint and a snippet for the engine's own client.
-Authenticate with an organization-wide key. The snippets create an index and add
+Authenticate with an organization-wide key, a branch key of the engine's branch, or a key limited to that engine. The snippets create an index and add
 a document, so run them with an admin key (`headband keys create <name> --type
-admin`); a search key can only search. Project keys do not work on engine
-endpoints. Serverless engines are available for Meilisearch, and for Typesense
+admin`); a search key can only search. A key of another branch does not work on the engine. Serverless engines are available for Meilisearch, and for Typesense
 in early access; Elasticsearch runs always on. If a command says the key cannot
 manage engines, run `headband login` again.
 
 ### Schema migrations
 
 For projects that define their indexes in `headband.config.ts` with
-`@headband/sync`. These commands read that file from the current directory.
+`@headband/sync`. These commands read that file from the current directory:
+its default export is `defineConfig({ url, projectId?, indexes })`, and `apply`
+also needs a named `adapter` export, such as `drizzleAdapter(...)` from
+`@headband/drizzle`, in the same file. When the adapter is exported, the
+config is checked against your tables first, and every misspelled table,
+field, relation or settings attribute is listed with its index.
+`headband schema <command> --help` describes each command.
 
 ```bash
 headband schema diff [--allow-destructive] [--json]
 headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]
-headband schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]
+headband schema apply [--project <id>] [--allow-destructive] [--dir <dir>] [--yes] [--json]
 headband schema status [--dir <dir>] [--json]
+headband schema forget <index> [--yes] [--json]
 ```
 
 - `diff` compares the config with the schema state on the server. Like
@@ -333,15 +525,30 @@ headband schema status [--dir <dir>] [--json]
 - `generate` writes a migration file for the pending changes into `--dir`
   (default `headband/migrations`). `--json` prints `{path}`, with `null` when
   there was nothing to generate.
-- `apply` runs the migration files not yet applied, in order, backfilling
-  documents through your config's `adapter` when a change needs a reindex.
-  Removing an index needs `--allow-destructive`. `--json` prints
-  `{appliedFiles, appliedOps}`.
-- `status` shows each index's applied version and any drift. `--json` prints
+- `apply` runs the migration files the server does not have yet, in order. A
+  new index is created and backfilled from every source row (rows
+  `shouldIndex` rejects are left out). A schema change builds a new index
+  beside the live one, backfills it and switches the name over. Removing an
+  index needs `--allow-destructive`. `--json` prints
+  `{appliedFiles, appliedOps, projectId}`.
+- `apply` recognises migrations the server already has from its schema state,
+  so a fresh checkout or CI applies without `headband/migrations/.applied.json`.
+  That file is only a local cache: commit it or ignore it.
+- `status` shows each index's applied version and any drift, including
+  `index missing` for an index deleted outside `apply`. `--json` prints
   `{indexes, localApplied, localHead}`.
+- `forget` removes the recorded schema state of an index deleted outside
+  `apply`, so the next `generate` plans it as new. `headband indexes delete`
+  clears it for you.
 
 Schema commands need a key with `schema.manage`, which only `headband login`
-mints.
+mints. That key is org-wide: new indexes go to the project named by
+`--project <id>` or the config's `projectId`, else to your org's Default
+project. Your app's own project admin key reaches only its project's indexes,
+so name that project.
+
+The URL comes from `--url`, else `HEADBAND_URL`, else the config's `url`, else
+your login's.
 
 ### Sync
 
@@ -382,35 +589,57 @@ Headband's setup SQL on your machine as the tables' owner, in one transaction;
 the owner URL never leaves your machine. Run `headband sync source --help` and
 `headband sync index --help` for the details.
 
+Managed Sync is in early access: until your organization has it, these
+commands say "Sync is not enabled for this organization yet."
+
 **Self-hosted Sync** runs a worker in your own infrastructure. Your app writes
-changes to an outbox table, and the worker pushes them to Headband.
+changes to an outbox table, and the worker pushes them to Headband. The
+`@headband/drizzle` README walks through the whole setup.
 
 ```bash
-headband sync init [--table <name>] [--write] [--json]
-headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]
+headband sync init [--table <name>] [--write] [--apply] [--json]
+headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]
 headband sync worker --scaffold docker [--force] [--json]
 headband sync reconcile [--fix] [--json]
 headband sync retry-dead-letters [--json]
+headband sync status [--json]
 ```
 
 - `init` prints the outbox table's DDL; `--write` also saves it to
-  `headband/outbox.sql`. `--json` prints `{ddl, path}`.
+  `headband/outbox.sql`, and `--apply` runs it against `DATABASE_URL` (it is
+  `CREATE TABLE IF NOT EXISTS`). `--json` prints `{ddl, path, applied}`.
 - `worker` drains the outbox. Without `--budget-ms` it loops until stopped
-  (Ctrl+C or SIGTERM finish the current batch first). With `--budget-ms` it
-  stops after that long; `--json` then prints the run report. In a loop,
+  (Ctrl+C or SIGTERM finish the current batch first), so `--loop` changes
+  nothing on its own. With `--budget-ms` it stops after that long, or earlier
+  once the outbox is empty; add `--loop` to keep waiting for changes until the
+  budget ends. `--json` then prints the run report. Each batch that drained
+  rows prints one line to stderr (CLI 0.6.0). In a loop,
   `--json` sends progress to stderr and prints the report when the worker
-  stops.
-- `worker --scaffold docker` writes `Dockerfile.headband-sync` and prints a
-  compose service for it.
-- `reconcile` compares each index's document count with its source table and
-  reports drift; `--fix` resends a drifted index in full. `--json` prints
-  `{indexes}`.
+  stops. A row that fails is printed with its model, ids and error; a batch
+  that fails is retried row by row, so one bad row never fails the others.
+  Rows that keep failing move to the dead letters. Each invocation is recorded
+  as one run under the connector `orm-sync` (`GET /v1/connectors/runs`); with
+  the org-wide login key that needs `--project <id>` or the config's
+  `projectId`. `--reconcile-every <n>` runs `reconcile` after every n-th batch.
+- `worker --scaffold docker` writes `Dockerfile.headband-sync`, which runs
+  `npx --yes @headband/cli@<version> sync worker --loop`, and prints a compose
+  service for it. The container needs `DATABASE_URL` and `HEADBAND_API_KEY`.
+- `reconcile` compares the source rows that belong in each index (every row
+  `shouldIndex` keeps) with the documents in it, and reports how many are
+  missing and how many are extra (counts, not ids). `--fix` pushes the missing
+  and deletes the extra. It exits
+  `1` when drift is left. `--json` prints `{indexes, drift}`. The index's ids
+  are read by cursor, so a Visor index past 1000 documents is compared id by
+  id too.
 - `retry-dead-letters` requeues rows that failed too many times. `--json`
   prints `{requeued}`.
+- `status`, beside a `headband.config.ts`, shows the outbox's pending rows,
+  dead letters and oldest pending row. Elsewhere it shows managed Sync.
 
-The worker and `retry-dead-letters` read the outbox database URL from
-`DATABASE_URL`, falling back to `HEADBAND_DATABASE_URL`. The worker and
-`reconcile` need `headband.config.ts` to export an `adapter`.
+The worker, `retry-dead-letters`, `status` and `init --apply` read the outbox
+database URL from `DATABASE_URL`, falling back to `HEADBAND_DATABASE_URL`. The
+worker and `reconcile` need `headband.config.ts` to export an `adapter`. A
+missing outbox table is reported by name, with how to create it.
 
 ## What `init` creates