[mnemitz]

Stack 4 of 4, splitting #331 for review. Based on #336.

1. Site fixes (Site fixes ahead of the API reference work #334)
2. Management reference from the public spec (Build the Management reference from the public spec #335)
3. Code samples, tested against a mock (Code samples for every Batch and Management operation, tested #336)
4. API reference on Speculoos ← this PR

When the stack is merged, main matches #331's branch, minus SPECULOOS-PLAN.md (deleted here).

What changes

Every API reference page is rendered by Speculoos (0.1.0-alpha.1) from IR built at build time (npm run build:speculoos-ir, wired into start and build). scripts/generate-speculoos-pages.ts writes one page per REST operation or WebSocket channel into gitignored directories, which the sidebar lists with autogenerated. A page's own prose, which the spec can't express (handshake responses, how a connection closes), lives in partials beside the pages.

Specs

• Realtime is rewritten as canonical AsyncAPI 3, with its authentication and WebSocket handshake declared. Agent STT is generated from it plus its overlay.
• Batch renders from the OpenAPI 3.1 copy the code-sample tests already read (Code samples for every Batch and Management operation, tested #336). Management renders from the public spec (Build the Management reference from the public spec #335).

Rendering (src/components/Speculoos/)

• site.tsx: how this site renders Speculoos. That's the Radix Themes map, with the site's Markdown, the sidebar's badge colours, and types expanded where they're used.
• SessionPanel.tsx: a channel's session as a compact sequence diagram beside the reference, with each message linking to its section and showing its example on hover. Below lg it comes first, collapsed.
• OperationPanel.tsx: an operation's code samples, then its examples, each labelled by its status's description ("400 Bad request").
• Schema.tsx: <Schema> puts the same field tables in guides, headed by the type's name and a link to where the reference uses it. open opens one field among the rest. The Batch and Realtime guides use it in place of the old SchemaNode and AsyncAPI loader.
• The site's Markdown component moves to src/components/Markdown, on react-markdown 10 with remark-gfm 4 and rehype-raw 7.

Removed: the OpenAPI plugin and theme, its templates and the sidebar filter for Batch paths, the Schema/SchemaItem theme components, the AsyncAPI and OpenAPI schema loaders, and the old WebSocket pages with their generator.

Worth reviewing

• Redirects: the Batch and Management info pages, the removed Batch log endpoint and post-a-new-project (from Build the Management reference from the public spec #335) are all in redirects.json / vercel.json.
• Anchors change: message anchors are kebab-case now (#startrecognition → #start-recognition). In-repo links are updated, but external deep links to the old anchors will land at the top of the page; redirects can't cover fragments.
• CI builds from a clean checkout: partials and src/generated are produced by the build, not committed.
• Speculoos is an alpha from npm. npm run speculoos:local tries local packs of the Speculoos repo.

Checked

• npm run build passes, with no broken links.
• tsc passes once the build has generated src/generated.
• npm run test:code-samples: all 24 samples pass.

Closes #331 once the stack lands.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Nov 2, 2026 4:06pm UTC