v5.47.0 6 June 2026 Fix Improvement

SpeyDocs Integrity — Honest 404s, Spec Taxonomy Closure & Generated llms Files

Why This Matters

The documentation site is part of the trust surface. A docs site that returns success responses for pages that do not exist, a specification that disagrees with itself about its own vocabulary, and hand-maintained reference artifacts that silently drift all erode the same claim the kernel exists to make: that what SpeyBooks states about itself is derived, not asserted. This release applies the derivation discipline to the documentation surface itself. Routes are honest, the taxonomy is closed by assertion, and the machine-readable reference files are generated from the same specification that produces the HTML pages.

Honest Routing

  • Nonexistent documentation URLs now return 404 A fallback in the web server configuration caused every nonexistent path on docs.speybooks.com to return the site homepage with a success status. Dead links were indistinguishable from live ones, for readers and crawlers alike. The fallback chains now terminate honestly, and a dedicated 404 page in the documentation’s own visual language tells readers the route does not appear in the specification and offers the way back.

  • Security headers restored on asset responses A web server configuration subtlety meant documentation asset responses had been served without inherited security headers. The affected response classes now carry the full header set.

Specification Taxonomy Closure

  • Declared tags are now derived from operations The OpenAPI specification’s tag declarations were a hand-maintained list that had drifted through two taxonomy migrations: four declarations no operation used, six operation tags no declaration covered, and one object document silently dropped as a consequence. The generator now derives the declared set from the tags operations actually use, sorted for byte-stable output. Admin Bug Reports, API Request Log, Health, Migration, Stripe Webhooks, and Transparency gained their declarations; the four fossils were removed; the orphaned object document was restored.

  • Taxonomy closure asserted at generation The generator now fails loudly if any used tag is ungrouped, any group carries a tag no operation uses, or any used tag lacks a description. A specification with an open taxonomy cannot be generated (enforcement: executable closure assertions in the generation pipeline; a violation exits non-zero and halts every downstream deploy).

Generated llms Files

  • llms.txt and llms-full.txt are now built from the specification Both machine-readable reference files were previously static artifacts, hand-written in February and untouched since. Their URL scheme had drifted from the live site, and the previously soft 404 behaviour had masked every dead link they contained. Both are now generated at build time from the same intermediate representation that produces the HTML pages: the index derives every URL from the route registry, and the full reference inlines all 198 endpoints with request and response examples from the specification’s curated documentation fields.

  • Legacy static artifacts removed The February files have been deleted. Captured example credentials discovered in the legacy full-reference file were rotated and scrubbed before removal; generated output sources its examples exclusively from the specification, so live captures cannot recur in these artifacts.

Deployment Verification

  • Six fail-closed gates on the documentation pipeline The documentation deploy now runs a sequence of operational controls: specification validity and taxonomy agreement, parser closure, build, output integrity (including a structural comparison of rendered endpoint pages against the specification’s endpoint count, llms freshness against the same derivation, and link-origin verification), ownership assertion, and live verification of the deployed site, including a permanent probe asserting that nonexistent paths return honest 404s with the branded page. Any failed check halts the deploy.

Operational Impact

  • Nonexistent documentation URLs return 404 (previously 200 with the homepage body)
  • Rendered endpoint pages compared against the specification on every deploy: 198 = 198
  • Declared tag set equals the operation-used set, asserted at generation: 31 = 31
  • All 18 object documents now attach to their resources (previously 17 of 18)
  • llms reference regenerated on every build, with endpoint count and link origin gated
  • Zero hand-maintained machine-readable reference artifacts remain on the documentation site

Files Changed

Backend (API):

  • scripts/generate-openapi.ts — declared tags derived from operations; taxonomy closure assertions; tag group fossils removed

Documentation site:

  • src/pages/404.astro — new branded 404 page
  • src/pages/llms.txt.ts — new generated index route
  • src/pages/llms-full.txt.ts — new generated full-reference route
  • deploy.sh — v2.2, six fail-closed gates
  • public/llms.txt, public/llms-full.txt — removed (replaced by generated routes)
  • Web server configuration — honest 404 fallbacks; asset response header restoration

Known Issues

  • The documentation build writes in place, leaving a brief window during each deploy where the live site is mid-build. Acceptable at current traffic; an atomic publish step is recorded as future hardening.

The documentation surface now holds itself to the same standard as the ledger it describes; next, the billing lifecycle work ahead of beta.