[finding] build-docs.ts §3 builds the ROOT references meta.json from a third enumeration — a category with no `.zod.ts` would be unroutable

[os-steve]

Found while fixing #11260 (the security card grid omitting misc). Same class, different code path, no instance in the tree today — filing rather than folding, per that card's scope.

What #11260 fixed, and what it did not

#11260's defect was that a category's meta.json and its index.mdx card grid were built from two different enumerations of "the pages of this category", and the misc catch-all — which has no .zod.ts behind it by definition — existed in only one of them. That is fixed: §2.5 now iterates the list §2 declared.

build-docs.ts §3 (// 3. Update root meta.json, ~line 940 post-fix) builds the root content/docs/references/meta.json — the list of categories in the sidebar — from a third enumeration, the one #11260 just moved the grid off:

const categoryDirs = Object.keys(CATEGORIES)
 .filter(cat => {
 const zodFiles = categoryZodFiles.get(cat);
 return zodFiles && zodFiles.size > 0;
 })
 .sort();

The latent shape

A category whose published schemas all come from plain .ts files rather than .zod.ts ones would have zodFiles.size === 0 while still publishing pages — everything lands in the misc catch-all. security/ already proves plain-.ts declarations reach that bucket (it is why security/misc exists at all); it simply also has four .zod.ts files, so it never trips this.

For such a category the generator would produce:

• §2 — its pages and its meta.json (built from the emitted page map): written;
• §2.5 — its index.mdx (post-docs(references): the generated security category index omits misc, the one page with no .zod.ts behind it #11260, keyed off that same declared list): written;
• §3 — its entry in the root meta.json: omitted, because it has no .zod.ts.

Result: a category folder that is fully generated and completely absent from the sidebar. Note the direction — before #11260 this was half-hidden by §2.5 skipping the index.mdx too, so the folder was merely broken rather than orphaned; now §3 is the only remaining enumeration keyed off source files instead of published pages.

Measured

No category is in this state today. All 14 have zodFiles.size > 0, so the root meta.json is byte-identical whichever enumeration is used, and #11260's PR changes nothing here:

ai 11 · api 29 · automation 13 · cloud 11 · data 30 · identity 5 · integration 1
kernel 32 · qa 1 · security 4 · shared 13 · studio 3 · system 36 · ui 18 (.zod.ts files)

This is a latent defect — an observation about a path that has no live instance — hence finding and not pm:queue.

Suggested shape (not a decision)

Same fix as #11260's, one level up: filter on the categories that published a meta.json (categoryMetaPages, the map #11260 introduced) rather than on .zod.ts counts. That would leave build-docs.ts with one answer to "which categories/pages exist" — the pages the run emitted — instead of the three it had.

Worth confirming in the same pass whether sourcePathToDocsRoute and the root index (§2.6, which enumerates from categoryPageSchemas) agree with that answer; §2.6 looks correct already.

Refs

#11260 (where this was found; fixed the category-level half) · #10834 (separate open finding on the same generated index) · packages/spec/scripts/build-docs.ts