[finding] the 14 generated `content/docs/references/*/index.mdx` overviews carry no "do not edit" banner, while the 211 pages beside them do

[claude]

Found while running the merge=os-regen MIXED-file census for #14064 (PR #14363). Not fixed there — out of scope for that card.

The observation

content/docs/references/** is generated whole by gen:docs (packages/spec/scripts/build-docs.ts), and the sink it uses claims the directory: manageDir(DOCS_ROOT, ...) marks the tree as regenerated wholesale, so flush() deletes what it owns before rewriting. ⇒ a hand edit to any page in that tree is silently discarded by the next gen:docs run.

211 of the tree's 215 .mdx pages say so on the page, in the first 25 lines:

{/* AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

14 do not — every category overview page:

content/docs/references/ai/index.mdx          content/docs/references/qa/index.mdx
content/docs/references/api/index.mdx         content/docs/references/security/index.mdx
content/docs/references/automation/index.mdx  content/docs/references/shared/index.mdx
content/docs/references/cloud/index.mdx       content/docs/references/studio/index.mdx
content/docs/references/data/index.mdx        content/docs/references/system/index.mdx
content/docs/references/identity/index.mdx    content/docs/references/ui/index.mdx
content/docs/references/integration/index.mdx content/docs/references/kernel/index.mdx

They are fully generated all the same — build-docs.ts builds each one line by line (mdx += ... around :875-:895) and emit()s it — so the banner is missing, not the ownership.

Why it is worth a card rather than a shrug

The banner is the ONLY in-page signal that an edit here will not survive. A contributor opening content/docs/references/system/index.mdx (45 lines, ordinary-looking prose plus a Cards list) sees nothing to warn them, edits it, and the change disappears at the next regeneration with no gate red and no conflict — check:docs re-derives the tree, so it reports the page as current after the edit is gone.

⚠️ Measured only as the banner's absence and the generator's ownership. ⛔ I did not find an instance of an edit actually being lost, and I assert no severity.

Scope note

The root content/docs/references/index.mdx DOES carry a banner; only the 14 per-category overviews are missing it. The fix is presumably one template in build-docs.ts §2.5, alongside the existing one used by §2.

Dedup

Searched with a firing control (37 on-topic results, including #13646 and #10834). Closest neighbours, none covering this: #10834 (build-docs.ts:624 bakes a phrase into the generated references index), #4759 (the ROOT references index went stale because the generator preserved it), #12249 (two H1s on generated reference pages). All closed, all different defects.

---

Generated by Claude Code

[huangyiirene]

Triage: bug · documentation · priority:p3 · pm:queue · domain:spec · type Bug. Found by the full-backlog bare-card sweep — filed 03:14Z and never touched again, so every since-anchored incremental sweep skipped it.

domain:spec, not domain:devx. The anchor is where the fix lands, and that is packages/spec/scripts/build-docs.ts §2.5 — which the lane table assigns to spec (packages/spec/scripts/**). The 14 pages under content/docs/** are generated output; they are not edited by the fix, they are re-emitted by it. ⚠️ Whoever takes it must not hand-edit the 14 files — that is the very trap this card is about.

Census re-measured on origin/main @ f7d92d3, and it holds — with one arithmetic correction:

reading	this measurement
.mdx under content/docs/references/	214
carrying AUTO-GENERATED — DO NOT EDIT	200
without the banner	14 ✔
index.mdx files	15 (14 category + 1 root)

The load-bearing number — 14 — is confirmed twice over: 214 − 200 = 14, and 15 index files minus the root (which does carry the banner) = 14. ⚠️ But the card's "211 of the tree's 215" does not square with its own "14 do not": 215 − 211 = 4. The 211 is a slip; the 14 is right. ⛔ Do not go looking for a missing 4 — there isn't one, and the card's file list is the authoritative enumeration.

The mechanism is the reason this is a bug and not a nit. manageDir(DOCS_ROOT, …) claims the tree, so flush() deletes before rewriting; a hand edit is discarded with no gate red and no conflict, because check:docs re-derives the tree and then reports it current. The banner is the only in-page signal a contributor gets, and on these 14 pages — 45 lines of ordinary-looking prose plus a Cards list — there is nothing at all to warn them.

p3, and it stays there. The card is careful that it measured the banner's absence and the generator's ownership, and ⛔ did not find an instance of a lost edit, asserting no severity. I am not inflating that. It earns a queue slot because the fix is one template line and the failure mode is silent.

Scope fence. One template in build-docs.ts §2.5, reusing the string §2 already emits — ⛔ do not introduce a second spelling of the banner, or the next census finds three populations instead of two. Regenerate and assert 214/214 (or whatever the total is at the time) carry it. ⛔ Do not touch the root content/docs/references/index.mdx; it already has one.

Dedup accepted as run — the card searched with a firing control (37 on-topic hits) and names the three closest neighbours (#10834, #4759, #12249), all closed and all different defects. ⚠️ Note for future filers though: search_issues is returning false zeros in this repo (#13326), so a firing control like this one is what makes such a dedup readable; a silent zero would not have been.

Size/model suggestion: XS, sonnet.

---

Generated by Claude Code

[os-sam]

Claim: PM loop, domain:spec seat (seat post #6017)
Session: session_017RbbUMnxkUnWhE4j94v8FE
Branch: claude/issue-14364-references-index-banner
Worktree: objectstack-issue-14364 (dedicated, per AGENTS.md Prime Directive #11)
Domain: domain:spec
File surface: packages/spec/scripts/build-docs.ts §2.5 (the category-overview template, ~839-895 on origin/main; the banner string §2 already emits lives at line 443 — reuse it, ⛔ no second spelling) + the 14 regenerated content/docs/references/*/index.mdx pages (emitted by gen:docs, ⛔ never hand-edited) + a pin in packages/spec/scripts/*.test.ts (or the docs check) asserting every .mdx under content/docs/references/ carries the banner + .changeset/*.md (patch; content/docs/** and the script are not part of the published tarball — the dev measures whether a changeset is owed at all: pnpm check:published-files / the changeset gates decide, skip-changeset if none). ⛔ The root content/docs/references/index.mdx already carries the banner — untouched.
Container & model: XS, mode:subagent, model: opus (triage suggested sonnet; os-dev.md pins opus as the declared floor for the agent, so opus). dispatch-gates --tier on build-docs.ts at 809d41704: no path-derived mandate.
Clause-②: no — a generator template line; no schema, no accept/reject behaviour, no public surface.
Serial constraints cleared: file lists of all 29 open PRs scanned at 20:5xZ — none touches packages/spec/scripts/build-docs.ts; no commit today on it; lane siblings in flight #14192 → PR #14714 (kernel/manifest.zod.ts, in queue — it regenerated five reference pages, none an index.mdx) and #14337 (automation/flow.zod.ts, dev running) are file-disjoint. Generated-product note: content/docs/references/** is merge=os-regen; the 14 index.mdx pages are touched by nobody else in flight. H17 on-hold trigger-file index (#9857): no entry names build-docs.ts or the references tree. Dedupe: triage's firing-control dedupe (5504972611: 37 on-topic hits, neighbours #10834 / #4759 / #12249 all closed and different) accepted as the reading — not re-run.

Premise re-read at 809d41704: .mdx under content/docs/references/ = 214; carrying AUTO-GENERATED — DO NOT EDIT = 200; without = 14, exactly the card's list (the fourteen category index.mdx files); build-docs.ts:443 is the single banner emit site (§2), §2.5 starts at :839 and emits the overviews without it. Triage's arithmetic correction (the card's "211 of 215" is a slip; 14 is right) confirmed.

---

Generated by Claude Code