docs: repair QUICK_REFERENCE's dead commands and layout claims, and pin them (#4149)

[yinlianghui]

Fixes#4149

Ordering

PR #4150 (same file, armed for auto-merge) merged as 43b2e4565 before this started, so this branches off main rather than stacking on claude/issue-4143-console-version-drift. The ## Current Release block that PR repaired and pinned is untouched here, and its test stays green.

Premise: valid, and it under-reported

All four claims on the card reproduce on 43b2e4565. Sweeping the rest of the page — the card says its list is the floor — found two more, one of them the same class as apps/server:

• packages/tenant sits in the Package Tiers table. That package was deleted by objectui#2564 (commit d5b1bc0b4, "drop zero-consumer @object-ui/tenant package").
• QUICK_REFERENCE.md is outside every SCAN_ROOTS entry in scripts/check-doc-links.mjs, so none of its internal links has ever been resolved by anything that can fail a build — the same hole objectui#4148 recorded for apps/**.

1. Commands — run-it-or-derive-it, one row each

Documented	What running it did	Now	Anchor
pnpm install	Done in 6.2s using pnpm v10.31.0	unchanged	pnpm builtin
pnpm build	--dry=json → turbo resolved 44 build tasks	unchanged	root script
pnpm typecheck	ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command "typecheck" not found / Did you mean "pnpm type-check"? (exit 254)	pnpm type-check — --dry=json → 80 tasks	root script
pnpm lint	--dry=json → 45 lint tasks	unchanged	root script
pnpm --filter @object-ui/site dev	Next.js 16.3.0 … Local: http://localhost:3000	unchanged — the documented port is correct	workspace pkg + script
pnpm test	CI runs pnpm test --shard=… (ci.yml:379)	unchanged — the "(CI runs this)" note is accurate	root script
pnpm exec vitest run …	exercised by this PR's own runs	unchanged	binary
pnpm playwright test	works — pnpm playwright --version → Version 1.62.1	pnpm test:e2e — --list → Total: 165 tests in 6 files, exit 0	root script
3 × example-* dev	No projects matched the filters — and exit 0	the two real ones (below)	workspace globs
pnpm changeset / version / publish	not executed — see the split below	unchanged	root script

Two rows need their reasoning stated rather than assumed.

pnpm playwright test was replaced even though it works. That is the one command on the page I changed without it being broken. It resolves because pnpm falls back to the local binary, but it is not a script, so it has no manifest anchor and the pin below would have needed a permanent carve-out for it. pnpm test:e2e is the repo's own declared spelling and the one CI runs (ci.yml:536, pnpm test:e2e --project=chromium). The pin found this by itself: on the pre-fix file it reports pnpm playwright test (no root script "playwright") beside pnpm typecheck.

The changesets block was verified, not executed — version rewrites every manifest and publish pushes to npm. What I checked instead is the only thing that was in doubt, read-only: that pnpm changeset SUBCOMMAND forwards its argument, since the repo also declares changeset:version and changeset:publish. pnpm changeset status prints > changeset status and exits 0, so pnpm changeset version runs changeset version exactly as changeset:version does. All three lines stand.

Run Examples

examples/ holds byo-backend-console, console-starter, hello-world and schema-catalog — none of the three the section named. The card flagged this as needing a judgement call about which examples a newcomer should run. It does not need one: examples/README.md already owns that decision and is maintained. It documents hello-world as a snippet and schema-catalog as "Not a runnable app — a data package", and their manifests agree: only the other two declare a dev script. So the block documents those two, and the prose points at that README rather than restating it.

Both were started and stopped for this PR:

> @object-ui/example-console-starter@0.1.0 dev
VITE v8.2.1 ready in 425 ms
➜ Local: http://localhost:5173/
> @object-ui/example-byo-backend-console@0.1.0 dev
VITE v8.2.1 ready in 387 ms
➜ Local: http://localhost:5174/

No ports in the page: one of the two pins server.port in its vite.config.ts and the other takes Vite's default, so the numbers are not uniformly derivable and examples/README.md already says "each exposes its own dev server port (see its README)". Pointer, not enumeration.

2. Paths

