docs(patches): say what pnpm 10.28.2 measurably does on a fumadocs-core bump

[hotlong]

Fixes #284

What changed

Only the "ON A VERSION BUMP" section of the header comment in patches/fumadocs-core@16.8.12.patch, plus the pnpm-lock.yaml lines that pnpm 10.28.2 rewrote because of it.

The old section contradicted itself. Its heading said "THIS PATCH IS EXPECTED TO FAIL LOUDLY", and its body said "the defect returns silently". The new section says only what #284's table measured with pnpm 10.28.2, on cb0c146 plus #239's one-line version change:

• Regenerating the lockfile fails loudly. --no-frozen-lockfile and --lockfile-only both exit 1 with ERR_PNPM_UNUSED_PATCH. --frozen-lockfile on the stale lockfile exits 1 earlier, on mismatched specifiers.
• Two paths end in an install that exits 0 and prints nothing:
  1. Deleting the pin, which is the first remedy the error text offers. 16.15.2 is then installed unpatched, and the defect is back at 67 references and 4 of 661 malformed targets.
  2. Regenerating the lockfile with allow-unused-patches. The frozen install then accepts that lockfile.
• The Locale surface step from ci: fail the build when an llms body carries a numeric character reference or a malformed link target #285 fails the build when either llms output carries the defect. It was measured red on the pin-deleted tree. The header claims only that; it does not claim the gate was run on path 2.

Left out: the Dependabot-updater inference. Dependabot's updater was not run, so the header does not mention it.

Kept and re-measured: the old section's sentence about 16.15.x reformatting an if was reworded, because this PR measured it. I unpacked both published tarballs in this session. diff shows the only difference in dist/mdx-plugins/stringifier.js is one if at line 28, which grows from 3 lines to 5. git apply --check of this patch against 16.15.2 prints Hunk #1 succeeded at 68 (offset 2 lines). The header now says the hunk's context sits 2 lines lower there. That replaces the unmeasured "does not necessarily line up" and the inaccurate "two hunks up", since the patch has one hunk. The header makes no claim about how pnpm's own patcher treats that offset, because that was not measured.

The diff hunks are byte-identical

Everything from the first diff --git line to EOF, origin/main (7004d3d) against this branch (2d9ffcb):

	first diff --git at byte	hunk section bytes	sha256 of hunk section
origin/main	3407	1357	7501cfc05abd506d346be71b686133008a89a2af78d70d33eea33c4e9bfce8d3
this branch	4840	1357	7501cfc05abd506d346be71b686133008a89a2af78d70d33eea33c4e9bfce8d3

cmp -l lists 0 differing bytes, and cmp exits 0.

The lockfile: the hash moved, and pnpm rewrote it

The PM's mechanism assumptions, as measured:

1. The hash moves. pnpm's patchedDependencies hash is the sha256 of the whole patch file. sha256sum of origin/main's file is 042796c0…b182ed8d79, exactly the old lockfile hash. The edited file's sha256 is a88318fc…7b625b3dfe57, and that is what pnpm wrote.
2. A frozen install against the old lockfile fails. It exits 1 with: ERR_PNPM_LOCKFILE_CONFIG_MISMATCH Cannot proceed with the frozen installation. The current "patchedDependencies" configuration doesn't match the value found in the lockfile. I reproduced this before regenerating.
   • I then regenerated with pnpm install --lockfile-only (pnpm 10.28.2, exit 0).
   • The assumption that only one line changes was slightly wrong. git diff --numstat reads 9 9 pnpm-lock.yaml. The hash appears 9 times: once as patchedDependencies…hash, and 8 times as the patch_hash= segment inside the dependency keys of fumadocs-core itself and of its dependents fumadocs-mdx and fumadocs-ui.
   • Taking origin/main's lockfile and replacing the old hash with the new one (sed s/OLD/NEW/g) gives a file byte-identical to the regenerated one (cmp exit 0). So the hash substitution is the only change: 9 old occurrences before, 9 new ones after, and 0 old ones left.
3. After regeneration, with node_modules wiped in the root and apps/docs (tools/ci-scripts had none), pnpm install --frozen-lockfile exits 0. The patch still applies, shown the same way as in fix(docs): pin the fumadocs-core peek omission that encodes markdown as entities #281:
   • Resolved through apps/docs, the virtual-store path is node_modules/.pnpm/fumadocs-core@16.8.12_patch_hash=a88318fc3b23c44ea3645ae68c43af3a905e0d00d6bc2fcefe3a7b_96ea1a842d0433803cdfc29229a4f307/…/dist/mdx-plugins/stringifier.js. It is the only fumadocs-core directory in the store.
   • if (handler.peek) wrapped.peek = handler.peek; is at line 81 (count 1). The pristine anchor appears 0 times.

Gates run on 2d9ffcb (the head of this PR)

Exit codes were captured before any pipe. Each quoted line is the gate's own verdict.

• NEXT_PRIVATE_STANDALONE=true pnpm turbo run build --force: exit 0, Tasks: 1 successful, 1 total / Cached: 0 cached, 1 total
• node .github/scripts/check-locale-surface.mjs: exit 0. llms-full.txt: 1 of 1 bodies, 0 numeric references, 661 link targets, 0 malformed. llms.mdx: 79 of 79 bodies, 0 references, 661 targets, 0 malformed. It also prints `fumadocs-core` resolved by `apps/docs`: 16.8.12 · patch pinned to: 16.8.12 and ✓ every advertised URL has a source file … and neither llms consumer carries a numeric character reference or a malformed link target
• pnpm turbo run test --force: exit 0, ✓ 7 self-test(s) passed
• node .github/scripts/check-node-floor.mjs: exit 0, ✅ Every declared floor clears what the dependency tree requires, and the declarations agree. (430 engines blocks scanned)
• No control bytes in the patch file (grep -naP for C0 and DEL: 0 matches). Every header line is ASCII and at most 84 columns.

Not run locally: Worker packaging, the size weigh-in, and the preview smoke check. CI runs all three.

Not touched

Root package.json, apps/, content/, .github/, and the patch's diff hunks. #239 was not pushed to, commented on, or merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr

Generated by Claude Code

---

Generated by Claude Code