Docs coverage
What the user and developer docs cover at this pin, what is stale, and what is still only a spec.
Docs coverage
Pin: e32f292468c4104a1f9fe8bf8db2f22c159567f1 (main, 2026-11-03).
Baseline for the diff: the last commit that changed docs/ before this pass was f44dad8a (2026-10-19), a refactor that touched the tree. The last pass that rewrote user and developer prose was 643d6024 (2026-09-12). This page is the record of the 2026-11-03 pass.
Vocabulary:
| Status | Meaning |
|---|---|
| DOCUMENTED | A page exists and matches the code cited on it. |
| STALE | A page existed and contradicted the code. The contradiction is named here, and the page was corrected in this pass. |
| UNDOCUMENTED | Shipped, and this pass added the page. |
| SPECCED, NOT SHIPPED | In planning, absent from the code. Not written up as a working feature. |
Corrected in this pass
| Page | Was wrong | Code |
|---|---|---|
| CLI reference | Said clone, migrate, and provision all exit 3 as unimplemented. | agent/internal/cli/cli.go: clone calls cmdClone, migrate calls cmdMigrate, only provision exits 3. |
| CLI reference | Omitted pack, recovery-pg, recovery-order, verify, update, capacity, mta. The license table omitted agent, proxy, and mta. | Same file, usage and gatedCommands. |
| User CLI reference | clone --new-ip and migrate --new-ip do not exist. provision was described as working. | cmdClone wants --from. cmdMigrate wants a container, --source-ssh, and --app. |
| Database and migrations | Said the app deploys through Coolify on 31.220.104.207 by git push. A later step still said "Push. Coolify auto-deploys". | Coolify is retired. The swap is scripts/node/redeploy-hostssh-cp.sh. See Control plane deploy. Step 3 now says the same. |
| Architecture | The diagram and the opening paragraph still put this app on Coolify at 31.220.104.207, deployed by git push. The rate-limiter sentence named that container. | Container hostssh-cp on 31.220.104.223. The limiter in lib/ratelimit.ts is per-process. |
| Changelog | Intro still described Coolify auto-deploy, and the newest entry stopped in July 2026. | The intro now points at the deploy page. The 2026-09 to 2026-11 section lists what this pin contains. |
| Docs index builder | scripts/build-docs-index.mjs read only the top level of docs/user and docs/dev. docs/user/admin/*.md never reached /docs. | The builder walks subdirectories. lib/docs/links.ts resolves links from the page's directory. |
Added in this pass
| Page | Status | Source |
|---|---|---|
| Recovery commands | DOCUMENTED | recovery_pg.go, recovery_order.go, pack.go, cmdVerify |
| Reading the console | DOCUMENTED | lib/health/pulse.js, lib/data.ts, commit e32f2924 |
| Control plane deploy | DOCUMENTED | scripts/node/redeploy-hostssh-cp.sh, list.ts, store.ts |
| This page | DOCUMENTED | the diff above |
Operator pages that already existed under docs/user/admin/ become servable at /docs/user/admin/... once content-index.json is rebuilt. They were written earlier. This pass did not re-audit every sentence in them.
API routes checked against docs/dev/api-reference.md
56 route.ts files under control-plane/web/app/api. The reference already had a summary table. These paths were absent from that file and are now rows in it:
| Route | Auth in the handler |
|---|---|
GET /api/v1/dl/{channel}/{asset} | none. Redirects to the release object. Never proxies the bytes. app/api/v1/dl/[channel]/[asset]/route.ts |
POST /api/v1/storage/download | agentGate, then the license's RLS scope. Mints a SigV4 GET. Does not stream the object. |
GET /api/v1/provisioning/preflight | provisioning worker. Read-only. 412 when the report is not ok. |
POST /api/v1/provisioning/enroll/{id} | bearer enrollment token, rate-limited per IP. Returns a shell script. |
GET/POST /api/v1/computers | computer API key. Creates or lists sandboxes. |
GET/DELETE /api/v1/computers/{id} | same key. Another license's id is a 404. |
POST /api/v1/computers/{id}/http/{verb} | same key. Forwards one allowlisted verb into that sandbox. Headless: goto, observe, act, content, extract, close. Desktop: exec, screenshot. |
GET/POST /api/v1/mcp/registry | session plus fleet.manage. |
GET /api/v1/github/install/callback | signed-in session. Installation id in the query is not trusted alone. |
GET/POST /api/auth/{path} | better-auth. Includes /api/auth/jwks. |
DELETE /api/v1/email/keys/{id} | already grouped with the keys row. Left as a group. |
GET /api/v1/email/messages/{id} | hs_ API key. Another tenant's id is a 404. |
POST /api/v1/email/mta/raw | Bearer HOSTSSH_MTA_FEEDBACK_SECRET. Fail-closed when the secret is unset. Raw DSN/ARF body. |
DELETE /api/v1/webhooks/endpoints/{id} | already grouped with the endpoints row. |
A hand table is not an OpenAPI document. Generating one from the handlers is still open. See the roadmap card hs-docs-0003 in planning/TODO.md.
Migration ledger
list.ts imports 58 modules, 0001 through 0058, ending at 0058_fleet_alert_outbox. Two of them are .js (0049-git-delivery-tracking.js, 0058-fleet-alert-outbox.js). The rest are .ts. The database page lists every id. Individual SQL comments live in the module files. This pass did not restate each statement.
SPECCED, NOT SHIPPED
These are in planning. They are not documented as working.
| Item | Where it is specified | What the code does |
|---|---|---|
hostssh provision | usage text in cli.go | Prints that it is not in this build and exits 3, after the license gate. Provisioning runs through the control-plane worker. |
| Unattended relocate and a signed public one-liner | planning/PRODUCT-VISION.md | Private beta. The homepage says so. |
| Live fleet inference completion | planning/INFERENCE-PLATFORM.md | Gateway code exists. A live fleet curl proof is still an open planning row. |
| External pentest and the 10/10 stamp | planning/PLATFORM-READINESS-10-OF-10-2026-09-02.md | Not run. Do not write a passing report. |
| Alert outbox on by default | migration 0058 creates the table | outboxEnabled is true only when the database is on and HOSTSSH_ALERT_OUTBOX_ENABLED=1. |
| Billion-path reference restore clock | planning card hs-b1b-0003 | A disposable run on 2026-11-04 passed GET /ready 0.19 minutes after capture was requested. Production restore is still off. The note is planning/algorithm/billion-engine-2026-11-03/drill-pass-2026-11-04-0422.md. |
Production versus this pin
Public /healthz on 2026-11-03 reported migrations 58/58 and rateLimit: memory (planning/NOW.md). The same note records SOURCE_COMMIT behind main. Docs in this commit describe main. The serving container matches them after the owner redeploys.
Cadence
Repeat this diff at the end of a program and at each major milestone. The milestones and the card are in planning/MASTER_PLAN.md and planning/TODO.md (hs-docs-0002). A scheduled run writes an updated copy of this page. It does not invent features from a spec. Loading these files into the docs table is a separate owner step (hs-docs-0004, control-plane/web/scripts/ingest-docs.mjs). A docs pass does not run that ingest.