Gaps — docs:build and page render failures
Raw observations about what the docs:build check does and does not prove, recorded where they were noticed and deliberately left unprocessed. Nothing here is a proposal, a decision, or a plan. The check belongs to spec 003; it was not spec 013's to change, and inventing a fix while passing through would have been scope creep.
From spec 013 — docs previews (2026-08-13)
Found by breaking it. research.md F4.
docs:build exits 0 on a failed server render
VitePress passes Markdown through Vue, so an interpolation in inline code is evaluated as a Vue expression. Fenced code blocks are escaped; inline code spans are not. A research.md draft quoted a GitHub Actions expression inline, Vue evaluated it against an undefined object, and the page's server-side render threw:
TypeError: Cannot read properties of undefined (reading 'event_name')The build printed that error, emitted the page, and exited 0.
Probed the same day with a throwaway docs/tmp-ssr-probe.md containing one interpolated expression, built, then deleted:
| Observation | Result |
|---|---|
pnpm docs:build exit code | 0 |
TypeError in its output | yes |
| Page emitted | yes, with a failed server render |
The two failure modes are not equivalent
Writing the note above produced the other one. With the braces still in inline code, Vue compiled the expression to _ctx.… and Rollup rejected it as Unexpected character '…' — a genuinely red build.
| Failure mode | Example | docs:build |
|---|---|---|
| Vue compile error | an expression that is not valid JavaScript | exit 1 — caught |
| Vue runtime SSR error | valid JavaScript over an undefined object | exit 0 — missed |
Only the second is invisible, and the second is the likelier one when documenting CI: github.event_name is perfectly valid JavaScript that simply has nothing to evaluate against.
What this means, stated without deciding anything
Spec 003's docs:build check proves the site builds. It does not prove the pages render. A green pipeline is not evidence that the documentation is readable.
Spec 013 makes this less costly without addressing it: previews publish every branch, so a broken page is now visible to anyone who opens the link — which is how this was caught. That is mitigation by accident, not a fix.
The authoring workaround is <span v-pre> around inline code containing braces, or keeping such examples inside fenced blocks. That is a convention, not a guard: nothing enforces it.