Repository navigation
[finding] the 14 generated content/docs/references/*/index.mdx overviews carry no "do not edit" banner, while the 211 pages beside them do #14364
Description
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.
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
Activity
huangyiirene commentedon Sep 2, 2026
Triage:
bug·documentation·priority:p3·pm:queue·domain:spec· typeBug. Found by the full-backlog bare-card sweep — filed 03:14Z and never touched again, so everysince-anchored incremental sweep skipped it.domain:spec, notdomain:devx. The anchor is where the fix lands, and that ispackages/spec/scripts/build-docs.ts§2.5 — which the lane table assigns to spec (packages/spec/scripts/**). The 14 pages undercontent/docs/**are generated output; they are not edited by the fix, they are re-emitted by it.Census re-measured on
origin/main@f7d92d3, and it holds — with one arithmetic correction:.mdxundercontent/docs/references/AUTO-GENERATED — DO NOT EDITindex.mdxfilesThe 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
bugand not a nit.manageDir(DOCS_ROOT, …)claims the tree, soflush()deletes before rewriting; a hand edit is discarded with no gate red and no conflict, becausecheck:docsre-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 rootcontent/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_issuesis 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