Docs Site AsciiDoc-Parity Blueprint: Verified Findings (2026)

An external blueprint proposed four AsciiDoc-parity pillars for voxlang.org: richer transclusion, audit-driven banners, contract-backed tables, and workspace attributes. Checked against the live docs-astro/ tree on 2026-11-05, only transclusion and version derivation held up; both landed. Audit banners already exist (ledger-driven), and the proposed stability contract and reality-audit status fields do not exist. Phase 342 then moved the site to Astro 7 / Starlight 0.42, renders GitHub alerts as asides (starlight-github-alerts 0.5.0), and fails the build on broken internal links (starlight-links-validator 0.27.0).

Verdict by pillar

Pillar	Blueprint claim	Reality (2026-11-05)	Decision
1. Transclusion	Upgrade remark-vox-include.mjs with tags, ranges, dedent, ::include{}	Plugin existed, anchors only, no deps	Done: tags (tag::x[]), # leaders, multi-select, N..M ranges, dedent, exact names. ::include{}, // !hide, auto titles cut (no call sites).
2. Admonitions	Drive Banner.astro from docs-reality-audit/inventory.v1.json; add starlight-github-alerts	Banner already reads docs-freshness/ledger.v1.json; inventory has no status field; findings empty	Rejected banner rewrite (owned by docs-freshness Phase 32). GitHub alerts accepted — 24 docs use them. Done (Phase 342): rendered as Starlight asides by starlight-github-alerts 0.5.0.
3. Data tables	stability-matrix.v1.json + Content Layer file() loaders	Contract does not exist	Rejected; use the *.generated.md + ssot-drift pattern.
4. Attributes / xrefs	remark-vox-attributes, [email protected]	No {token} usage; validator needs Astro ≥7.2.10 / Starlight ≥0.42	llms.txt version now derived from root Cargo.toml (done). Token plugin rejected. Validator accepted. Done (Phase 342): starlight-links-validator 0.27.0 runs in every pnpm build on default (fatal) options; only .mdx page links and the documented 127.0.0.1:11434 probe URL are excluded.

Other corrections

• The live remark chain is remarkVoxInclude → remarkDocLinks; remarkStripTitleH1 and voxDiagram do not exist.
• .mdx is already first-class (Phase 323), so “keep everything .md” is not a constraint.
• The version SSOT is root Cargo.toml [workspace.package], not CITATION.cff.
• Namespace collision is real: vox-lang (crates.io; English-sentence → NASM compiler) and MrSmith33/vox (D-language compiler, BSL-1.0) both exist; llms.txt now disambiguates.

Follow-up

Phase 342 (DOCS-PARITY-02..04) is complete: Starlight 0.42 / Astro 7 upgrade, GitHub-alert rendering, build-time link validation, and the two remark-doc-links failures. The one deferred idea is resolving empty-label xref titles in remark-doc-links; it is not implemented.