docs(guide): retire the hand-written version table from the release notes page

[yinlianghui-tw]

Fixes#5786

Executes the maintainer's ruling of 2026-08-23 (option D): the hand-written version
table on content/docs/guide/release-notes.md is retired and the page collapses to a
short pointer at the two sources that are written as part of each release. No refresh of
the version numbers, no generation pipeline, no pin test — those were the rejected
options.

Why not simply refresh it

Refreshing is the intuitive fix and it was ruled out twice over. It is the third instance
of the same shape (#3689 on the CLI page, #3645 across 35 package READMEs): a hand-written
version block that nothing pins drifts again as soon as it is corrected. And it is
currently unanswerable — the releases API and QUICK_REFERENCE.md disagree about the
current version, which is the repo-vs-npm divergence #5442 exists to settle. Retiring the
table sidesteps that question rather than enshrining one side of it.

What the page says now

It names both sources concretely, because three entry points send readers here to learn
what shipped and a pointer that does not say which changelog or where Releases live
would be worse than a stale page:

• each package's own CHANGELOG.md — where to read it in the installed package, on
  npm, and in this repository — stated as the source of truth for granular history,
  including breaking changes and migration notes;
• GitHub Releases, linked, as the place to see which version is current.

#5785's correction of the granular/summary relationship (the monorepo CHANGELOG.md is a
hand-curated summary that can lag, and each package's own file wins where they disagree)
is preserved in substance and now carries the whole page. This change composes with that
PR; it does not undo any of it.

The coupling this uncovered, and why the test is in the diff

scripts/__tests__/doc-version-claims.test.ts pinned this page by name:

expect(exemptFiles,'the v3.3.0 release section must still be reached by the exemption').toContain('content/docs/guide/release-notes.md');

That gate exempts version literals sitting under a version heading (release notes are
frozen history) and ratchets every other literal. Measured across this change, the page's
## v3.3.0 section was the corpus's only version-heading section: exemptClaims went
from 8 to 0, and the assertion above was the one thing in the repository that noticed.

A floor over exemptClaims.length would now be a pin demanding that some published page
keep carrying release sections — a shape this repository deliberately no longer has. The
exemption is still live code that every corpus claim passes through, so it is now exercised
against a fixture through claimsIn, the same function the corpus goes through. The
fixture keeps the retired compatibility row verbatim, and the new assertion is strictly
stronger than the one it replaces: it pins both directions on one document (the claim
above the release heading stays scanned, the one under it is exempt, and the exemption is
reached through an ancestor heading), where the corpus arrangement ruled out
"green by not matching" on the exempt side only.

Proven to be load-bearing rather than decorative: with VERSION_HEADING ablated to a
regex that never matches, the file goes to 2 failed | 16 passed; restored, 18
passed. The mutation was confirmed on disk before the run (injected marker present ×1,
original pattern absent), and the ablation script carried a trap ... EXIT INT TERM
restore — git status was clean afterwards.

Verification — all at 58e18f484, the final commit

check	verdict line
node scripts/check-doc-links.mjs	Links are valid across 15 scan roots.
node scripts/check-doc-component-types.mjs	✅ Every documented component type is registered.
node scripts/check-control-bytes.mjs	✅ check-control-bytes: OK (scanned 5026 tracked text file(s); skipped 85 binary).
node scripts/check-changeset-presence.mjs	✅ No source of a released package changed in this range, so no changeset is owed.
vitest run scripts/__tests__/doc-version-claims.test.ts	Tests 18 passed (18)
tsc -p tsconfig.scripts.json	exit 0
eslint on the changed .ts	1 file linted, 0 errors, 0 warnings
turbo run build --filter=@object-ui/site	Tasks: 30 successful, 30 total

The page was then read out of the prerendered HTML
(apps/site/.next/server/app/docs/guide/release-notes.html) rather than assumed to
render: it comes out as a coherent short page — title, description, two bullets and a
closing paragraph — not an orphaned heading, and all three outbound links
(/tree/main/packages, /releases, /blob/main/CHANGELOG.md) are present in the article.

Narrowing declared: eslint was run on the one changed .ts file rather than repo-wide.
The other changed file is .md, and this repo's eslint config names no markdown files, so
the narrowing excludes nothing that eslint would have judged. CI runs the full farm either
way.

Honest limit: retiring a documentation surface has no runtime consequence, so there is
no behavioural test to point at. The evidence is negative by nature — nothing still points
at content that no longer exists: check-doc-links is green over the page's new links, the
one gate that referenced the removed content is updated in this diff, and a repo-wide grep
for release-notes finds only the sidebar entry (content/docs/guide/meta.json) and that
test.

Inbound links: checked, none became misleading

• content/docs/guide/meta.json — the sidebar entry, the only thing in the repository that
  links to this page. A reader clicking "Release Notes" now gets an answer to the question
  they arrived with, so it stays.
• README.md's "Changelog (summary)" and the changelog section of
  content/docs/guide/ci-cd-pipeline.md point at the root CHANGELOG.md, not at this page,
  and both already describe it as a hand-curated summary. Unaffected, and not edited.

No changeset: content/docs/** and scripts/__tests__/** touch no released package's
src/, which CONTRIBUTING.md lists explicitly under "No changeset is needed at all", and
check-changeset-presence.mjs agrees.

Out of scope and untouched, per the dispatch: the root CHANGELOG.md, QUICK_REFERENCE.md
and its pin tests, check-doc-links.mjs, and #5442's version-divergence question.

---

Generated by Claude Code

[yinlianghui-tw]

PM: ACCEPT — ruling D executed, and the gate you broke came back stronger

The maintainer's ruling is carried out exactly: the hand-written v3.3.0 section, its Upgrade Notes and its compatibility matrix are gone, and the page is a short pointer. No version numbers refreshed, no generator built, no pin test added — the three rejected options, all avoided. And PR #5785's correction of the granular/summary relationship was re-derived from main and preserved rather than overwritten; it now carries the whole page.

The coupling was found by measuring, not assuming — and that is the whole reason the order asked

scripts/__tests__/doc-version-claims.test.ts pinned this page by name, and the v3.3.0 section turned out to be the scanned corpus's only version-heading section: exemptClaims measured 8 before the cut and 0 after, so the gate went red.

The order said "grep for tests pinning this page's content before you cut it — verify that rather than assuming it." This is precisely the case it was written for, and the naive read (only QUICK_REFERENCE.md is pinned) would have been wrong.

The fix is the part worth naming

When removing content leaves an assertion with nothing to assert on, there are two easy wrong moves: delete the branch, or leave it silently matching nothing. You took neither. The version-heading exemption is now exercised against a fixture through claimsIn — the same function the corpus goes through — pinning both the exempt and the scanned direction on one document.

That is stronger than what existed before: the corpus arrangement only ever exercised the exempt direction, and only by accident of one page happening to contain a version heading. A gate whose coverage depends on a doc nobody is required to keep is a gate one edit from going vacuous — which is exactly what just happened. Routing it through a fixture makes the coverage deliberate.

And you ablated the replacement rather than trusting it: VERSION_HEADING mutated to a never-matching regex, confirmed on disk first (injected marker 1, original pattern 0), file went to 2 failed | 16 passed, restored under a trap with a clean git status. You also said why no rebuild was owed — vitest reads the TS source directly, nothing resolves through dist. This lane has lost a round to a stale artifact today; naming the reason is what separates that from luck.

The pointer actually answers the question

The order warned that a pointer failing to say which CHANGELOG or where Releases live is a worse page than a stale one. Yours names both concretely — each package's own CHANGELOG.md with three places to read it (the installed package, npm, and packages/PKG/CHANGELOG.md in-repo), and GitHub Releases, linked.

And you verified it renders as a real page rather than an orphaned heading by reading the prerendered HTML at apps/site/.next/server/app/docs/guide/release-notes.html — title, description, both bullets, closing paragraph and all three outbound links present in the article. Read, not assumed.

Inbound links checked, correctly not edited

meta.json's sidebar entry is the only link into the page, and it still answers what readers arrive with. README.md's "Changelog (summary)" and ci-cd-pipeline.md's changelog section point at the rootCHANGELOG.md, not here — so nothing became misleading and nothing needed touching. The repo-wide grep for release-notes finding only meta.json and that test is the evidence that closes it.

Sidestepping #5442 entirely is also the right outcome, and it is part of why D was chosen: with the releases API saying 17.5.0 and QUICK_REFERENCE.md saying 17.6.0, "refresh to the current version" had no correct answer. Retiring the table means the page no longer has an opinion that can be wrong.

Honest limit, correctly stated

Retiring a doc surface has no runtime consequence, so there is no behavioural test — the evidence is that nothing still points at content that no longer exists. Backed by three readings rather than an assertion: check-doc-links green over the new links, the one gate referencing the removed content updated in this diff, and the repo-wide grep.

Changeset correctly not written, with the reason cited from CONTRIBUTING (documentation and repo-level scripts sit under "No changeset is needed at all") and the gate asked anyway.

Landing

⏳ CI converging on 58e18f484. The self check-in verifies every-check-green and lands it.

---

Generated by Claude Code