fix(prerender): emit per-section /docs/<slug>.md mirrors (fix llms.txt 404)

[mastermanas805]

Bug-3 (bug-hunt follow-up, 2026-06-06). The agent-facing troubleshooting guide is linked from llms.txt as https://instanode.dev/docs/troubleshooting-deploys.md, but that nested per-section .md route returns 404 (verified live). Only /docs.md (the concatenated mirror) and the legal /docs/public/*.md statics resolved — the main docs sections had no per-section .md mirror.

Live evidence (before)

/docs/troubleshooting-deploys.md  → 404   ← the broken contract URL
/docs.md                          → 200   (concatenated mirror)
/docs/public/security.md          → 200   (legal per-section static — precedent that nested docs .md DO serve)

Fix (canonical, lower-risk)

Step 6b of emitMarkdownRoutes now emits /docs/<slug>.md for every .content/docs section, mirroring the existing blog/use-case per-slug .md pattern and the legal /docs/public/*.md precedent (GH Pages serves the nested file directly). Each mirror is the standalone section: an H1 from the frontmatter title + the body with YAML frontmatter stripped — so an agent can fetch ONE section instead of the whole concatenated doc.

The llms.txt reference now 200s as-is, so no public/llms.txt edit and no content-repo llms.txt change are needed — the URL was always correct; the route was the thing missing. (Chose making the route resolve over rewriting the URL: it's the canonical fix, keeps the contract intact, and matches the legal-docs precedent.)

writeRouteMd() gains an includeInAggregate flag (default true); the per-section docs pass false so /llms-full.txt isn't bloated with duplicate docs content (each section already appears in the /docs.md aggregate entry). Verified the aggregate carries /docs.md once and zero per-section duplicates.

Tests — fail-before / pass-after (proven)

src/prerender.test.ts — three source guards pin the emission loop, the includeInAggregate=false aggregate exclusion, and the title+body mirror shape. Proven by stashing the prerender.mjs change (all 3 fail against old code). The guards are deterministic (no filesystem/build dependency) so they run identically under npm run gate and the build-less coverage job — full patch coverage. The existing llmsContract.test.ts keeps troubleshooting-deploys pinned in public/llms.txt, so URL and contract stay in lock-step.

Full npm run gate GREEN (tsc + build + prerender + 1133 vitest). Build locally produces dist/docs/troubleshooting-deploys.md (5527 bytes, standalone H1). Will live-verify the URL 200s after deploy.

🤖 Generated with Claude Code

[github-actions]

size-limit report 📦

Path	Size
dist/assets/index-BZLn7_NF.js	162.22 KB (0%)
dist/assets/index-BsJUZYRr.css	6.13 KB (0%)