docs: add upgrading.mdx stating both upgrade halves and linking the per-major checklists

[os-project-manager]

Fixes#8909

Adds content/docs/upgrading.mdx and lists it in the Build group of the root content/docs/meta.json, after api.

The defect this closes

The two upgrade lifecycles — platform runtime and metadata app — run on separate clocks and were never distinguished anywhere in the docs. content/docs/deployment/cli.mdx:821 already calls os migrate meta --from 16 "the metadata half of the upgrade"; the other half was written down nowhere, and no page placed them side by side. The v17 upgrade checklist (66 actionable bullets, correctly written for app authors) sits at line 3270 of a 3691-line page with nothing linking to it.

Shape

One page, no directory, as the card ruled. build-without-code.mdx is the existing precedent for a bare .mdx listed directly in the root nav. The content measured out at roughly one page — fork, two halves, link table, disambiguation — so no structural escalation was needed.

Verified against source, not prose

The card's load-bearing good news is that os migrate meta --from N accumulates across skipped majors. I confirmed it in the source rather than the docs, and then measured it:

composeMigrationChain (packages/spec/src/migrations/chain.ts) filters MIGRATION_MAJORS to m > fromMajor && m <= toMajor and applyMetaMigrations folds every resulting step in one pass. Probed against the real registry:

--from 16 -> hops [17] (1 step)
--from 15 -> hops [16, 17] (2 steps)
--from 14 -> hops [15, 16, 17] (3 steps)
--from 12 -> hops [13, 14, 15, 16, 17] (5 steps)
from=9 -> MigrationFloorError: the chain's support floor is 10

Both premise clauses hold. Two further facts came out of the same read and are stated on the page:

• The support floor is 10 (MIGRATION_SUPPORT_FLOOR), a release-policy knob, and below it the command refuses rather than half-migrating.
• Semantic changes are never auto-applied.applyMetaMigrations applies the mechanical transforms and reports the non-lossless residue as structured to-dos — measured at 73 to-dos for --from 16 alone. The page says so explicitly, because "run one command and you are done" would be a false promise and it is precisely why the per-major checklists still matter.

The runtime half is likewise sourced: the one-major-wide load-time conversion window (ADR-0087 D2, retired at N+1) is what decides when a platform move forces an app move, and the artifact-pinned boot applies safe/needs-confirm drift while refusing the boot on destructive drift before the port binds.

Link, never copy

Every per-major checklist is linked at its #upgrade-checklist anchor for v9 and v12 through v17 — verified present on all seven pages. Nothing under content/docs/releases/ is touched, and no bullet is duplicated: a second copy would silently rot, which is the failure class the v17 work just cleaned up. content/docs/deployment/ is untouched as well (cards #8910 and #8911 hold those files concurrently).

Disambiguating link: yes

content/docs/references/kernel/package-upgrade.mdx is a genuinely different concept — upgrading an installed package inside a deployment, with its own pre-check / snapshot / execute / rollback lifecycle. It is neither of the two halves, and a reader searching "upgrade" lands on it. The page therefore closes with a short "Not this page" section pointing at it. I did not add a reciprocal link from that file: it carries an AUTO-GENERATED — DO NOT EDIT banner and is regenerated from the spec source, so an edit there would be overwritten.

Third file, and why

.claude/workflows/docs-accuracy-audit.js is regenerated. check:docs-audit-scope derives ALL_HANDWRITTEN from content/docs/, and a new hand-written page that is not registered makes a run that calls itself a FULL audit silently skip it — the gate goes red naming the omission. Produced with the gate's own --write, a one-line addition; not a hand edit.

Gates

Union re-run after the final commit, at dfbf789cc, clean tree:

PASS check:nul-bytes
PASS check:role-word
PASS check:release-notes
PASS check:docs-audit-scope
PASS check:doc-authoring
PASS check:skill-frame-sync
PASS check:doc-formula-expressions

The last three were not in my dispatch list — re-deriving with scripts/pm/dispatch-gates.mjs against my actual changed paths surfaced them via the .claude/ edit. check:role-word is a ratchet and is green at head with no baseline change (the new page uses none of the reserved vocabulary).

Also compiled the page through @mdx-js/mdx directly to confirm it parses (OK, 14682 chars) — worth doing since MDX treats a bare angle bracket before a letter as JSX.

Docs-only; skip-changeset.

Generated by Claude Code

---

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)
objectstack	Ignored		Aug 16, 2026 3:07am