[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