fix(spec): converge root docs meta.json onto the declared page list (#11482)

[os-litant]

Fixes #11482

What

build-docs.ts §3 (// 3. Update root meta.json) built the ROOT
content/docs/references/meta.json — the sidebar's top-level category list —
by filtering on categoryZodFiles (the .zod.ts files found on disk), a
third, independent enumeration of "the pages of this category" alongside §2's
own meta.json and §2.5's card grid (both already keyed off
categoryMetaPages per #11260).

A category whose published pages all come from plain .ts files rather than
.zod.ts ones (the misc catch-all class — security/misc proves the shape
is real) has zero .zod.ts files while still publishing a page, a
meta.json and an index.mdx. The old filter would drop such a category
from the root sidebar even though §2 and §2.5 both fully generated it — a
folder complete on disk and unreachable from the nav.

§3 now reads categoryMetaPages, the same declared list §2.5 already reads,
via an extracted rootCategoryDirs (scripts/lib/root-meta.ts) — one answer
to "which categories exist," read three times, instead of three answers that
happened to agree today.

Measured — no live instance, byte-identical output

No category is in the latent state today (all 14 have zodFiles.size > 0),
so this was a latent defect with no observable effect. Verified directly:

• pnpm --filter @objectstack/spec gen:docs before and after the fix
  produces a content/docs/references/meta.json with the same sha256
  (41bb8932b11061fbc0bd6168b4087c5528ac75d41359be72db8bfd21b3106eef) and an
  empty git diff across content/docs/.
• pnpm --filter @objectstack/spec check:docs passes clean (229 generated
  files in sync).

Because the edge this fixes has no live instance, it cannot be pinned from
generated output in either direction — the same reasoning #11260's
category-index.test.ts gives for the card-grid fix. The rule is pinned
directly in scripts/root-meta.test.ts against the extracted
rootCategoryDirs, with the misc-shaped fixture that has no repo instance
(an all-misc category with zero .zod.ts files), plus the empty/sort/
real-14-category shapes.

Scope

packages/spec/scripts/build-docs.ts §3 only, its extracted
scripts/lib/root-meta.ts, the pin (scripts/root-meta.test.ts), and a
changeset. Not touched: #11601 (nested-item describe rendering — a different
defect class in the same file; that card is serialized behind this one and
was not addressed here).

Tests

All run scoped to @objectstack/spec under the shared verify lock,
HEAD 900d16b:

• pnpm --filter @objectstack/spec build — clean.
• pnpm --filter @objectstack/spec exec vitest run scripts/root-meta.test.ts scripts/category-index.test.ts scripts/root-index.test.ts — 3 files / 31 tests passed.
• pnpm --filter @objectstack/spec typecheck (tsc --noEmit + check:scripts-typecheck + check:test-typecheck) — clean.
• pnpm --filter @objectstack/spec check:docs — clean, byte-identical root meta.json (see Measured above).
• pnpm --filter @objectstack/spec exec vitest run (full package suite) — 427 test files passed (427), 11352 tests passed (11352).
• pnpm --filter @objectstack/spec run check:empty-state / check:liveness / check:strictness-ledger / check:variant-docs — all clean.
• npx eslint --no-inline-config --format json scoped to exactly the 3 changed TS files — 0 errors / 0 warnings across all 3; this repo's ESLint config enables no type-aware linting for any file (eslint.config.mjs, documented at its QUERY_OPTIONS_TEST_GLOBS comment), so this 3-file scope cannot move judgment on any untouched file.
• Repo-root gates named by node scripts/pm/dispatch-gates.mjs for this diff: check:changeset-gate-self-tests, check:merge-driver, check:objectui-changeset, check:published-files, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check-adr-0087-registration.mjs, check-changeset-no-major.mjs, check-empty-changeset.mjs, check-plugin-teardown-shape.mjs, docs-audit/check-affected-docs.mjs, docs-audit/check-drift-comment.mjs, release-rehearsal-clone.mjs --self-test — all clean.
• Convention-triggered (new test file added): check:query-options-erasure, check:engine-double-contract, check:cross-package-test-inputs, check:where-matcher, check:type-check-coverage (structural) — all clean.
• Not run locally: check-dev-prereqs.mjs (full 78-package pnpm build precondition) and check:type-check-debt --re-measure (same full-workspace-build precondition) — out of scope for a single scripts-layer file per the local-verification-scope discipline; CI's own build step covers both, and the new file is fully covered by the existing tsconfig.scripts.json program with 0 errors, so it cannot move either ledger.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 494279cb31f1d92adab959763085e19c923a8652 → packageMentionDocs.