docs(releases): split the v17 page per minor, and draft the missing 17.4.0 section

[huangyiirene]

Docs-only restructure, on the maintainer's direct instruction (「v18 起按新结构建，v17 回填。同意，现在就处理，包括刚发布了 17.4」). ⛔ Not a rider on a code change — content/docs/releases/** is edited here and nowhere else, per the content/docs/releases/ guardrail.

Governed-surface check. Today's register, printed rather than recalled — docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md. This PR's 14-file list hits none of them (content/docs/** and scripts/** are not on the register), so Prime Directive #14 does not apply and the merge queue is the landing path (AGENTS.md §7).

Why

content/docs/releases/v17.mdx had reached 5,611 lines / 369 KB — 5.7× the finished v16 page (1,052 lines), at 17.3.0, with 17.4.0 still to land. At roughly 90k tokens that is two thirds of the budget this project advertises for an entire application, in one release-notes file.

And the reader's question is per-minor, while the page answered it in three places up to 1,200 lines apart: What's new in 17.2.0 (line 4042), Breaking changes & migration in 17.2.0 (4059), and 17.2.0 under a separate Upgrade checklist heading (5284).

What changed

v17.mdx becomes v17/, one self-contained page per minor — what it changed, what breaks, and its own upgrade checklist:

page	lines
v17/index.mdx	199
v17/17-0.mdx	1,919
v17/17-1.mdx	720
v17/17-2.mdx	377
v17/17-3.mdx	783
v17/17-4.mdx	449

Sidebar: Releases > v17 > [v17, 17.4.0, 17.3.0, 17.2.0, 17.1.0, 17.0.0].

The filenames are dotless on purpose. They first landed as 17.0.mdx … 17.4.mdx and "Check Documentation Links" went red with 20 File not found errors, all of them /docs/releases/v17/17.N. Reproduced against the pinned lychee 0.24.2 with the workflow's own argv and isolated in a three-link fixture:

/docs/t/17.3   (17.3.mdx exists)  -> ERROR  File not found
/docs/t/17-3   (17-3.mdx exists)  -> OK
/docs/t/plain  (plain.mdx exists) -> OK

--fallback-extensions mdx,md does not fire when the last path segment already contains a dot — lychee reads .3 as the extension and never tries .mdx. It is the filename shape, not the split, that the checker cannot follow, so the slug drops the dot. Frontmatter titles are untouched, so the sidebar still reads 17.0.0 … 17.4.0 and the slug is invisible to readers.

Content is conserved. Every line of the old body appears in exactly one new file, verified by set difference — that check caught the ## Upgrade checklist section intro (22 lines, including the callout recording that only the 17.3.0 list was written against a measured upgrade) being dropped; it now lives on index.mdx, linked from each minor. The ### 17.x.0 checklist headings are kept verbatim, so their #1730-style anchors survive the move.

The rc.0 … rc.6 archive is deleted — 1,688 lines, 30% of the old page, describing changes between release candidates of a version that shipped 2026-08-14, all of it contained in the shipped 17.0.0. "When did X change during the rc train" is a changelog question; 17.0.0's page now says so where the archive used to be linked.

17.4.0 — published with no section anywhere

17.4.0 went out 2026-09-09 and releases/index.mdx already named it the current series, but no page carried it.

v17/17-4.mdx is a machine draft and says so at the top. It was built by de-duplicating the 396 changesets that make up 17.4.0 across all 61 package CHANGELOG.md files — a changeset that bumps six packages appears once, not six times — split into 35 carrying a breaking marker, 140 other minor entries, and 221 patch entries reported as counts rather than enumerated.

It carries the same section shape as its siblings so a reader lands where they expect, but only the shape is finished. The two sections no mechanical pass can produce say so where they stand rather than being filled with a guess:

• Highlights — a judgement about audience, not a transformation of the entries.
• Upgrade checklist — a walked route; nobody has walked 17.3.0 → 17.4.0.

The Console section names the pin endpoints it can measure (00d3f09c500c → 53ded82bf7a4, bumped by 30b09907) and states plainly that the intermediate bumps are not enumerated, because this checkout's .objectui-sha history does not carry them.

⛔ Deciding what is user-facing is the maintainer's judgement at release time. This page is raw material for that pass, not a substitute for it.

Three gates learn the second layout — none is weakened

check-release-notes (owns page existence) and check-release-page-status (owns what the page says) now accept either v<major>.mdx or v<major>/index.mdx. Neither layout is deprecated, and no baseline and no exception list is introduced — v16 and earlier stay flat and keep passing unchanged.

check-release-section-coverage is the third, and it is the one this PR would otherwise have quietly blinded. It looked only for a flat page, so after the split it printed (v17: … skipped) and then reported "2 GA major(s) in scope (v16, v17); every one has a heading on its major's release page" — naming v17 as covered while asserting nothing about it. Its source justifies that skip explicitly by the two sibling gates going red on the same fact, and this PR taught both of those the folder layout, so the justification was gone. It now reads either layout, taking the folder as one corpus: "some heading names this minor" is a property of the major's prose wherever it is written, and moving ## What's new in 17.1.0 from line 3475 of one file to line 5 of another is not a coverage change.

Proven to measure rather than merely to stop printing "skipped": with every heading naming the 17.4 series mutated away, the gate reports the finding against content/docs/releases/v17/ and exits 0 advisory / 1 --strict. Its 50-case self-test is unchanged and still passes. (A first mutation attempt on 17.2 wrongly passed — 17-3.mdx carries a heading that mentions 17.2.0 in passing. That looseness is pre-existing: the old flat page contained the same heading.)

Two generated artifacts follow their files

scripts/docs-audit/handwritten-docs.json is generated output — the audit scope, derived as content/docs/**/*.mdx minus the generated references, with hand-editing rejected by the gate whatever the contents. check:docs-audit-scope went red naming both directions of the drift (one listed path gone, six real pages unlisted); regenerated with the gate's own --write, and the diff is exactly those six for that one. Left unfixed, a "FULL audit" would have called itself full while skipping every v17 page, and an agent pointed at the dead path would report "0 fixes" — indistinguishable in the summary from a page read and found accurate.

role-word-baseline.json records a pure relocation: one row, path only, content/docs/releases/v17.mdx: 2 → v17/17-0.mdx: 2. Count unchanged, nothing else re-baselined in the same stroke. One reserved word appearing in a changeset's own headline is elided in 17-4.mdx with the elision stated inline, rather than silently rewriting a verbatim quote.

upgrading.mdx follows the checklist links to their new pages and gains a 17.4.0 row that says plainly its checklist is not written.

Verification

gate	result
Check Documentation Links (pinned lychee 0.24.2, workflow argv)	2,152 links, 0 errors — was 20
check-docs-audit-scope	exit 0
check-release-notes · check-release-page-status	exit 0 — both GA majors in scope
check-release-section-coverage (live + 50-case self-test)	exit 0, and observed going red under mutation
check-role-word · check-doc-anchors · check-docs-single-h1	exit 0
check-doc-authoring · check-docs-image-tag · check-docs-redirects	exit 0
check-release-index-currency-sync · check-quick-reference-counts	exit 0
check-corpus-claim-drift · check-published-readme-links · check-org-identifier	exit 0

Content conservation was verified by comm over the sorted old body against the sorted new files; the only line that does not appear verbatim is the one intra-page anchor deliberately rewritten to point across files. An anchor audit over the split files reported 0 broken intra-page links.

skip-changeset: the diff publishes nothing from any released package (content/docs/** and four files under scripts/).

🤖 Generated with Claude Code

https://claude.ai/code/session_016M1gHPfToXY4sUdzsD2CHa

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json f6b7c53db7b65bbfb019750efb4e545470b0c2b7 → packageMentionDocs.