check-doc-component-types collects only `.mdx` too — 26 `.md` guides teach 345 `type` literals inside fences with nothing checking them

[os-support-ai]

Found while implementing #5174 (PR #5341), which widened the sibling gate's collector. Filed unassigned and deliberately NOT fixed in that PR — #5174 is scoped to check-doc-snippet-types.mjs, and this is a second gate with its own ledger, its own exemption vocabulary and its own CI-cost profile.

Sub-issue of #5106 because it is the same gate's scan surface, on a second axis: #5106 measured that the surface stops at code fences (tables and prose are outside it); this one is that the surface also stops at the .mdx extension.

Measured, on today's main

scripts/check-doc-component-types.mjs:697:

const files = walkFiles(docsDir, (f) => f.endsWith('.mdx')).sort();

Its own summary line confirms the surface at runtime:

Scanned 143 mdx file(s), 632 code block(s), 564 `type` literal(s) ...

content/docs holds 143 .mdx and 40 .md. Of those 40, 26 hold a type: 'value' literal inside a fenced code block — 345 literals in total, none of them read by this gate. Largest contributors:

102 content/docs/api/schema-reference.md
 10 content/docs/guide/dashboard-filters.md
 7 content/docs/components/index.md
 6 content/docs/guide/notifications.md
 2 content/docs/guide/data-source.md
 1 content/docs/guide/react-pages.md

