Skip to content

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.


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.txt and a .md version 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.md exists with every feature marked, and api-docs-scope.md section 4 is updated with anything new.

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.

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.md section 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 .md version of every docs page at /docs/<page>.md
  • an llms.txt index
  • an llms-full.txt with 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.md section 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.

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-After header on 429 / 503 / 529 (no x-ratelimit-*; see ../architecture/api-errors.md)
  • streaming responses
  • the Idempotency-Key extension

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.md section 4
  • Done when: every endpoint in the spec has a page, and every generated sample runs against staging unchanged except for the key.

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.md sections 1–3 and 5; backlog #17
  • Done when: every section has an English page, and no page uses money wording for credits.

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.md has 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/docs and the sample run passes.

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.