Found while implementing #10738 (a gate holding hand-kept section landing indexes to their meta.json). Out of scope there: that gate only holds pages carrying a ## What's in this module heading, and the generated content/docs/references/*/index.mdx pages carry none. Filing rather than fixing — packages/** is claimed this round by #10921.
Measured on origin/main @ 98ea3443f
content/docs/references/security/ ships five pages. Its meta.json declares all five. Its index.mdx grid cards four:
$ cat content/docs/references/security/meta.json
{ "title": "Security Protocol", "pages": ["explain", "misc", "permission", "rls", "sharing"] }
$ grep -o 'href="/docs/references/security/[a-z-]*"' content/docs/references/security/index.mdx
href="/docs/references/security/explain"
href="/docs/references/security/permission"
href="/docs/references/security/rls"
href="/docs/references/security/sharing"
$ ls content/docs/references/security/misc.mdx
content/docs/references/security/misc.mdx
So /docs/references/security/misc exists, is generated, and is routed in the sidebar — but a reader on the category overview cannot reach it.
Swept across all 14 references/* categories: security is the only one whose meta.json carries a misc entry, and the only one affected. Every other category's grid matches its meta.json exactly.
Mechanism
Both files come out of the same generator run, packages/spec/scripts/build-docs.ts (gen:docs), from two different code paths that disagree about the misc catch-all.
The card emitter (~line 806) iterates zodFiles — page names derived from .zod.ts modules:
Array.from(zodFiles).sort().forEach(zodFile=>{// ... "This aligns the index with `meta.json`, which already lists only generated pages."if(!wasEmitted(path.join(DOCS_ROOT,category,`${zodFile}.mdx`)))return;misc is the catch-all bucket, and the file itself says twice that it has no module behind it (~line 233, "no file behind it (the misc catch-all bucket)"; ~line 409, "the misc catch-all has no file behind it"). So misc is never in zodFiles, the loop never considers it, and the wasEmitted guard — which is what the comment leans on — never runs for it. The meta.json builder (~line 790, via SECTION_GROUPS / the flat list at ~line 569) takes a different route and does include it.
The comment's claim "This aligns the index with meta.json" is therefore false for exactly this bucket, and it is the kind of false that reads as verified.
Suggested shape (not a decision)
Card the pages meta.json actually declares rather than re-deriving from zodFiles, keeping the wasEmitted guard so an undelivered page still cannot be carded. That makes the comment's stated invariant true by construction instead of by coincidence, and closes the whole class rather than special-casing misc.
Worth checking in the same pass whether a category that is allmisc would emit an empty grid.
Refs
#10738 (where this was found) · #10834 (open finding on a different defect in the same generated index) · packages/spec/scripts/build-docs.ts
Found while implementing #10738 (a gate holding hand-kept section landing indexes to their
meta.json). Out of scope there: that gate only holds pages carrying a## What's in this moduleheading, and the generatedcontent/docs/references/*/index.mdxpages carry none. Filing rather than fixing —packages/**is claimed this round by #10921.Measured on
origin/main@98ea3443fcontent/docs/references/security/ships five pages. Itsmeta.jsondeclares all five. Itsindex.mdxgrid cards four:So
/docs/references/security/miscexists, is generated, and is routed in the sidebar — but a reader on the category overview cannot reach it.Swept across all 14
references/*categories:securityis the only one whosemeta.jsoncarries amiscentry, and the only one affected. Every other category's grid matches itsmeta.jsonexactly.Mechanism
Both files come out of the same generator run,
packages/spec/scripts/build-docs.ts(gen:docs), from two different code paths that disagree about themisccatch-all.The card emitter (~line 806) iterates
zodFiles— page names derived from.zod.tsmodules:miscis the catch-all bucket, and the file itself says twice that it has no module behind it (~line 233, "no file behind it (themisccatch-all bucket)"; ~line 409, "themisccatch-all has no file behind it"). Somiscis never inzodFiles, the loop never considers it, and thewasEmittedguard — which is what the comment leans on — never runs for it. Themeta.jsonbuilder (~line 790, viaSECTION_GROUPS/ the flat list at ~line 569) takes a different route and does include it.The comment's claim "This aligns the index with
meta.json" is therefore false for exactly this bucket, and it is the kind of false that reads as verified.Suggested shape (not a decision)
Card the pages
meta.jsonactually declares rather than re-deriving fromzodFiles, keeping thewasEmittedguard so an undelivered page still cannot be carded. That makes the comment's stated invariant true by construction instead of by coincidence, and closes the whole class rather than special-casingmisc.Worth checking in the same pass whether a category that is all
miscwould emit an empty grid.Refs
#10738 (where this was found) · #10834 (open
findingon a different defect in the same generated index) ·packages/spec/scripts/build-docs.ts