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
Activity
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.⚠️ 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 .mdxundercontent/docs/references/214 carrying AUTO-GENERATED — DO NOT EDIT200 without the banner 14 ✔ index.mdxfiles15 (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
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
Found while running the
merge=os-regenMIXED-file census for #14064 (PR #14363). Not fixed there — out of scope for that card.The observation
content/docs/references/**is generated whole bygen:docs(packages/spec/scripts/build-docs.ts), and the sink it uses claims the directory:manageDir(DOCS_ROOT, ...)marks the tree as regenerated wholesale, soflush()deletes what it owns before rewriting. ⇒ a hand edit to any page in that tree is silently discarded by the nextgen:docsrun.211 of the tree's 215
.mdxpages say so on the page, in the first 25 lines:14 do not — every category overview page:
They are fully generated all the same —
build-docs.tsbuilds each one line by line (mdx += ...around:875-:895) andemit()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:docsre-derives the tree, so it reports the page as current after the edit is gone.Scope note
The root
content/docs/references/index.mdxDOES carry a banner; only the 14 per-category overviews are missing it. The fix is presumably one template inbuild-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:624bakes 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