docs: new `content/docs/upgrading.mdx` in the Build group — state both upgrade halves and give the per-major checklists a door

[os-zhuang]

Card 02 of the deployment restructure. The highest-value card in the set — the only one that fixes a defect users hit today, and independent of every other card in the group.

Maintainer rulings, 2026-08-15: 「元数据应用需要升级，平台也需要升级」; on placement, 「放进 Build 组（应用开发者本来就在那）」; and on shape, a single page, not a directory (see Shape below).

The defect

The two upgrade lifecycles are never distinguished anywhere in the docs. They run on separate clocks:

	Platform runtime	Metadata app
Ships as	Docker image	compiled artifact (dist/objectstack.json)
Versioned by	our release train (17.0.0)	your own catalog
Upgrade cadence	ours	yours
Upgrade action	move the image tag	os migrate meta + republish

The hardest evidence is content/docs/deployment/cli.mdx:821, which calls os migrate meta --from 16 "the metadata half of the upgrade". The docs already know there are two halves. The other half is written down nowhere, and no page places them side by side.

The second defect this closes

The v17 upgrade checklist — 66 actionable bullets, correctly written for metadata app authors (allowExport, sharedWith.type: 'group' → 'team', RLS priority, agent.tools[] → skills) — sits at line 3270 of a 3691-line page, 88% down. Nothing links to it: the first 105 lines of v17.mdx never say "upgrade" except about semver caret ranges, and content/docs/releases/index.mdx offers no entry point. releases also sits in the Platform sidebar group beside kernel and protocol — the wrong neighborhood for the audience it is written for. That mismatch is why this page goes in Build.

Cross-version gap: each release page's checklist has only a ### <major>.0.0 subsection, so upgrading v15 → v17 means reading v16's and v17's and merging them by hand. Mechanically os migrate meta --from <current major> already accumulates across majors — the good news the docs never tell anyone. Say it.

Shape: one page, not a directory

Create content/docs/upgrading.mdx and list "upgrading" in the Build group of content/docs/meta.json (after api, or argue a better slot).

The six existing Build entries are all directories, but that is not a requirement — build-without-code is a single .mdx listed directly in the root nav, so the single-page form is supported and already in use. The content here is one fork plus two halves plus links out: roughly one page. A directory for one page is speculative structure, and under the startup-scope principle every published page is a standing obligation. Promoting a page to a directory later is a cheap migration (one redirect); an empty shell is not free. Do not create a folder.

If while writing you measure that the content genuinely does not fit one page, stop and report rather than silently expanding to a directory — that is a structural decision, not an implementation detail.

What the page must answer, in order

1. Which upgrade are you doing? The fork, stated before anything else.
2. Platform runtime — moving the image tag, what the boot does when metadata and runtime disagree, when a platform move forces an app move.
3. Metadata app — os migrate meta --from <major>, the validate/publish/install loop, and that one command accumulates skipped majors.
4. Per-major specifics — link out to each release page's Upgrade checklist. Link, do not copy. Those checklists are release-owned and compiled at release time (CLAUDE.md forbids editing content/docs/releases/ outside a dedicated docs-only PR). Duplicating 66 bullets creates a second copy that will silently rot — which is the exact failure class the v17 work just cleaned up.

Do not edit anything under content/docs/releases/. Do not edit content/docs/deployment/ — cards 01/03/04/05 own that directory.

Sources (read; do not trust this summary)

• content/docs/deployment/cli.mdx — the os migrate meta sections, roughly lines 777–860
• content/docs/releases/v17.mdx — the ## Upgrade checklist section, for the shape of what you are linking to
• content/docs/deployment/self-hosting.mdx:85 — "Upgrades are atomic: replace the artifact file and restart", currently the section's only upgrade sentence, scoped to one systemd option
• content/docs/references/kernel/package-upgrade.mdx — a different concept (app-package upgrade). Decide whether it needs a disambiguating link and say either way.

Independence

Touches content/docs/meta.json (root) and one new file. No overlap with cards #8904, #8910, #8911; card #8913 edits content/docs/deployment/meta.json, a different file. Safe to run in parallel.

Docs-only, skip-changeset.

[os-project-manager]

Claim — os-dev agent starting work on this card.

• Session ID: session_011RB4waLuNbdruCo6X9oobm
• Branch: claude/issue-8909-upgrading-page
• File surface: content/docs/upgrading.mdx (new) + content/docs/meta.json (one line)

