Render API overview and operation pages, and keep every old URL working

[matthewmr-eqty]

Review focus

runtime/routes/docs.astro changes for every site: a site without an openapi: page builds the same 1,771 pages as before. Read runtime/openapi/OperationPage.astro first, then routes/docs.astro and routes/openapi-file.ts. eq-tabs.ts is a separate keyboard fix that affects every docs tab strip, not only API pages.

Need

Customers reading guardian's APIs need each operation's method, path, samples, parameters and responses on its own page, and the links they already hold, including tag pages, must still land somewhere useful.

Problem

The new design drops tag pages, the downloadable file must be the service team's own bytes, and statically rendered tabs loaded with no tab stop, so keyboard users could not reach the cURL and fetch samples.

Change

Overview and operation pages render only from the model, in Equality's Badge, Tabs, TableContainer and CodeFence, with native <details> until Equality ships an Accordion. Old tag URLs redirect to the overview; the committed file is served byte for byte at <page>/openapi.json or .yaml. The demo renders the Swagger Petstore (pinned, served byte for byte) so CI exercises the whole path; it stays out of llms.txt. The README gains an "API reference" section and the design-system skill a name-table row.

Evidence

Built from the real Integrity file: overview, 35 operations, 10 tag redirects, served JSON byte-identical; a YAML source served byte-identical as .yaml. Demo build: 1,794 pages, including Petstore's 19 operations and three tag redirects; the served .yaml is identical to upstream; OAuth and API-key security render per operation; a missing file fails the build naming the page. Browser (Chromium): sidebar tag groups with method badges, right rail, tabs by click and keyboard, tag redirect. Four live astro dev cases pass. Lint, format check, build and 155 docs tests pass.

Not covered

The visual design pass is next; the pages use the plan's draft anatomy. Parameter enums and defaults are not shown yet, and samples keep {petId}-style placeholders and skip non-JSON bodies. noIndex pages are still indexed by Pagefind on main, so the example API appears in search. Only Chromium was checked; browser tests are not in CI.

Flow

/reference/<svc>/api-reference/
   ├─ index.html                 OverviewPage (model)
   ├─ operations/<slug>/         OperationPage (model + operation)
   ├─ operations/tags/<tag>/  ─▶ redirect to the overview
   └─ openapi.json | .yaml       the committed file, byte for byte