fix(spec): emit the "do not edit" banner on the 14 generated category overviews

[claude]

Fixes #14364

The 14 generated content/docs/references/CATEGORY/index.mdx overview pages carried no
"do not edit" banner, while the other 200 pages in the same generated tree did. The tree is
claimed by manageDir(DOCS_ROOT, ...), so flush() deletes what it owns before rewriting: a
hand edit to a page without the banner is discarded by the next gen:docs run with no gate
red and no merge conflict — check:docs re-derives the tree and then reports it current. The
banner is the only in-page warning a contributor gets before spending an afternoon on a page
that cannot keep their words.

What changed

One template, one spelling of the banner. packages/spec/scripts/build-docs.ts §2.5 — the
per-category overview emitter — now appends the banner right after the frontmatter, exactly
where §2 puts it on every schema page. The string it appends is the one §2 already emitted,
lifted into a single exported constant AUTO_GENERATED_BANNER in
packages/spec/scripts/lib/generated-output.ts (the in-page half of manageDir()'s claim,
next to the claim itself). §2.6's root-index emitter in scripts/lib/root-index.ts carried a
second byte-identical copy of the same literal; it now reads the constant too, so the
generator holds one spelling rather than three. git grep -c "AUTO-GENERATED — DO NOT EDIT" packages/spec/scripts reports the literal once, in generated-output.ts.

The 14 pages are regenerated output, not hand edits. Running pnpm --filter @objectstack/spec gen:docs on this branch reproduces the committed tree byte for byte
(git status --porcelain empty afterwards). That same empty diff is the proof the shared
constant is byte-identical to both literals it replaced: the other 200 schema pages and the
root content/docs/references/index.mdx are untouched — the root index blob is
4761aa1d2bc1c9362e36726433fbab56b16f7353 on origin/main and on this branch alike.

A pin that asks the question of the tree, not of a template.
packages/spec/scripts/references-banner.test.ts walks every .mdx under
content/docs/references/ and requires the banner in its first 25 lines. Nothing was red
before this change because no check had ever asked the question of the tree as a whole; each
template was only ever read against itself. A future template that forgets the line — a new
category shape, a new page kind, a refactor that drops the constant from one call site — now
lands as a red on the first regeneration instead of as a second silent population of pages.
Two guards keep it from degrading into a vacuous green: a floor on the page count (so a glob
that stops matching reads as broken, not as "all zero pages pass") and an assertion that the
banner constant still says something (so emptying it cannot make every page trivially contain
it). The banner text is imported, never re-typed.

Census

	pages carrying the banner
origin/main	200 of 214
this branch	214 of 214

The 14 were exactly the per-category overviews (ai, api, automation, cloud, data,
identity, integration, kernel, qa, security, shared, studio, system, ui).

Verification

All runs under scripts/pm/os-verify-lock.sh, exit codes captured before any pipe, on
commit 3e76dd6ca.

• pnpm --filter @objectstack/spec gen:docs then git status --porcelain — empty. Generator
  output reproduces the commit byte for byte.
• pnpm --filter @objectstack/spec check:docs — 229 generated files in sync with packages/spec.
• pnpm --filter @objectstack/spec check:generated — All 15 generated artifacts are up to date.
• pnpm --filter @objectstack/spec check:scripts-typecheck — clean. tsc --listFiles confirms
  the program actually reads all four edited files, the new test included (1 hit each), so
  this is a measurement and not a silent skip.
• vitest run scripts/references-banner.test.ts scripts/root-index.test.ts scripts/category-index.test.ts scripts/root-meta.test.ts scripts/check-generated-ledger.test.ts scripts/schema-tree-freshness.test.ts — 6 files, 48 tests passed. The sibling suites are the
  ones that name the edited generator libraries.
• pnpm check:nul-bytes — OK (scanned 8038 text files ... no raw ASCII control bytes).
• pnpm check:doc-authoring — clean on all four legs.
• pnpm check:published-files / pnpm check:changeset-gate-self-tests — green.
• Reverse verification: the mdx += AUTO_GENERATED_BANNER; line was deleted from §2.5 on disk
  and the mutation proven there before anything was measured (statement count 1 to 0, injected
  marker count 1, blob d59f2e1fe to eabbcb8c1). Regenerating from the mutated generator
  stripped the banner from exactly 14 of 214 pages and the pin went RED with
  AssertionError: 14 of 214 generated reference page(s) carry no "do not edit" banner in their first 25 lines (exit 1). Restoring with git checkout HEAD -- ... — pinned to HEAD, not a
  bare checkout, so the index could not hand back the mutation — reproduced the HEAD blob
  d59f2e1fe exactly, and after regeneration git diff HEAD and git status --porcelain were
  both empty; the pin returned to 3 of 3 green. The mutation script carried a trap ... EXIT INT TERM restoring by absolute path, but the blob comparison is the proof, not the trap.
• pnpm lint (eslint . --no-inline-config, the whole repo, no narrowing) — exit 0, no findings.
• Also green: check:doc-frontmatter, check:doc-route-spelling, check:docs-section-name,
  check:section-landing-index, docs-audit/check-affected-docs, docs-audit/check-drift-comment,
  check:doc-anchors, check:docs-single-h1, check:docs-redirects, check:docs-audit-scope,
  check:page-declaration-shape, check:quick-reference-counts, check:cross-package-test-inputs,
  check:comment-mask-adoption, check:keyed-text-bounds, check:test-source-alias,
  check:type-check-coverage, check:role-word, check:pm-dispatch-gates, check:merge-driver,
  check:published-readme-links, check:corpus-claim-drift.
• NOT MEASURED locally, both by the gate's own declaration and left to CI:
  check-test-completeness (exit 3 — needs a saved turbo run test log) and check:type-check-debt
  (exit 3, PREREQUISITE NOT MET — needs the whole workspace build closure). Neither is a finding.
  The remainder of the derived family runs on CI.

Why skip-changeset

Nothing in this PR reaches a published tarball, so it declares no release. packages/spec
ships files: ["dist","json-schema","liveness","prompts","llms.txt","README.md", "src/**/*.zod.ts","CHANGELOG.md","api-surface","spec-changes.json"] — scripts/ is not in
that whitelist, and pnpm check:published-files independently reports that the 69 publishable
packages "admit no test, test-harness config or build script". content/ sits at the repo
root, outside every pnpm-workspace.yaml package glob, so it cannot be packed by any package.
The label is applied to this PR with that reason.

🤖 Generated with Claude Code

https://claude.ai/code/session_017RbbUMnxkUnWhE4j94v8FE

---

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 4d0d9445a8ed0240e7ca6a393bbe7f4c637e6bd6 → packageMentionDocs.