docs(guides,tooling): clear four .md pages off the doc-snippet ledger (#5174 batch 2)

[yinlianghui-tw]

Part of #5174 — batch 2. The card stays open: 5 .md guide entries remain after this.

What this does

Walks four pages off UNGATED_DOCS in scripts/check-doc-snippet-types.mjs, clearing the 89 diagnostics they were carrying.

page	diagnostics cleared	how
content/docs/guide/plugins.md	20	10 fragments declared, 2 blocks already compiled
content/docs/guide/building-crud-app.md	21	7 fragments, 2 blocks fixed, 2 already compiled
content/docs/rfcs/0001-clipboard-paste.md	23	7 fragments
content/docs/guide/architecture.md	25	10 fragments, 2 blocks fixed
total	89	34 fragments · 8 compiling (4 of them after an edit)

Ledger entries 53 → 49. Covered documents 169 → 173. 42 blocks newly under the gate.

Every page reached zero the two honest routes only — a block that should compile made self-contained against the built dist/, or a FRAGMENT_MARKER with a written measured reason for one that genuinely cannot. There is no third route in this diff.

Three real documented-API defects the ledger was hiding

These are why covering guide/architecture and building-crud-app was worth doing rather than declaring them wholesale:

1. building-crud-app.md — the guide's RestDataSource passed QueryParams['$orderby'] straight into URLSearchParams.set. $orderby is a four-shape union (an OData clause string · a Record mapping field name to 'asc'/'desc' · string[] · an array of sort objects) and set takes a string (TS2345). Narrowed to the string form with a comment saying why, rather than stringifying a shape the server cannot parse.
2. building-crud-app.md — the TaskDetail component used SchemaRenderer with no import of its own. A reader copying that block got TS2304.
3. architecture.md — the section titled Type Safety, with the line marked // ✅ Type-checked, set ButtonSchema.onClick to the string 'handleClick'. The declared type is a zero-argument function returning void or a promise of it (TS2322). The block now declares a handler and passes it.

The fourth edited block is architecture.md's step-2 renderer example, which referenced a schema defined only in the step-1 json fence; it now carries that schema as a typed BaseSchema constant, so the block is copy-pasteable.

The pages that are mostly fragments are mostly fragments for a stated reason: guide/plugins and the clipboard-paste RFC document a package the reader is being taught to create, and an RFC's signature excerpts have no bodies by design. Every marker names which of those it is.

The four binding invariants, measured

Diffed programmatically between origin/main's copy of the script and this branch's copy:

invariant	measured
covered set strictly grows	169 → 173 documents
⛔ no previously-covered document becomes ungated	ADDED ledger entries: [] — and previously-covered docs that are now UNGATED: []
surviving entries keep measured reasons	surviving entries with a non-measured reason: [] (49 checked)
⛔ gate strictness never moves	proven byte-for-byte, below

REMOVED entries: is exactly the four pages named above and nothing else.

Strictness proven byte-for-byte, not argued. Everything from the // ── Fence scanning banner to EOF — scanFences, listDocuments, derivePackageTypePaths, analyze, compileSnippets, the reporting and main — is byte-identical to origin/main (475 lines). DOC_EXTENSIONS, TS_FENCE_LANGUAGES, FRAGMENT_MARKER, MIN_REASON_LENGTH and COMPILER_OPTIONS each hash identical. The entire script diff is the four removed ledger entries plus the ledger's own docblock prose: 27 insertions, 34 deletions.

CI cost under the #4846 ruling — stated, not absorbed

--build-filter grew 19 → 20 filters (@object-ui/plugin-dashboard, pulled in by exactly one line: guide/plugins.md's import '@object-ui/plugin-dashboard').

Turbo build tasks stayed 33 → 33, and the two task sets are identical package-by-package from --dry=json (tasks ADDED: [], tasks REMOVED: []) — the new filter was already in the closure as a transitive dependency. Four more covered pages cost this gate zero extra build tasks. Nothing here for the maintainer to weigh.

(The real turbo run build reports 32 where --dry=json reports 33: the difference is @object-ui/test-support#build, which the dry run enumerates but which carries no build command. Both sides of the before/after comparison were measured the same way, so the delta of zero is unaffected.)

Verification

All at 41addc61a, working tree clean and byte-identical to what is pushed, union re-run after that commit, from the repo root, against a build of the gate's own filter closure (32 tasks, all successful, serialised through the container's shared heavy-verify entry point). Exit codes captured before any pipe; each line quotes the gate's own printed verdict.

• node scripts/check-doc-snippet-types.mjs → exit 0. Scanned 222 document(s): 173 covered (37 of them hold a ts/tsx block), 49 ungated · Covered blocks: 203 — 135 to compile, 68 declared fragment(s). · Syntax phase: every block parsed, so every one of them reached the semantic phase. · Semantic phase: 135 of 135 block(s) judged, 0 failed. · Every covered documentation snippet compiles against the built types. Controls green: resolution landed on packages/types/dist/index.d.ts, sentinel produced TS2305, positive control 0 diagnostics.
• scripts/__tests__/check-doc-snippet-types.test.ts → Test Files 1 passed (1) / Tests 20 passed (20). Running the script is not running its test; both were run.
• check-doc-component-types → exit 0, Every documented component type is registered. (183 doc files, 1056 code blocks)
• check-doc-links → exit 0, Links are valid across 13 scan roots.
• check-control-bytes → exit 0, OK (scanned 4950 tracked text file(s); skipped 85 binary), plus a manual control-byte grep over all five changed files: no hits.
• check-lint-coverage → exit 0, 46/46 packages linted, 0 with outstanding errors.
• Root eslint (the exact lint:root invocation) → exit 0, 0 errors, 26 warnings, all pre-existing; the one changed .mjs reports errorCount 0, warningCount 0.
• pnpm check (the CLI self-check the Lint workflow runs) → exit 0, Analyzing 615 files... ✓ All checks passed.

Changeset: none owed, and no label. node scripts/check-changeset-presence.mjs → exit 0: "5 file(s) changed, 0 of them under the src/ of a package the release covers … No source of a released package changed in this range, so no changeset is owed." Followed its verdict. ⛔ No skip-changeset label was applied: that label is not a mechanism in this repo — objectui#3724 established it was documented by a since-deleted second workflow inventory and "neither the workflow nor the label was ever real", a fact scripts/__tests__/ci-cd-pipeline-doc.test.ts still pins. check-changeset-no-major → exit 0.

Lint scope, declared. The root eslint task was run whole, not narrowed. Its population is read from eslint's own config via --format json: 166 files, of which 0 are .md — linting a changed .md directly answers File ignored because no matching configuration was supplied, so four of the five changed files are outside eslint's population by its own configuration. The other 46 per-package lint tasks are scoped to packages/*/, apps/*/ and examples/*/, which this diff does not touch at all.

Fragment markers re-verified rather than inherited. fumadocs-mdx 15.2.3 selects the compiler format by extension (filePath.endsWith(".mdx") ? "mdx" : "md", read from its own dist, two call sites). All four changed .md files were then compiled through @mdx-js/mdx 3.1.1 in format md: all four compile, and doc-snippet occurs 0 times in every compiled output against 34 occurrences in source.

Reverse verification — prediction written before each run, direction included

No build artifact sits between the mutation and the thing under test on either leg: the mutation is markdown the gate reads straight from disk, and the dist/*.d.ts it compiles against is untouched, so no rebuild was needed. Each leg proved the mutation reached disk by grepping the specific text meant to change — never an editor's exit code — and each carried a trap … EXIT INT TERM restore.

Leg 1 — revert architecture.md only, keep its ledger removal. Predicted: exit 1; exactly 25 diagnostics, all on that page; fragments 68 → 58; blocks-to-compile 135 → 145; the two edited blocks fail again as TS2322 and TS2304; NOTE printed; direction MORE findings. Observed: exit 1; 25, all on that page; Covered blocks: 203 — 145 to compile, 58 declared fragment(s); TS2304: Cannot find name 'schema' and the TS2322 on onClick (string not assignable to the handler type); NOTE printed. Match including direction.

Leg 2 — revert all four pages, keep all four ledger removals. Predicted: exit 1; exactly 89 diagnostics split 20/21/23/25; fragments 68 → 34; blocks-to-compile 135 → 169; NOTE printed; direction MORE. Observed: exit 1; 89 exactly, split 20 plugins / 21 building-crud-app / 23 clipboard-paste / 25 architecture — matching the baseline to the unit and per page; Covered blocks: 203 — 169 to compile, 34 declared fragment(s); Syntax phase: 7 block(s) failed to parse; NOTE printed. Match including direction.

Restore leg run, not skipped: git status clean, 34 markers back on disk, git diff HEAD empty, gate exit 0 with 135 of 135 block(s) judged, 0 failed.

Two dispatch measurements checked

• ✅ building-crud-app's recorded reason over-stated its debt. It recorded 20 undefined-name / 4 unresolved-module; measured 14 TS2304 and 3 TS2307. Confirmed exactly. The stale numbers were not copied forward — the entry is deleted, so the drift is retired rather than re-worded.
• ✅ Nothing was mechanically clearable. Re-measured: zero TS2305/TS2724/TS2614 across all 89 diagnostics. 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 cleared that class completely; every diagnostic here was genuine per-page fragment / self-containment judgement. ⛔ No fabricated symbol was re-decided per page.

What is left on this card

5 .md guide entries: plugin-development 25 · schema-rendering 27 · theming 29 · layout 45 · component-registry 59 = 185 diagnostics, plus 12 .mdx and 32 READMEs. layout and component-registry are 104 between them and are a batch of their own, as the batch-1 seat noted.

Generated by Claude Code