docs: Document API tokens and the OpenAPI reference

CLAUDE.md

@@ -434,6 +434,39 @@ same commit.
 
 `UpdateAgentCmd` carries a target version and Gitea base URL; the agent downloads and replaces itself.
 
+### API tokens and OpenAPI
+
+A token is `vt_` plus 32 random bytes hex, shown once at creation and stored
+only as sha256 — the same shape as `servers.agent_token_hash` and the ESO read
+token, and for the same reason: nothing downstream ever needs the plaintext
+back. It belongs to the user who created it, and its role can never exceed
+theirs; see the `api_tokens` note under MongoDB Collections for how that stays
+true across a demotion rather than only at issuance. Scopes are eight
+resources — `servers`, `keys`, `secrets`, `workflows`, `monitors`, `vulns`,
+`workloads`, `settings` — each split into `:read` and `:write`, with `:write`
+satisfying a `:read` requirement on the same resource so a caller does not have
+to hold both. `settings:write` covers token management itself, which is why
+creating and revoking tokens is owner|admin territory the same as the rest of
+Settings. Expiry is optional per token; `settings.api_token_max_days` caps how
+far out a new one may be set, and when that cap is set a token requested with
+no expiry is refused rather than silently capped — the policy governs
+issuance only and never reaches back to invalidate a token already issued.
+`RateLimitTokens` holds every token to 600 requests/minute in a Redis fixed
+window, answering 429 with `Retry-After`; cookie sessions are untouched; it
+exists so a runaway script cannot take an instance down, not as the general
+API rate-limiting project some future ticket might build.
+
+`server/internal/api/docs/openapi.json` is a **generated, committed** OpenAPI
+3.1 document — `swag v2` reading `@…` annotations off the handlers — served at
+`GET /api/openapi.json` and rendered as a reference page by a vendored Scalar
+bundle at `GET /api/docs`. `server-deploy.yml` regenerates it on every server
+build and runs `git diff --exit-code` against the committed copy: a handler
+whose annotation drifted from its code fails CI rather than shipping a
+reference that lies. Scalar is vendored (`scalar.standalone.js`, served from
+`GET /api/docs/scalar.js`) rather than pulled from a CDN, because the
+reference page has to work on an air-gapped install with no outbound access at
+all — the same requirement licence verification already meets.
+
 ### Marketing site and sitesvc
 
 `site/` is a separate Next.js app built exactly like `web/` — `output: "standalone"`, run by Node in a `node:26-alpine` image, listening on `3000` and published as `3003`. The contact form posts to `sitesvc`; account signup posts to `admin` (`NEXT_PUBLIC_ADMIN_API_URL`), which creates an HQ account, not an org — the control plane is not touched until the customer later creates a cloud instance from the portal.
@@ -675,6 +708,8 @@ licence      GET /license · POST /license                (POST: self-hosted onl
 org          GET,POST /org/users · PUT /org/users/:id/role · DELETE /org/users/:id
 providers    GET,POST /auth/providers · PUT,DELETE /auth/providers/:id
              POST /auth/providers/:id/{test,ack-notice} · GET /auth/presets  (owner|admin)
+tokens       GET /tokens · GET /tokens/scopes · POST /tokens · DELETE /tokens/:id
+             GET /openapi.json · GET /docs
 ```
 
 `GET /license` reports `deployment`, and **`POST /license` answers 409 `cloud_managed` when it is `cloud`**. A cloud instance's licence is written by `admin/internal/inject` straight into the database and never through this endpoint, so the refusal cannot break injection — it only stops a customer pasting over a licence they do not own. `web/` hides the paste form and points at the HQ portal instead, but as with `hq`-managed users, the API is the boundary and the UI is the courtesy.
@@ -749,7 +784,7 @@ Paddle is merchant of record; `admin/internal/paddle` is a thin REST client (no
 
 ## MongoDB Collections
 
-`servers` · `keys` · `assignments` · `orgs` · `users` · `auth_providers` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `workflow_log_lines` · `workflow_log_seq` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `server_packages` · `vuln_findings` · `vuln_alert_rules` · `vulndb_meta` · `server_workloads` · `migrations`
+`servers` · `keys` · `assignments` · `orgs` · `users` · `auth_providers` · `settings` · `secrets` · `workflows` · `workflow_steps` · `workflow_runs` · `workflow_log_lines` · `workflow_log_seq` · `monitors` · `incidents` · `monitor_rollups` · `notification_channels` · `console_sessions` · `audit_logs` · `server_packages` · `vuln_findings` · `vuln_alert_rules` · `vulndb_meta` · `server_workloads` · `api_tokens` · `migrations`
 
 Every document except `migrations` carries `org_id`. Struct definitions are the source of truth — see `server/internal/models/`.
 
@@ -768,6 +803,7 @@ Notes that are not obvious from the structs:
 - `vuln_findings` is unique on `(instance_id, server_id, cve_id, package_name)`. That key is what makes a rescan an idempotent upsert rather than a duplicate factory, and what lets `first_seen` survive one. An empty `fixed_in` means no vendor fix exists — a real state, never "not vulnerable".
 - `vulndb_meta` is a singleton and deliberately carries **no** `instance_id`: the vulnerability database is a property of the deployment, not a tenant. Same reasoning as `migrations`, and the reason it is absent from `services.ScopedCollections`.
 - **`services.ScopedCollections` is the canonical registry of tenant-scoped collections**, and `scopedCollectionsForPurge` derives instance deletion from it rather than keeping a second list. A new collection carrying `instance_id` must be added there or its rows outlive the instance.
+- `api_tokens` stores only `sha256` of the token, like `servers.agent_token_hash`. A token's effective role is `min(user.role, token.role)` **recomputed per request**, so demoting somebody demotes their tokens; deleting the user deletes them. Scopes are enforced from a map keyed on the registered gin route pattern, and `AssertScopeMapComplete` **fails boot** when an `/api` route is missing from it — a route added without an entry would otherwise be silently unreachable by every token.
 
 Admin's own database is separate and holds `accounts` · `admin_instances` · `licenses` · `subscriptions` · `plans` · `catalogue` · `entitlements` · `paddle_events` · `staff_users` · `customer_users` · `instance_members` · `admin_audit`. `paddle_events` is the webhook idempotency log, unique on `event_id`: an event is claimed there before processing, and a duplicate of a handled event is a 200 no-op. `instance_members` is unique on `(instance_id, customer_user_id)` — one person holds at most one user in one instance, which makes a grant idempotent-by-refusal rather than silently doubling a projection. It is an _index_ of the control-plane rows, not the authority (see "Grants project, they do not federate"). Admin has no migrations collection; `models.Backfill` runs on every boot and is idempotent by filtering on the absence of what it writes.