docs(deployment): rewrite the section index around the two lifecycles and re-order meta.json (#8913)

[os-project-manager]

Fixes#8913

Card 05 — the keystone of the deployment restructure. Per the card, every blocker was
verified merged on origin/main by content, not by merge-commit subject, before the
first edit:

Blocker	Content check on origin/main
#8904	no vercel.mdx / ObjectQL-migration page in content/docs/deployment/ (12 files remain)
#8909	content/docs/upgrading.mdx exists, 206 lines; 0 files under content/docs/upgrading/ (positive control: 12 under content/docs/deployment/)
#8910	publish-and-preview.mdx is 223 lines and carries ## The two ways in
#8911	## Docker (official image) — the standard path present in self-hosting.mdx; the ## Option 1 / 2 / 3 peer numbering is gone

Every page name, heading and anchor referenced below was read off that merged tree — the
point of landing this card last.

The rewrite

content/docs/deployment/index.mdx forked on venue ("Deployment Modes": local /
standalone / Cloud-managed). It now forks on lifecycle, because that is what a reader
arrives with:

• The platform runtime — you operate it. Ships as a Docker image on our release train,
  moved on our cadence. Venue (Docker, Compose, Kubernetes, bare Node.js under systemd,
  ObjectStack Cloud) is a bullet list inside this half, not a peer of it.
• Your metadata app — you build it. Compiles to dist/objectstack.json, versioned in
  your catalog, shipped on your cadence.

The old content that was not wrong survives, relocated rather than deleted:

Old section	Where it went
## Local runtime	a bullet under "Where it runs" — a local runtime is a shape of the platform half, with the commands left to Single-Environment Mode and the CLI reference
## Standalone artifact runtime	the app half's compile step, plus the artifact-source precedence under "Where the two meet"
## Cloud-managed deployment	split: the Cloud venue bullet in the platform half, the publish/install mechanics in the app half pointing at publish-and-preview (which now owns them)
## Routing precedence	compressed to a pointer at /docs/api/environment-routing#resolution-order, which carries the identical six-step list and the control-plane exclusion. The index no longer keeps a second copy that can drift
## Environment variables (partial table + two callouts)	the MCP callout is kept; the OS_SECRET_KEY callout is dropped as a third copy — self-hosting.mdx carries both halves of it already ("The minimum viable production environment" for the ephemeral-filesystem case, "Scaling beyond one node" for the multi-node refusal-to-boot case)
## Related	replaced by three in-page tables that name every page in the section and say what it answers

New closing section, "Where the two meet" — the engines.protocol handshake, the
artifact-source precedence (an operator input that selects an app version), and database
drift. These are the three seams where treating the two lifecycles as one goes wrong.

Title changed Deployment Modes to Deployment Overview: "Modes" is the venue fork's own
vocabulary. The new name matches this repo's existing section-index convention (API Overview, AI Overview).

meta.json

Re-ordered to match — platform pages, app pages, then shared reference:

index,
self-hosting, production-readiness, backup-restore, tenancy-modes, single-project-mode,
publish-and-preview, validating-metadata,
cli, environment-variables, troubleshooting

Every assignment was checked against the merged page rather than the card's proposal, and
all ten hold. cli.mdx stays reference by its own measurement — 1398 lines of which
## Commands spans 68–1283 — and is cross-linked from both halves in the "Shared
reference" table, split by which commands serve which lifecycle. It is not split, and it
did not drift into the platform half.

The cross-group link

/docs/upgrading — a single page in the Build group, not a content/docs/upgrading/
section. The card body's wording is stale here and the correction comment on the card is
right; measured again on the merged tree (0 files under that directory). The index links
its two halves individually: /docs/upgrading#the-platform-runtime from the platform half
and /docs/upgrading#the-metadata-app from the app half, which is the navigable form of
the split. No directory was created.

Pointer fixes this rewrite forced (named, with evidence)

Five files beyond the two the card names. Each is a pointer that this change made wrong,
each is mechanical, and all are in the same gate family:

1. content/docs/deployment/environment-variables.mdx — its OS_SECRET_KEY row linked
   /docs/deployment#environment-variables, an anchor this rewrite deletes. Retargeted to
   self-hosting#the-minimum-viable-production-environment, which carries the same
   guidance in the operator's context. Without this check:doc-anchors goes red — it is
   the only inbound anchor into the index in the whole corpus (grep over
   docs/deployment#).
2. content/docs/deployment/self-hosting.mdx (2 lines) — one link label, and one Related
   entry that described the deleted structure verbatim ("the map of local / standalone /
   Cloud").
3. content/docs/deployment/single-project-mode.mdx (2 places) — one Related label, and a
   sentence sending readers to the index "when you need to publish to an ObjectOS Cloud
   control plane", which the index no longer explains; retargeted to publish-and-preview
   and environment-routing.
4. content/docs/deployment/publish-and-preview.mdx (1 line) — Related label.
5. content/docs/api/environment-routing.mdx (1 line) — Related label.

After this, grep -rn 'Deployment Modes' content/ returns nothing.

Deliberately not swept:ui/setup-app.mdx, automation/hook-bodies.mdx and
kernel/index.mdx link the index under labels ("Cloud Deployment", "Deployment &
Operations") that do not name the old title and are no more wrong after this change than
before it. Pre-existing looseness, not created here — recorded as #8984.

Where I disagree with the card

The card asks me to flag single-project-mode folding into self-hosting if the merged
state strengthens the case. It weakens it. After #8911, self-hosting.mdx is 436
lines that are firmly about production infrastructure (Docker, Compose, Kubernetes,
systemd, TLS, health checks). single-project-mode.mdx is about the default boot shape —
pnpm dev, os dev, createStandaloneStack() — and its real subject after this
restructure is environment selection: one active OS_ENVIRONMENT_ID versus a host that
resolves one per request. Folding it into the production page would put local development
inside a production guide. If a follow-up is still wanted, the better shape is a merge with
the environment-routing framing, not with self-hosting. No issue filed — this is the
card's flag-it-in-the-PR path, and the disposition is the PM's.

Round 2 — merge-queue repair (b40e5fefb)

The first head was dequeued on CI_FAILURE: packages/cli/test/cloud-login-json-ndjson.e2e.test.ts
pins the #6730 NDJSON exception in this page as well as in the CLI reference, asserting
/NDJSON/, /one\s+per\s+line/i and the /docs/deployment/cli#os-cloud-login link all
appear in content/docs/deployment/index.mdx.

The rewrite kept every fact the pin protects — NDJSON named, the anchor kept, "parse line
by line" kept — but spelled the middle one "one compact JSON document per line", which
breaks the token adjacency the second regex needs. Repaired by rewording that one clause to
"emits NDJSON: compact JSON documents, one per line." Meaning, framing and placement
unchanged; the rewrite is not reverted.

Verified rather than eyeballed, from the committed state:

state	NDJSON	one per line	anchor	the test
HEAD~1 restored into the tree (pre-fix wording)	true	false	true	1 failed
b40e5fefb (fix)	true	true	true	1 passed, 11 skipped

The pre-fix leg was run by checking the old file out of the committed parent and restored
with git checkout HEAD -- ..., then proven byte-identical
(git hash-object = git rev-parse HEAD:... = 7b1fe377c, git status --porcelain empty).

Swept for the rest of the class rather than fixing only the reported one: of the seven files
this PR changes, content/docs/deployment/index.mdx is the only one any test reads —
the other CLI docs pins target cli.mdx, which this PR does not touch, and no test
references self-hosting, single-project-mode, publish-and-preview,
environment-variables, environment-routing or the section meta.json.

Why PR-side CI could not see it, and the follow-up: @objectstack/cli#test declares no
content/docs input glob, and pnpm check:cross-package-test-inputs nevertheless passes —
the three CLI tests that read these pages seed their paths with
resolve(fileURLToPath(import.meta.url), '..'), a spelling the detector's published list
does not carry, so the read is invisible to the gate and to turbo's affected set. Filed as
#8995 (blocked by #8946, which is editing the same declaration block).

Verification

Gate union re-run after the final commit, at b40e5fefb, clean tree
(git status --porcelain empty), all exit 0:

Gate	Result
pnpm check:doc-anchors	227 internal #fragment links across 396 source files all resolve to a real heading
pnpm check:role-word	43 baselined files, no new occurrences (the ratchet family, re-run at the new head)
pnpm check:docs-audit-scope	audit scope in sync, 178 hand-written docs; 9 release-owned pages read-only
pnpm check:nul-bytes	5938 text files, no raw ASCII control bytes
pnpm check:doc-authoring	376 files clean
vitest run test/cloud-login-json-ndjson.e2e.test.ts -t 'documents the exception where the cloud login step is prescribed'	1 passed, 11 skipped (the spawn-based cases are name-filtered out; they need a built dependency closure and are unrelated to this diff)

Path-derived set (node scripts/pm/dispatch-gates.mjs over the seven changed paths) is
check:docs-audit-scope + check:role-word; check:doc-anchors, check:nul-bytes and
check:doc-authoring were added on top because this change adds cross-page anchor links
and touches only hand-written docs. The CLI pin is not derivable from either source — it
lives inside a test file's readFileSync, which is what #8995 is about.

Additionally, all six changed .mdx files were compiled through @mdx-js/mdx +
remark-gfm (the pipeline fumadocs-mdx uses) at the same commit — all six compile.
Anchors were computed with the workspace's own github-slugger, the same package
fumadocs-core imports, before being written.

Docs-only: no changeset, skip-changeset applied.

---

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 4:47am

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31926481115 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (3/3) — 失败步骤: Run this shard's tests

  �[90mstdout�[2m | src/webhook-secret-at-rest.test.ts�[2m > �[22m�[2mfail-closed and re-arm, extended to headers (#7986 × #7799/#8022)�[2m > �[22m�[2mdrops the subscription rather than delivering it wi
  �[90mstdout�[2m | src/webhook-secret-at-rest.test.ts�[2m > �[22m�[2mfail-closed and re-arm, extended to headers (#7986 × #7799/#8022)�[2m > �[22m�[2mdrops the subscription rather than delivering it wi
  �[90mstdout�[2m | src/webhook-secret-at-rest.test.ts�[2m > �[22m�[2mfail-closed and re-arm, extended to headers (#7986 × #7799/#8022)�[2m > �[22m�[2mre-arms with its headers when the CryptoProvider re
  �[90mstdout�[2m | src/webhook-secret-at-rest.test.ts�[2m > �[22m�[2mfail-closed and re-arm, extended to headers (#7986 × #7799/#8022)�[2m > �[22m�[2mre-arms with its headers when the CryptoProvider re
  �[41m�[1m FAIL �[22m�[49m test/cloud-login-json-ndjson.e2e.test.ts�[2m > �[22mthe exception stays declared, not just implemented (#6730 ruling)�[2m > �[22mdocuments the exception where the cloud login
  

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 1 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)