feat(docs): interactive API reference on /docs/rest-api

[vreshch]

What & why

Upgrades /docs/rest-api from a single hand-written endpoint into an interactive, grouped API reference that reproduces the approved prototype inside the landing docs engine.

Proto source: _archive/proto/api-reference-page/index.html (grouped endpoint list -> expandable contract per row).

What changed

• New endpoints DocBlock type (docs/types.ts): { type: 'endpoints', groups: EndpointGroup[] } plus Endpoint / EndpointArg / EndpointError / EndpointGroup / HttpMethod / EndpointStatus.
• Endpoint data (lib/api-endpoints.ts): all 10 endpoints transcribed exactly from the proto API array (same copy, contracts, grouping: Vaults / Notes / Search & export). Reuses REST_API_BASE_URL from lib/mcp-docs.ts.
• Client island (components/docs/endpoint-list.tsx, 'use client'): accordion rows - colored method badges (GET success / POST info / PUT warning / PATCH tag-schedules / DELETE destructive, all soft /10 bg + /20 border), chevron rotate, aria-expanded + aria-controls, independent open state per row, orange draft-warning line for planned rows, Live vs Planned - wave N chips. Bodies toggle via CSS so the contract stays in the prerendered HTML.
• JSON highlighter (components/docs/json-highlight.tsx, 'use client'): response blocks normalized through JSON.parse/stringify (2-space) then tokenized - keys / strings / numbers / booleans+null each distinct via semantic tokens (works light + dark). No shiki in the island; local tokenizer. Binary export response stays plain text.
• Renderer wired (docs/components/doc-article.tsx): case 'endpoints'.
• Page rewired (docs/content/rest-api.ts): kept lede + endpoint + authentication + Limits and versioning + What this API is not; replaced the hand-written example / response-schema / errors sections with one endpoints block.

Theme mapping / deviations

Proto used dashboard OKLCH tokens directly; all map 1:1 to the landing DS semantic tokens (success/info/warning/destructive/tag-schedules for the PATCH purple, primary/primary-soft, muted-foreground, etc.), so light + dark both work with no custom colors. Code/response blocks reuse the landing CodeBlock chrome (copy button + language chip) instead of the proto's bare <pre>, to match existing docs pages. No forced visual deviations otherwise.

Verify evidence

• npm run verify green: type-check + lint + format:check + test + build. /docs/[slug] prerenders as static HTML (SSG).
• Runtime: production build + next start -p 3013, curl /docs/rest-api -> 200. Prerendered HTML contains: /v1/vaults x45, PATCH badge present, method-badge classes for all 5 verbs (6 GET / 1 POST / 1 PUT / 1 PATCH / 1 DELETE), 6x Planned - wave 2 + 3x Planned - wave 3 + 1 live, draft-warning line, and JSON highlighting spans (numbers in text-warning, keys in text-info, strings in text-success, booleans/null in text-tag-schedules; 91 token spans, 9 json chips). Server stopped after check.

MERGE ONLY AFTER REVIEW

Merging landing master auto-deploys BOTH dev and prod. Do not merge until reviewed. This PR is DRAFT.

[github-actions]

✅ CI - Verify PASSED

Commit: 63a764fee2fe793123826c02c35e82ae21a15fd2 · Branch: feature/api-reference-ui

• ✅ Type check
• ✅ Lint
• ✅ Format check
• ✅ Unit tests
• ✅ Build
• ✅ Landing e2e

🔗 View workflow run