fix(repo): declare the Node/pnpm floors the toolchain actually requires

[os-warren]

Fixes #5306

Implements the maintainer ruling of 2026-08-25T05:50Z exactly, by the numbers rather than the option letters (the letters in the ruling do not line up with the letters in the analysis comment; the numbers govern):

"engines": { "node": ">=22.11", "pnpm": ">=10" }

⛔ The segmented range ^22.11 || ^24 || >=26 was ruled out as an ongoing maintenance tax, and the jsdom ^22.22.2 measurement is not re-litigated here — the maintainer had it in front of them when they chose the minimal correction. ⛔ engine-strict=true is out of scope by the same ruling; .npmrc is untouched and #6264 is not edited.

Verified before implementing: >=22.11 is not actively wrong. CI resolves node-version: '22.x' to 22.23.2 (PM's job-log read on this card), this container runs 22.22.2, and pnpm install --frozen-lockfile is clean under the new floor — quoted below. Nothing had to be excluded that CI or contributors actually use.

What moved, and why each one is load-bearing

File	Change	Why it is not optional
package.json	node: ">=22" → ">=22.11", pnpm: ">=9" → ">=10"	The ruling.
QUICK_REFERENCE.md	pnpm row ≥ 9 → ≥ 10	The second half the dispatch asked me to look for. scripts/__tests__/quick-reference-current-release-4143.test.ts pins this row to engines.pnpm; without it the change is red. Regenerated with pnpm quick-reference:sync, not by hand.
CONTRIBUTING.md:23-24	"Node.js 18.0 or higher" → 22.11; pnpm line now states its floor	Contributor onboarding stated a floor four majors below the manifest.
CONTRIBUTING.md:378	"Tests on Node.js 18.x and 20.x" → 4 shards on 22.x	There is no Node matrix in ci.yml at all — the matrix is shard: [1,2,3,4], all on node-version: '22.x'.
scripts/setup.sh	reads both floors out of engines; compares full versions	The automated setup README.md:465 points contributors at. It enforced Node ≥ 20 / pnpm ≥ 9 in hard-coded integers.
content/docs/guide/deployment.md	corepack prepare pnpm@9 → pnpm@10; Netlify NODE_VERSION 20 → 22, PNPM_VERSION 9 → 10	This page builds this workspace (it copies pnpm-workspace.yaml, packages/, apps/ and publishes apps/console/dist), so its toolchain versions are claims about the repo, not about a reader's app.

⚠️ The Node row in QUICK_REFERENCE.md deliberately does not move. Its pin derives the floor as the first integer of the range (engines.node.match(/(\d+)/)), so >=22.11 still reads ≥ 22. Changing that row to ≥ 22.11 would go red. Called out because "the Node floor changed but the Node row didn't" looks like an oversight and is not.

Three edits outside package.json + CONTRIBUTING.md, declared rather than slipped in

scripts/setup.sh, the deployment.md versions and the pnpm half of the CONTRIBUTING.md prerequisites are in-place fixes of the same defect this card exists to close (a stated Node/pnpm floor disagreeing with the toolchain), each with its correct form pinned by evidence already in the tree — the ruling's numbers, packageManager: pnpm@10.31.0, and the workflows' own node-version: '22.x'. None of them adds a verification surface. Naming them here because an unnamed drive-by fix is unreviewable sprawl.

setup.sh reads the floors instead of repeating them, which is the only version of this fix that cannot drift again:

NODE_FLOOR=$(node -p "require('$REPO_ROOT/package.json').engines.node.replace(/^[^0-9]*/, '')")
if [ "$(printf '%s\n%s\n' "$NODE_FLOOR" "$(node -v | cut -d'v' -f2)" | sort -V | head -n1)" != "$NODE_FLOOR" ]; then

The old check compared majors (cut -d'.' -f1), so a 22.11 floor was not even expressible in it — -lt 22 would have accepted 22.0–22.10 while the message next to it claimed 22.11, re-creating this card's defect one order of magnitude smaller.

Two premises in the dispatch, measured

• ✅ CONTRIBUTING.md does say "Node.js 18.0 or higher" — line 23, and it is fixed here. The PM's grep found only line 378 because the line reads - **Node.js** 18.0 or higher: the bold markers sit between the name and the number, so a contiguous Node.js 18 pattern misses it. Not "already fixed" — the pattern missed it.
• ⚠️ The content/docs sweep is NOT empty. Paired with a control (grep -rl pnpm content/docs → 19 files of 184, so the sweep reaches the tree), four pages carry Node/pnpm version prose. One is fixed here (deployment.md); one is already correct and self-anchoring (content/docs/utilities/cli.mdx:300 points at the engines field rather than restating it); two are deliberately not touched and filed instead — see below. My own first pattern also returned zero on QUICK_REFERENCE.md, for the same bold-marker reason, which is how a one-pattern zero reads as an empty sweep twice in a row on this card.

⛔ content/docs/releases/ untouched. content/docs/guide/release-notes.md's historical Node.js >= 18 compatibility matrix for the shipped v3.3.0 release untouched — rewriting a past release's stated compatibility misrepresents history.

Deliberately left alone, filed instead

• finding(docs): the consumer-facing Node/pnpm floors in two guides are anchored to nothing — and the version-literal ledger cannot see them, because its separator class excludes **bold** #6307 — content/docs/guide/quick-start.md:12-13 and building-crud-app.md:12 state Node.js 20+ / pnpm 9+ for a reader building their own app (pnpm create vite my-app), not this workspace. Measured: 0 of 40 packages declare engines, so those numbers restate no manifest in this tree. Rewriting them to 22.11/10 would invent a consumer requirement nobody measured — the mirror image of this card's defect. Filed with the reason no gate objected: doc-version-claims' separator class excludes *, so **Node.js** 20+ is invisible to the ledger that exists to catch exactly this.
• docs(ci-cd-pipeline): the "follow the existing pattern" workflow snippet teaches setup-node@v4 + node-version: 20 + pnpm/action-setup, none of which this repo uses #6308 — ci-cd-pipeline.md:1626-1637 teaches actions/setup-node@v4 + node-version: 20 + pnpm/action-setup@v4 as "the existing pattern", against a repo with 27× setup-node@v7, node-version: '22.x' everywhere and zero pnpm/action-setup. Same family, but a multi-part snippet rewrite on a page carrying its own pin test — a separate change, not a rider.

Cross-lane

⚠️ This PR touches content/docs/guide/, where PR #6082 (card #5923) is in flight. Checked immediately before pushing: #6082's file list is content/docs/guide/layout.md only — no overlap with deployment.md. origin/main was re-fetched at push time and is still 090927f4f (0 commits since my base), so nothing landed under content/docs/guide/ or on root package.json while I worked.

Gates

All run on the final commit 12052c180, exit codes captured by redirect before any pipe, each quoted from the gate's own verdict line.

Gate	Exit	Its own verdict
pnpm install --frozen-lockfile (new floor)	0	Lockfile is up to date, resolution step is skipped / Already up to date / Done in 2.6s using pnpm v10.31.0 — no engine warning
node scripts/check-changeset-presence.mjs	0	✅ No source of a released package changed in this range, so no changeset is owed.
pnpm quick-reference:check	0	✅ QUICK_REFERENCE.md's "Current Release" block already states every anchor.
vitest run × 4 pin files	0	Test Files 4 passed (4) / Tests 139 passed (139)
pnpm check:control-bytes	0	✅ check-control-bytes: OK (scanned 5195 tracked text file(s); skipped 85 binary).
pnpm check:shell-escape-residue	0	✅ check-shell-escape-residue: OK (4/4 root(s) resolved …)
pnpm check:doc-fences	0	✅ check:doc-fences — every TypeScript block in 223 document(s) is fenced ts/tsx/typescript …
pnpm docs:check-links	0	Links are valid across 17 scan roots.

Pin files run: quick-reference-current-release-4143, sync-quick-reference-release, doc-version-claims, check-doc-links.

No changeset, on the gate's verdict rather than on my judgement — nothing published changed. ⛔ No skip-changeset label: #4912 records that no workflow reads it in this repo.

Repo-wide pnpm lint narrowed, and the narrowing is measured, not assumed. eslint --format json over all five changed paths returns five results, every one of them File ignored because no matching configuration was supplied. — eslint's own config, not my guess, says this diff contains zero files it judges (a .json, three .md, one .sh). No type-aware linting is configured, so no untouched file's verdict can move either. CI runs the full farm regardless.

Reverse verification — the pin is live, not vacuously green

Committed first, then mutated, then restored (never against an uncommitted edit):

1. Put the pnpm row back to ≥ 9. Mutation proven on disk by blob hash, not by an editor's exit code: git hash-object moved from 0708d493d… (HEAD) to ef00feb7f…, and the old/new row spellings counted 1/0.
2. vitest run scripts/__tests__/quick-reference-current-release-4143.test.ts → exit 1, Tests 2 failed | 6 passed, on exactly the right assertion:
   AssertionError: QUICK_REFERENCE.md's pnpm row must state exactly the floor "≥ 10" and the pinned "pnpm@10.31.0": expected [ '10.31.0', '≥9' ] to deeply equal [ '10.31.0', '≥10' ]
3. Restored with git checkout HEAD -- QUICK_REFERENCE.md (naming HEAD, not a bare checkout that would re-read the polluted index), under an EXIT INT TERM trap using an absolute repo root. Restore proven the same way as the mutation: blob hash back to 0708d493d…, git diff HEAD empty. Both legs re-run green afterwards.

No build/dist leg applies here: the pin reads QUICK_REFERENCE.md and package.json off disk, so there is no compiled artifact that could keep a mutation alive or hide it.

---

Generated by Claude Code