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

* docs(deployment): rewrite the section index around the two lifecycles

The deployment index forked on venue ("Deployment Modes": local / standalone /
Cloud-managed). Readers arrive with a lifecycle in hand instead: they are either
operating the platform runtime (a Docker image on our release train) or shipping
a metadata app (a compiled artifact in their own catalog). The two are
independent — a deployment can move platform majors without touching its app,
and publish a dozen app versions without moving the platform.

The index now forks on that, and venue (Docker / Compose / Kubernetes / Cloud)
is a detail inside the platform-runtime half rather than a peer of it. The
local-vs-cloud environment-selection content survives as "how many environments
one runtime serves", pointing at the canonical resolution order instead of
carrying a second copy of it. meta.json is re-ordered to match: platform-runtime
pages, then app pages, then the shared reference (cli, environment-variables,
troubleshooting), which belong to neither.

Axis B readers are pointed at /docs/upgrading (a single page in the Build group,
not a directory) — the one cross-group link that makes the split navigable.

Also updated the pointers this rewrite invalidated: the inbound anchor
/docs/deployment#environment-variables (that section is gone; retargeted to the
self-hosting page that carries the same OS_SECRET_KEY guidance) and five "Deployment
Modes" link labels naming the page's old title and old structure.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011RB4waLuNbdruCo6X9oobm

* docs(deployment): restore the contiguous "one per line" phrase in the NDJSON note

packages/cli/test/cloud-login-json-ndjson.e2e.test.ts pins the #6730 NDJSON
exception in three places, one of which is this page: it asserts /NDJSON/,
/one\s+per\s+line/i and the /docs/deployment/cli#os-cloud-login link all appear
in content/docs/deployment/index.mdx, so a script author meeting `os cloud login`
in the publish flow finds the declaration without going to the CLI reference.

The index rewrite kept every fact — NDJSON named, the link kept, "parse line by
line" kept — but spelled the middle one "one compact JSON document per line",
which breaks the adjacency the second regex needs. The sentence now reads
"emits NDJSON: compact JSON documents, one per line." Meaning unchanged,
framing and placement unchanged, pin satisfied.

The test lives in packages/cli, so a docs-only PR's affected-only CI never runs
it; this surfaced in the merge queue's full suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011RB4waLuNbdruCo6X9oobm

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

content/docs/api/environment-routing.mdx

@@ -125,5 +125,5 @@ one, so they are intentionally excluded from data-plane resolution.
 ## Related
 
 - [Single-Environment Mode](/docs/deployment/single-project-mode)
-- [Deployment Modes](/docs/deployment)
+- [Deployment Overview](/docs/deployment)
 - [Client SDK](/docs/api/client-sdk)

content/docs/deployment/environment-variables.mdx

@@ -63,7 +63,7 @@ read at startup unless noted otherwise. Boolean variables accept `true` / `false
 
 | Variable | Type | Default | Description |
 |:---|:---|:---|:---|
-| `OS_SECRET_KEY` | string | — | 32-byte master key (64 hex chars or base64) for `sys_secret` encryption — encrypted settings, `secret` fields, datasource credentials. **Required** for containerized or multi-node deployments; on a single durable host `os start` mints and persists a dev key instead. See [Deployment Modes](/docs/deployment#environment-variables). |
+| `OS_SECRET_KEY` | string | — | 32-byte master key (64 hex chars or base64) for `sys_secret` encryption — encrypted settings, `secret` fields, datasource credentials. **Required** for containerized or multi-node deployments; on a single durable host `os start` mints and persists a dev key instead. See [Self-Hosted Deployment](/docs/deployment/self-hosting#the-minimum-viable-production-environment). |
 | `OS_DEV_CRYPTO_KEY` | string | — | Development convenience crypto key, consulted after `OS_SECRET_KEY`. Do not use in production. |
 | `OS_CLUSTER_DRIVER` | string | `memory` | Cluster coordination driver id. When set to anything other than `memory`, the runtime treats the deployment as multi-node (and requires `OS_SECRET_KEY`). Non-memory drivers are opt-in sibling packages (e.g. `redis` via `@objectstack/service-cluster-redis`) — see [Cluster](/docs/kernel/cluster). |
 | `OS_REDIS_URL` | url | — | Connection URL passed to a non-memory cluster driver (e.g. `OS_CLUSTER_DRIVER=redis`). |

content/docs/deployment/index.mdx

@@ -2,15 +2,15 @@
   "title": "Deployment & Operations",
   "pages": [
     "index",
-    "cli",
-    "validating-metadata",
     "self-hosting",
-    "backup-restore",
     "production-readiness",
+    "backup-restore",
+    "tenancy-modes",
+    "single-project-mode",
     "publish-and-preview",
+    "validating-metadata",
+    "cli",
     "environment-variables",
-    "single-project-mode",
-    "tenancy-modes",
     "troubleshooting"
   ]
 }

content/docs/deployment/meta.json

@@ -218,6 +218,6 @@ boot-time schema-drift policy, against a local file.
 - [Artifact-pinned boot](/docs/deployment/self-hosting#artifact-pinned-boot-os_artifact_url) — the operational detail for `OS_ARTIFACT_URL`: schemes, integrity pinning, cache behaviour, pre-signed URLs
 - [CLI reference](/docs/deployment/cli)
 - [Packages](/docs/plugins/packages)
-- [Deployment Modes](/docs/deployment)
+- [Deployment Overview](/docs/deployment)
 - [Environment Variables](/docs/deployment/environment-variables)
 - [Environment-Scoped Routing](/docs/api/environment-routing)

content/docs/deployment/publish-and-preview.mdx

@@ -11,7 +11,7 @@ platform publishes an official runtime image on every release, and Compose and
 Kubernetes are shapes of that same path rather than alternatives to it. Bare
 Node.js under systemd is the minority path, kept for hosts where a container
 runtime is not available or not permitted. It assumes you have read
-[Deployment Modes](/docs/deployment).
+[Deployment Overview](/docs/deployment).
 
 The deployment model is deliberately simple:
 
@@ -430,7 +430,7 @@ Disable with `OS_MCP_SERVER_ENABLED=false`. See
 ## Related
 
 - [Backup & Restore](/docs/deployment/backup-restore) — what to back up, and the restore drill
-- [Deployment Modes](/docs/deployment) — the map of local / standalone / Cloud
+- [Deployment Overview](/docs/deployment) — the two lifecycles this section is organised around, and which pages belong to each
 - [`os start` reference](/docs/deployment/cli#os-start) — every flag and env var
 - [Environment Variables](/docs/deployment/environment-variables) — the full catalog
 - [Troubleshooting & FAQ](/docs/deployment/troubleshooting)

content/docs/deployment/self-hosting.mdx

@@ -17,8 +17,11 @@ This is the mode used by:
 - `createStandaloneStack()` / `createDefaultHostConfig()` in
   `@objectstack/runtime`
 
-Use [Deployment Modes](/docs/deployment) when you need to publish to an
-ObjectOS Cloud control plane or test environment-scoped routing.
+Need more than one environment? [Publish, Versioning &
+Preview](/docs/deployment/publish-and-preview) covers publishing to an ObjectOS
+Cloud control plane, and [Environment-Scoped
+Routing](/docs/api/environment-routing) covers resolving an environment per
+request.
 
 ---
 
@@ -107,5 +110,5 @@ environments, provision databases, or mount a control plane.
 ## Related
 
 - [Environment-Scoped Routing](/docs/api/environment-routing)
-- [Deployment Modes](/docs/deployment)
+- [Deployment Overview](/docs/deployment)
 - [CLI reference](/docs/deployment/cli)