docs(spec): reality-audit — openapi + sitemap + account-keys sk_live examples

[Mlaz-code]

Final piece of the 2026-06-26 docs reality audit: the machine/spec files, built on top of the merged family pieces (#272 events, #273 historical, #274 catalog, #275 odds; opportunities piece NOT merged).

Audit commits carried

• 83fb982 (WIP tip of docs/audit-2026-06-26-fixes) — hunks for this piece's 4 files only: public/openapi.json, public/openapi-version.json, public/sitemap.xml, content/en/api-reference/account-keys.mdx.

Reconciliation against what actually merged

• openapi.json: the audit's spec body is semantically identical to main's (scripts/check-openapi-version.mjs: "no path/schema changes detected") — only x-generated-at / x-commit-sha provenance metadata differ. So there were no unmerged-family (opportunities) endpoint changes to revert; the spec describes exactly what the live docs pages now say.
• openapi-version.json: committed sidecar was stale (2.1.0) vs the spec's info.version (3.1.0) — synced. (stamp-openapi.mjs regenerates both at build; this fixes the committed state.)
• sitemap.xml: instead of the audit's 06-26 snapshot (224 URLs), regenerated with the repo's own scripts/generate-sitemap.mjs against today's content tree (228 URLs). The audit snapshot was already missing concepts/market-lifecycle (x4 locales) added to main after the audit. Superset of the audit's additions (entity-reference-ids, liquidity, polymarket-resolution x4 locales, trailing-slash + hreflang format).

Live verification (2026-07-02, OVH :3003)

Endpoint	Result
GET /account/keys (internal key, no user_id)	verified — HTTP 400 {"error":{"code":"validation_error","message":"No user_id associated with this API key"}}, exactly as the page now documents; error envelope has no docs field (audit's removal confirmed)
GET /account/keys 200 shape	verified against sharp-api-go/keys.go on main (1940dc1) — {success, data:[{id, id_masked, name, tier, is_active, created_at, updated_at}], meta:{count, max_keys}} (can't exercise 200 live without a customer key)
POST /account/keys	verified vs handler — returns 200 (not 201), meta.warning string exact; name optional, max 100 chars
DELETE /account/keys/{keyId}	verified vs handler — {success, data:{deleted, key_id, message}}; 404 "Key not found or not owned by you"; 400 "Cannot delete the API key you are currently using"
POST /account/keys/{keyId}/rotate	verified vs handler — gracePeriodHours 0–72; data.new_key/{old_key} shape; both meta.warning/meta.message strings exact

Drift fixed beyond the audit (handler is ground truth):

• id_masked example: "..." + last 8 chars (audit showed 9)
• max_keys for pro = 1, not 5 (maxKeysPerTier: free/hobby/pro=1, sharp=2)

Notes

• sk_live_ example keys are intentionally truncated fakes (sk_live_new345mno678...) — GitHub push protection rejects full-length fake sk_live keys. Real keys are sk_-prefixed; main's sharpapi_... format was fiction.
• Key-management endpoints support dashboard session auth + API-key auth (authenticateClerkOrAPIKey) — page claim verified.
• i18n backfill follow-up needed for de/es/pt-BR (account-keys.mdx changed in en only).

Type: docs

[Mlaz-code]

Merge gate (auto-classified): gate=docs — auto-classified by the gate-log enforcer (9min after merge, no Merge gate: audit comment found). Reviewer agent: please correct if wrong by replying with Merge gate: gate=<correct-word> — <evidence>. The audit log keys on the first such token; your correction overrides this auto-classified guess.

Posted by scripts/gate-log-enforcer.py because instruction-level rules about the gate= template aren't binding (0/N adoption); structural enforcement fills the log either way.