capy-bearer/docs/work/documentation-route-repair.md

Documentation route repair

Evidence, 2026-09-30

The public documentation index linked to seven pages that returned nginx 404 responses. All six handler pages failed. The request-context how-to page also failed. The generated page files existed.

The production worker found an api|type|guide category allowlist in CT100 nginx. Development nginx already accepted safe category and slug segments. The production worker replaced the allowlist with that generic route and reloaded nginx after nginx -t passed. No compiler or application deployment was needed.

The runtime configuration and rollback are recorded in /root/docs/capy-bearer.md. The private coordination task is 2026/09/f977721c9c056fc60f68e86921b88246.

Acceptance

• Before the repair, the HTTP checker reported all seven failing routes.
• After the repair, all 274 documentation-index links returned 200.
• An independent recursive documentation crawl passed.
• The reported RENDER page returned 200 and contained its handler signature.
• Unknown handler and unknown category routes still returned 404.
• The stylesheet and project information page returned 200.
• Six offline HTTP-checker tests and four documentation-generator tests passed.
• Shell syntax and git diff --check passed.

scripts/check_capy_doc_links.py accepts the public site origin through --base-url. It checks same-origin rendered documentation links, including links from detail pages. It skips executable example routes. Requests run sequentially with a timeout, a page bound, and a short delay.

Run public acceptance with the project-home origin from the README:

timeout 240 python3 scripts/check_capy_doc_links.py --base-url "$SITE_ORIGIN" --timeout 5

The existing reference test runs the checker self-tests without network access. Public acceptance remains an explicit operator command. This change adds no scheduled work.