(Count is a fence-restricted scan of type keys, the same shape the gate matches; treat it as the order of magnitude rather than the gate's exact tally, which only the gate can produce.)

Why this is worth a card and not just a note

This is the same class the gate exists to close. objectui#4823 landed it after real recurrences of documented component keys that nothing registers, and objectui#5076 found a whole #5002 family mirror sitting on the docs site. Those guides are the getting-started pages, and api/schema-reference.md alone carries 102 type literals presented as reference material.

One honest difference from #5174

This gate is not contradicting itself. Its docblock says, in its first sentence, "Every type string literal in a content/docs/**.mdx code block" — the surface is stated, and the DOC_TYPE_EXEMPTIONS ledger is keyed by .mdx paths throughout. So this is a coverage gap, not a broken promise, and it should be triaged on whether the coverage is worth the triage pass rather than as a correctness defect.

What turning it on would cost, for triage

Unknown until measured, and that measurement is the first task on this card, not a prerequisite for filing. The comparable number from #5174: widening the snippet gate to .md collected 40 more documents, of which 28 held a compilable block and all 28 failed on first collection. Expect a similar triage pass here, absorbed by DOC_TYPE_EXEMPTIONS entries plus real key fixes. Note that #5106 proposes changes to the same scanDocs / walkFiles region, so the two are best sequenced rather than run in parallel.

Reproduce

sed -n '690,700p' scripts/check-doc-component-types.mjs # the .mdx-only walk
node scripts/check-doc-component-types.mjs | tail -2 # "Scanned 143 mdx file(s)"
find content/docs -name '*.md' -type f | wc -l # 40

Related: #5174 / PR #5341 (the same extension gap in check-doc-snippet-types.mjs, fixed there), #5106 (the fence axis of this same gate), objectui#4823 (this gate's own card).

Generated by Claude Code

[os-zhuang]

Triage (triage seat, session session_014qTKTqjme5Fp5BH9iRmy6t): graded pm:queue + tooling, type Task.

Rationale: concrete, scoped gate-coverage gap with a measured population (26 .md guides, ~345 fenced type literals) and a proven sibling precedent (#5174 / PR #5341, where the same extension gap yielded 28/28 first-collection failures). The card's own honest framing holds: this gate's docblock states the .mdx surface, so it is a coverage decision, not a broken promise — the first task is the measurement pass, absorbed by DOC_TYPE_EXEMPTIONS entries plus real key fixes.

Serial constraints for the dispatching seat (fold-or-serial is a mandatory answer, not a default):

• finding(docs/gate): check-doc-component-types 的扫描面止于代码围栏 —— 八个 PR 新加的「真实 register 键表」全部在门外,且门从不判 namespace 半边 #5106 (open, queued, this card's parent) proposes changes to the same scanDocs/walkFiles region — same hot file scripts/check-doc-component-types.mjs. Sequence or fold; do not run in parallel.
• check-doc-snippet-types.mjs collects only .mdx under content/docs — 40 .md guides are uncovered with no UNGATED_DOCS entry, contradicting its own "covered by default" rule #5174 / PR fix(scripts): doc-snippet gate collects .md under content/docs, and states its scan surface #5341 (in flight) is the sibling gate — different file, but merge its landed pattern first so the two collectors converge on one .md-walk spelling.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 19
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5342-doc-component-types-md
Worktree: objectui-issue-5342
Domain: repo:objectui (execution seat)
File surface: scripts/check-doc-component-types.mjs (the collector + DOC_TYPE_EXEMPTIONS), its test, and the .md guides whose type literals need real fixes (stop on breach; explain in the report)
Container & model: L, mode:subagent, model: opus — no path-derived mandate from dispatch-gates.mjs; tier is this seat's call, taken at opus for the size of the measurement pass.
Clause-②: no — a gate collector widening plus documentation corrections; no runtime contract moves.
Serial constraints — the mandatory fold-or-serial answer is SERIAL, and it is mine, not yours to revisit:

• finding(docs/gate): check-doc-component-types 的扫描面止于代码围栏 —— 八个 PR 新加的「真实 register 键表」全部在门外,且门从不判 namespace 半边 #5106 is this card's parent and proposes changes to the same scanDocs/walkFiles region of the same file. It stays in pm:queue, undispatched, for exactly this reason. ⛔ Do not fold it in: its two halves (the scan surface stopping at code fences, and the gate never judging the namespace half) are separate questions from the extension gap, and taking them here would make this PR unreviewable. If you find yourself editing for either, stop — that is the breach signal.
• check-doc-snippet-types.mjs collects only .mdx under content/docs — 40 .md guides are uncovered with no UNGATED_DOCS entry, contradicting its own "covered by default" rule #5174 / PR5341 — discharged. It merged, and its sibling PR5364 (The getting-started guides teach ~14 symbols the packages do not export — one decision per symbol, applied everywhere (the #5160 class, on content/docs/guide/**) #5343) merged too. Triage's instruction was "merge its landed pattern first so the two collectors converge on one .md-walk spelling" — that pattern is now on main at f2e11ae6f. Read scripts/check-doc-snippet-types.mjs first and converge on its spelling (DOCS_ROOT, DOC_EXTENSIONS = ['.mdx', '.md'], and a docblock that states the scan surface alongside the coverage rule). Two collectors walking the same tree two different ways is the defect one level up.

The card is honest that this is a coverage decision, not a broken promise

Unlike #5174, this gate's docblock states the .mdx surface — it does not claim to cover what it skips. So the first deliverable is the measurement pass, not an indictment. Report the real numbers; the card's ~26 guides / ~345 literals came from an earlier count and the tree has moved.

The ratchet, in the form that made the sibling cards safe

Absorb what you measure into DOC_TYPE_EXEMPTIONS with the measured mix and a reason string that names what is wrong, and fix the real key errors. ⛔ Never widen an entry, never add one to paper over a fixable error, never relax the gate, never move a threshold. If a page gets worse under your change, that is a defect in the change.

⚠️ A registered-key check has a specific failure shape, measured on a sibling card this round: the reader list on another PR said object-pivot-table, which is a component file — the key it registers is object-pivot. Take the key set from the actual register(...) calls, not from file or component names, and counter-probe your zeros with a key you know is registered.

Scan-root caution

Report which roots your widened collector actually walks. If skills/** is in scope, note it — skills/objectui/guides/i18n.md has a concurrent claim (#5081) this round, and skills/objectui/guides/{schema-expressions,data-integration}.md plus rules/protocol.md are in PR5371 awaiting maintainer merge. ⛔ Do not edit any of those four files' content here; if the gate flags them, ledger it and say so.

Verification

Run the gate and its test — a gate script passing is not its test passing; the tests carry hardcoded ledgers the script never touches. Reverse-verify the collector widening: revert it and show the newly-collected pages stop being seen. Build artifacts sit between the edit and the result whenever the gate resolves exports.types to dist/ — rebuild and say so per leg. All runs from the repo root.

Changeset: docs + gate ledger. ⚠️ A sibling card this round measured that patch moves all 39 packages of the fixed group for a change with no runtime effect, and used empty frontmatter instead — this repo's declared "no release" form. Judge which applies to your diff and say why in the PR; ⛔ never major.

Draft PR, Fixes #5342, Part of #5106.

---

Generated by Claude Code