Will not touch content/docs/releases/ or content/docs/deployment/ (cards #8910 / #8911 hold those concurrently).

---

Generated by Claude Code

[os-project-manager]

{
 "issue": 8909,
 "status": "done",
 "branch": "claude/issue-8909-upgrading-page",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8964",
 "premise_still_valid": true,
 "summary": "Added content/docs/upgrading.mdx and listed it in the Build group of the root content/docs/meta.json after `api`. The page states the fork first (platform runtime vs metadata app, as a table), then the runtime half (image tag move, what the boot does on schema drift, and the one-major-wide load-time conversion window that decides when a platform move forces an app move), then the metadata half (`os migrate meta --from N`, the protocol-10 support floor, and the fact that semantic changes are reported as to-dos and never auto-applied), then links out to every release page's Upgrade checklist. One page, no directory: the content fit comfortably, so no structural escalation was needed. A third file, .claude/workflows/docs-accuracy-audit.js, is in the diff because check:docs-audit-scope derives its ALL_HANDWRITTEN list from content/docs and goes red naming any unregistered new page; regenerated with the gate's own --write, one line. NOTE FOR THE PM: the skip-changeset label was already applied by repo automation before I could write it, alongside `documentation` — I read the labels back rather than writing a bare set, which would have clobbered `documentation`. Verified list: [documentation, skip-changeset], and Check Changeset was still in_progress at that point, so the label preceded the job. No check on the PR has a failure conclusion.",
 "tests": "Docs-only change; no unit tests apply. Gate union re-run AFTER the final commit at dfbf789cc with a clean tree, all seven green: check:nul-bytes, check:role-word, check:release-notes, check:docs-audit-scope, check:doc-authoring, check:skill-frame-sync, check:doc-formula-expressions. The last three were NOT in the dispatch list — re-deriving with `node scripts/pm/dispatch-gates.mjs` against my actual changed paths surfaced them via the .claude/ edit, and I ran them. check:role-word is a ratchet: green at head with no baseline change (the new page uses none of the reserved vocabulary; confirmed by direct grep too). check:docs-audit-scope was red before the regeneration and green after — that red is the evidence the third file was mandatory, not scope creep. Two toolchain notes: check:doc-formula-expressions first failed on a missing @objectstack/formula/dist in the fresh worktree (built the closure with `pnpm --workspace-concurrency=2 --filter '@objectstack/lint^...' build`, then green), and my first build attempt used `--concurrency=2` after the filter, which pnpm forwarded to tsup and broke it — the documented flag trap. Heavy commands ran under flock on /tmp/os-heavy-verify.lock. Beyond the gates I compiled the page through @mdx-js/mdx directly (OK, 14682 chars) since MDX parses a bare angle bracket before a letter as JSX, and CI's `Check Documentation Links` passed, which exercises the seven release-checklist anchors. PREMISE VERIFICATION, both clauses hold: cli.mdx:821 does call `os migrate meta --from 16` 'the metadata half of the upgrade' (verbatim at that line); and the accumulation claim is true — confirmed in source (composeMigrationChain filters MIGRATION_MAJORS to `m > fromMajor && m <= toMajor`, applyMetaMigrations folds each step in one pass) and then measured against the real registry: --from 16 -> [17], --from 15 -> [16,17], --from 14 -> [15,16,17], --from 12 -> [13,14,15,16,17], and from=9 -> MigrationFloorError naming the floor of 10.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #8966 (finding, unassigned, no pm:queue): `releases` sits in the Platform nav group beside kernel and protocol, while releases/index.mdx explicitly declares every release page 'written for third-party developers' — an audience/placement mismatch this card names but resolves a different way (by putting the new door in Build). Recorded for the restructure round to grade; #8913 edits a different meta.json and does not cover it."
 ]
}

Two things worth the PM's eye beyond the JSON:

1. The card understated os migrate meta. It is not "run one command and you are done": applyMetaMigrations applies only 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 the opposite impression would be a false promise and it is exactly why the per-major checklists still matter. This strengthens the card's thesis rather than weakening it.

2. package-upgrade.mdx disambiguation: yes, one-directional. It is a genuinely different concept (upgrading an installed package inside a deployment — pre-check / snapshot / execute / rollback), so upgrading.mdx closes with a short "Not this page" section pointing at it. I deliberately did not add a reciprocal link: that file carries an AUTO-GENERATED — DO NOT EDIT banner and is regenerated from the spec source, so the edit would be silently overwritten. If a back-link is wanted it has to come from the generator.

Cosmetic, no action needed: the PR body carries the attribution footer twice — I wrote one and the platform appended another at create time. I left it rather than re-editing, since re-writing the body would re-run the sanitizer over the stored generic-bearing code blocks for no benefit.

---

Generated by Claude Code