apps/server and packages/tenant are removed. The examples/* row enumerated four examples, two of which no longer exist; it becomes a pointer to examples/README.md, which is the file that stays current by being the examples index. Every other path in the file was checked against the tree and is present.

3. The count: a derived number, not a pointer

The card allowed either. This one keeps a number, because it has an exact anchor (private in each manifest) and because a count carries information a pointer cannot — the scale of the repo. What it may not be is hand-written: "39" counted directories, and packages/vscode-extension (package name object-ui, shipped to the VS Code marketplace) is private: true.

The row now reads 38 published packages (@object-ui/*), plus the private vscode-extension. Naming the private one is load-bearing, not decoration: without it a reader who counts 39 directories and reads 38 "corrects" the number back, which is how the original defect is most likely to return. The test requires that reconciliation only while a private package exists — see below.

Contrast the examples/* row and the .changeset/ note (the latter already pointer-ised by #4150): those enumerate a set that churns and have no stable form, so they get pointers. The rule I applied is per-claim, as the card asked: anchor exists and is exact → derive a number; set churns → point at the file that owns it.

4. The pin — scripts/__tests__/quick-reference-commands-4149.test.ts

A sibling of #4143's test, not an extension of it. That file is scoped to ## Current Release in its own words, deliberately, because "asserting over the whole file would conflate a status claim with a package count" — and its reverse direction (no un-derived version literal) would go red on this page's ports and counts if widened. So the two split by section and this one never reads ## Current Release.

Eleven assertions, every expectation computed from an anchor, no value written twice:

• every pnpm command in the page's bash fences names a root script (or a pnpm builtin)
• every --filter target is a real workspace package that declares the script it is asked to run
• reverse: every examples/* package declaring a dev script has a documented command. Forward alone stays green on a page that documents nothing — what was actually wrong is that both runnable examples were missing while three phantoms were listed
• every path in a code span exists; globs must match at least one directory
• reverse: every directory under apps/ has a layout row (the table lists apps individually, so a new one is invisible until someone adds it)
• the published count is derived from the manifests' private flags, the @object-ui/* parenthetical is checked against the published names, and the private packages must be accounted for — that last assertion retires itself when the last private package leaves, so the exemption cannot outlive its justification
• every relative link resolves (nothing else does this, per the SCAN_ROOTS gap above)
• the quoted vitest-guard message still appears in scripts/vitest-invocation-guard.mjs

What is deliberately left unpinned, per the card's "report the split": the prose, the trailing comment on each command, the example ports, and two of the five quoted guard lines — those two are built by string interpolation in the guard's canonicalLines() and are not literals in the source, so asserting them would mean re-implementing the guard's formatting. The three that are literals are asserted, which is enough to catch a rewording. There is also no "every root script must be documented" direction: the root manifest declares ~50 scripts, this is a one-page cheat-sheet, and the defect is a documented command that does not exist — not an existing command that is undocumented.

Reverse verification — both directions, predicted first

Fix taken out with git checkout origin/main -- QUICK_REFERENCE.md plus a patch file. Never git stash — that stack is shared across worktrees (objectui#3430).

Doc side. Predicted 6 red / 5 green before running: dead script, dead filter, missing-examples reverse, dead paths, wrong count, unexplained private gap red; link check, apps/ reverse, guard quote, parser guard and the @object-ui/* naming check green. Measured: Tests 6 failed | 5 passed (11).

QUICK_REFERENCE.md documents ["pnpm typecheck (no root script \"typecheck\")",
"pnpm playwright test (no root script \"playwright\")"]
QUICK_REFERENCE.md documents ["pnpm --filter @object-ui/example-crm dev (no workspace package named …)", …]
QUICK_REFERENCE.md's "Run Examples" section documents no `pnpm --filter … dev` line for
["examples/byo-backend-console","examples/console-starter"]
QUICK_REFERENCE.md names ["apps/server (not in the tree)","packages/tenant (not in the tree)"]
QUICK_REFERENCE.md must state "38 published packages" … (39 directories, 1 of them private: ["packages/vscode-extension"])
QUICK_REFERENCE.md's `packages/*` row states a published count that is smaller than the 39 directories a reader sees

The five that stayed green are the claims that had not drifted — the same asymmetry #4150 relied on as evidence the gate measures the doc rather than the edit.

Anchor side — two mutations against the repaired page, the direction that proves the expectations are computed rather than hardcoded a second time:

1. rename root type-check → type-check-renamed: documents ["pnpm type-check (no root script \"type-check\")"]
2. delete private from packages/vscode-extension/package.json: must state "39 published packages" … (39 directories, 0 of them private: [])

Mutation 2 produced a third, unpredicted red that is the guard working correctly: keeps the @object-ui/* parenthetical true fired, because an un-privated vscode-extension publishes under the name object-ui, which is not @object-ui/*. And the self-retiring clause behaved: with zero private packages, "accounts for the private packages" went green on its own. Both mutations reverted; git status clean apart from this change.

Gates

$ pnpm exec vitest run scripts/ # whole pin-test suite, incl. #4143's
Test Files 30 passed (30)
Tests 576 passed (576)
$ pnpm run type-check:scripts # tsc -p tsconfig.scripts.json → exit 0
$ pnpm run check:control-bytes
✅ check-control-bytes: OK (scanned 3844 tracked text file(s); skipped 85 binary).
$ pnpm run docs:check-links
Links are valid across 7 scan roots.
$ pnpm exec eslint scripts/__tests__/quick-reference-commands-4149.test.ts # exit 0

ESLint earned its keep here: it caught a zero-width space (U+200B) I had used inside a block comment to keep a glob from closing the comment — no-irregular-whitespace, an invisible byte that the control-byte scan does not cover. Rewritten in words; both files then re-swept for invisible and control characters, clean.

Changeset

None owed — arbitrated by the script, not by judgement:

$ node scripts/check-changeset-presence.mjs
✅ No source of a released package changed in this range, so no changeset is owed.

On the skip-changeset label: it exists as a label object in this repo, but nothing reads it — changeset-presence.yml decides from the diff and matches no label, and scripts/__tests__/ci-cd-pipeline-doc.test.ts:184 records that objectui#3724 deleted .github/WORKFLOWS.md for documenting, among other phantoms, "a changeset gate skippable with a skip-changeset label; neither the workflow nor the label was ever real". It is applied here for consistency with the dispatch convention, with no mechanical effect either way.

Out-of-scope findings — reported, not fixed

• check-doc-links cannot see this file. Its seven scan roots do not include the repo root, so QUICK_REFERENCE.md, AGENTS.md, CLAUDE.md and CHANGELOG.md have never had a link resolved by a blocking gate. objectui#4148 already covers widening SCAN_ROOTS (it was filed for apps/**); this is the same gap, one directory over, and belongs there rather than in a second card. The new test resolves this page's own links in the meantime.
• next dev writes two untracked files that nothing ignores. Running pnpm --filter @object-ui/site dev (for the port check above) made Next.js 16 generate apps/site/AGENTS.md and apps/site/CLAUDE.md via node_modules/next/dist/server/lib/generate-agent-files.js. They are neither committed nor in .gitignore, and the generated text tells the reader to commit them. In a repo where parallel agents run git add -A, that is a live trap for sweeping generated files into an unrelated PR. Deleted from this worktree, not fixed here; filed separately.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 2:57pm