Track D — Developer Docs
Goal: the public developer docs at router.africa/docs: a custom docs app in the website repo that matches the features of OpenRouter’s docs, with the API reference rendered from our own curated OpenAPI spec.
Done when: the docs are live before launch, every documented sample runs against staging, the spec matches apps/api (contract test), and llms.txt and the .md pages are served.
Where it runs: in parallel with phases 1–9, mostly in the website repo (router.africa-website). The OpenAPI spec and its contract test live in the code repo next to apps/api. D.09 is the launch gate and replaces the old single docs task in phase 9 (P9.13).
Spec: ../product/api-docs-scope.md (content scope and features), ../product/api-surface.md (which endpoints are public), ../product/openrouter-api-comparison.md (compatibility differences), decisions log Developer docs site.
| ID | Task | Who | Needs | Status |
|---|---|---|---|---|
| D.01 | Audit OpenRouter’s docs site | You + agent | — | done — audit in context #13; human pass (HTML only, no screenshots) on this branch |
| D.02 | Docs design pass | You + agent | D.01 | todo |
| D.03 | Docs app skeleton | Agent | D.02 | todo |
| D.04 | AI-readable outputs and page actions | Agent | D.03 | todo |
| D.05 | Search | Agent | D.03 | todo |
| D.06 | Curated OpenAPI spec and contract test | Agent | P1.08, P3.08 | todo |
| D.07 | API reference and Request Builder | Agent | D.03, D.06 | todo |
| D.08 | Guides and content | Agent | D.03, P1.08 | todo |
| D.09 | Verify and publish (launch gate) | You + agent | D.04–D.08, P9.08 | todo |
| D.10 | Ask AI (nice to have) | You + agent | D.04 | todo |
The website work for Track D ships as one PR (D.02 mockups through D.08), reviewed visually before merge. D.10 stays out of the current plan.
D.01 — Audit OpenRouter’s docs site
Section titled “D.01 — Audit OpenRouter’s docs site”Who: You + agent · Needs: —
The existing audit (openrouter-api-comparison.md) covers OpenRouter’s API, not its docs site. Walk the live docs as a reader, with screenshots, and list every site feature: navigation, search and its shortcut, any AI assistant, page actions, code blocks and switchers, the Request Builder, reference page layout, callouts, changelog, theme, feedback widgets and footer. Mark each one: match, match differently, or skip, with a reason.
Already seen from their page source (2026-10-26):
-
llms.txtand a.mdversion of every page -
language and package-manager tabs, line numbers, expandable code
-
callouts
-
a Request Builder
-
a reference generated from a published OpenAPI spec, with examples for each error status
-
Spec: decisions log, Developer docs site
-
Done when:
../product/openrouter-docs-site-audit.mdexists with every feature marked, andapi-docs-scope.mdsection 4 is updated with anything new.
D.02 — Docs design pass
Section titled “D.02 — Docs design pass”Who: You + agent · Needs: D.01
Static mockups in the Router.Africa design system for the page types, approved by you before building:
- docs landing
- a guide page
- an API reference page
- the Request Builder
- search
- mobile navigation
Both a dark and a light theme, following the device setting (prefers-color-scheme) by default, with a toggle. Match how the marketing site handles theme. OpenRouter’s docs default to dark; ours follow the device.
- Spec:
../product/design-system/README.md; D.01 - Done when: you’ve approved the mockups.
D.03 — Docs app skeleton
Section titled “D.03 — Docs app skeleton”Who: Agent · Needs: D.02
In the website repo, a custom Astro docs section at /docs (no Starlight):
- MDX content collection
- docs layout: sidebar, table of contents, breadcrumbs, previous and next links
- callout components
- code blocks: language tabs with the choice remembered, SDK switch (OpenAI SDK, Anthropic SDK, HTTP), package-manager tabs, copy button, line numbers, expandable blocks
- changelog page
- a “Docs” link in the site nav
Resolve the build checks in api-docs-scope.md section 4: i18n (docs launch in English; build the routes so /fr/docs and /sw/docs can be added later following the site’s URL convention and language switcher, with fallback to English for a page not yet translated), the sitemap, and @astrojs/cloudflare.
- Spec:
../product/api-docs-scope.mdsection 4; D.02 - Done when: a sample page renders to the approved design on a preview deploy, and the site’s other routes and locales are unchanged.
D.04 — AI-readable outputs and page actions
Section titled “D.04 — AI-readable outputs and page actions”Who: Agent · Needs: D.03
At build time:
- a
.mdversion of every docs page at/docs/<page>.md - an
llms.txtindex - an
llms-full.txtwith the whole docs in one file
English is canonical for these; the fr and sw .md pages are served too, and the index lists each language.
On every page, a menu with “Copy page” (Markdown), “View as Markdown”, “Open in ChatGPT” and “Open in Claude” (each with a prompt that points the tool at the page’s Markdown URL).
- Spec:
../product/api-docs-scope.mdsection 4 - Done when: the outputs are served with the right content type on a preview deploy, and the “Open in” links load the page in each tool.
D.05 — Search
Section titled “D.05 — Search”Who: Agent · Needs: D.03
Pagefind full-text search over the docs only, opened with ⌘K / Ctrl+K, with keyboard navigation of results. One index per language, so a French reader searches French pages.
- Done when: search finds pages by heading and body text in each language, and stays scoped to
/docs.
D.06 — Curated OpenAPI spec and contract test
Section titled “D.06 — Curated OpenAPI spec and contract test”Who: Agent · Needs: P1.08, P3.08
In the code repo, apps/api/openapi.yaml, hand-maintained, with only the endpoints and parameters we document (api-surface.md):
- the error catalogue from P1.08, with an example per error
GET /v1/generation(P3.12), with the same rules: metadata only, no content- the
Retry-Afterheader on429/503/529(nox-ratelimit-*; see../architecture/api-errors.md) - streaming responses
- the
Idempotency-Keyextension
A contract test in the PR gates runs real requests against apps/api and validates the responses against the spec. The docs build fetches the published spec.
- Spec: decisions log, Developer docs site;
../product/api-surface.md; P1.08 - Done when: the contract test passes and fails on a deliberate mismatch, and the spec is published (YAML and JSON) for the docs build.
D.07 — API reference and Request Builder
Section titled “D.07 — API reference and Request Builder”Who: Agent · Needs: D.03, D.06
- Reference pages rendered from the spec: method and path, auth, a parameter table, request and response schemas, streaming, an example for each error, and generated code in curl, Python and TypeScript (reviewed by hand).
- Request Builder: pick an endpoint, model and options and get ready-to-run code in each language. It never sends a request. Its model list is a fixed list maintained in the docs, not fetched from staging (staging may carry test models).
- Downloads: the spec as YAML and JSON.
- Spec:
../product/api-docs-scope.mdsection 4 - Done when: every endpoint in the spec has a page, and every generated sample runs against staging unchanged except for the key.
D.08 — Guides and content
Section titled “D.08 — Guides and content”Who: Agent · Needs: D.03, P1.08
Every section in api-docs-scope.md section 2:
- Basics: quickstart (the same curl as the dashboard’s onboarding and Overview), authentication
- Money: credits and billing (wording rule), spend caps and key scoping
- Calling the API: errors, rate limits, idempotency and retries, streaming
- Policy: data and privacy (content is not saved by default; saving is opt-in, matching the terms)
- Compatibility notes: from the “Diverge” rows of
openrouter-api-comparison.md - Changelog and status
Draft the sections that are ready (scope section 3) early. Finish each one once its dependency is built.
Languages (decided 2026-11-07): English at launch; French and Swahili later, after launch. English is the source. Process accepted 2026-11-07; the fr and sw work and finding the two native reviewers are deferred until after launch. The process: the agent drafts fr and sw from the final English page, a native reader for each language reviews before launch, and the agent re-translates a page whenever the English changes. Never translated: code, URLs, parameter and field names, error codes and error messages, model names. A shared glossary of terms (credit, workspace, key, hold, rate limit) keeps wording consistent across pages. The credits wording rule applies in every language: no “wallet”, cash or refund language.
- Spec:
../product/api-docs-scope.mdsections 1–3 and 5; backlog #17 - Done when: every section has an English page, and no page uses money wording for credits.
D.09 — Verify and publish (launch gate)
Section titled “D.09 — Verify and publish (launch gate)”Who: You + agent · Needs: D.04–D.08, P9.08
- Samples: every guide sample is extracted and run against staging in CI.
- Links: checked (and per language once fr and sw exist).
- Status page link: added.
- Website copy: every “change one line” claim in
website-copy.mdhas a matching page. - You: read through and approve.
- Publish: before P10.02.
- Spec:
../product/api-docs-scope.md;../product/website-copy.md - Done when: the docs are live at
router.africa/docsand the sample run passes.
D.10 — Ask AI (nice to have)
Section titled “D.10 — Ask AI (nice to have)”Who: You + agent · Needs: D.04
An “Ask AI” panel that answers questions from the docs only, grounded in llms-full.txt, with links to the pages it used. It has running costs, so:
- a monthly cost cap
- a per-IP rate limit
- Turnstile
- no logging of questions beyond what abuse handling needs
You: choose the model and budget. This task does not block launch; ship it when the rest of the track is done.
- Spec: decisions log, Developer docs site
- Done when: it answers from the docs with citations, refuses off-topic questions, and stops at the cost cap.