docs(deployment): rewrite the section index around the two lifecycles and re-order `meta.json` — lands last

[os-zhuang]

Blocked-by: #8904
Blocked-by: #8909
Blocked-by: #8910
Blocked-by: #8911

Card 05 — the keystone of the deployment restructure, and deliberately the last to land. Maintainer ruling, 2026-08-15: restructure the section around the two lifecycles.

⛔ Why this one waits

The index is the only page whose correctness depends on every other page already being where it claims. Writing it first creates a window where the section's front door describes a structure the repo has not reached — which is precisely the defect class that produced #8882 (the v17 release page was compiled for a state that had not landed, and shipped saying the release had not happened). Do not repeat it one directory over.

All four blockers must be merged, not merely approved, before this starts. Re-read every page on the merged ref: the four cards ahead of this one move content between pages, and this card's job is to describe where it ended up.

The defect

content/docs/deployment/index.mdx (183 lines) is titled "Deployment Modes" and forks on venue:

Mode	Runs from this repo	Environment selection	Typical use
Local example	Yes	one active OS_ENVIRONMENT_ID	framework dev
Standalone app	Yes	one compiled artifact	self-hosted backend
Cloud-managed environment	runtime seams only	Cloud control plane	SaaS

That is a where do you host it fork. A reader arrives with a lifecycle in hand instead:

• Axis A — platform runtime. "I operate ObjectStack." Ships as a Docker image, versioned by our release train, upgraded on our cadence.
• Axis B — metadata app. "I build an app that runs on it." Ships as a compiled artifact, versioned in your catalog, upgraded on yours.

The two are genuinely independent — a deployment can move from platform 16 to 17 without touching its app, and publish twelve app versions without moving the platform. Venue (Docker / Compose / Kubernetes) is a detail inside Axis A, not a peer of it.

Scope

• Rewrite content/docs/deployment/index.mdx as the lifecycle fork. The existing local/standalone/cloud content is not all wrong — local-vs-cloud environment selection is real and still needs saying — but it belongs under an axis, not as the top-level split.
• Re-order content/docs/deployment/meta.json to match: Axis A pages, Axis B pages, then shared reference (cli, environment-variables, troubleshooting).
• Point Axis B readers at the new content/docs/upgrading/ section (docs: new content/docs/upgrading.mdx in the Build group — state both upgrade halves and give the per-major checklists a door #8909), which lives in the Build group by maintainer ruling. This is the one cross-group link that makes the split navigable — an app developer reading the deployment index must be able to reach the upgrade path from here.

Page assignment as proposed (verify each against the merged tree; disagree in the PR if a page has moved):

• Axis A — self-hosting, production-readiness, backup-restore, tenancy-modes, single-project-mode
• Axis B — publish-and-preview, validating-metadata
• Reference — cli, environment-variables, troubleshooting

cli.mdx is 1398 lines of which ## Commands spans 68–1283 — 87% is a command reference. It belongs to neither axis. Cross-link it from both; do not split it, and do not let it become an Axis A page by default.

single-project-mode (111 lines) is a candidate to fold into self-hosting later. Not this card — flag it in the PR if the merged state makes the case stronger, and it becomes its own follow-up.

Docs-only, skip-changeset.

[os-zhuang]

Correction to this card's cross-reference. The body says to point Axis B readers at "the new content/docs/upgrading/ section". #8909 has since been narrowed to a single page, content/docs/upgrading.mdx — not a directory.

Maintainer's challenge, 2026-08-15: 「content/docs/upgrading/ 需要创建一个文件夹吗？以后准备写很多内容吗」. It was right — I had proposed a directory by pattern-matching the six Build-group neighbors, all of which are directories, rather than by measuring the content. build-without-code is a single .mdx listed directly in the root nav, so the single-page form is supported and already in use, and the content is roughly one page.

Nothing else in this card changes: the link target is /docs/upgrading either way. Verify the final shape on the merged tree when this card starts — #8909 is instructed to report rather than silently expand if the content turns out not to fit one page.

---

Generated by Claude Code