docs(deploy): rewrite the Deploy section for the commercial runtime

[os-zhuang]

Fixes#59

The four Deploy pages taught a licence-free, build-it-yourself path that cannot work. docker.mdx told readers to clone this repository and run docker build against a Dockerfile that does not exist here, and published a moving-tag table for an image that is not distributed that way. Across all four pages, licensing appeared zero times — on a product whose walled postures refuse to boot without a licence. And air-gapped.mdx was reverse-wrong: it told readers to leave the cloud-posture setting unset "to run fully offline", when unset resolves to the public control plane.

Rewritten from the deployment artifacts that ship with the release, rather than reconciled with the old story. Previously published images are not referenced anywhere.

What the pages now carry

• Digest pinning, with the reason: a tag can be re-pointed, so a routine pull can swap the running version with no deployment event and no way to prove afterwards what ran. Keeping the previous digest is the rollback.
• Licence on the happy path — what an unlicensed single-organization deployment does (Community behaviour, nothing bricks), and what an unlicensed multi-organization deployment does (exits at startup). Plus the two decisions a walled deployment must declare before it will start.
• Air-gap as a licence mode. An air-gap licence is issued offline and verified locally against a key embedded in the image; you cannot reach that state by unplugging the network.
• Refused at startup, not "not recommended." The supported licence and cloud-posture combinations are given as a table with outcomes, including the impossible pairing (an online licence with no control plane), and why the runtime refuses early instead of failing later while blaming the licence.
• Unset is not "off" — its own heading on the air-gapped page, since that is the sentence this card was filed over.
• Multi-node states what becomes mandatory: the cluster driver plus one shared secret key, identical on every replica — replicas that mint their own would diverge, so the runtime refuses to start instead.
• Supply-chain verification in the production path: signature, SBOM and provenance, with what each of the three actually answers.

Content boundary

The pages carry the decision shape and point at the release's deploy bundle for anything a customer copies verbatim. There is no prose copy of an environment template here, so there is nothing to drift — that is how the previous pages got into this state. The exact registry reference, digest and verification commands come with the release, which is what versions them.

kubernetes.mdx opens by saying plainly that no chart or manifests ship, and reframes as the properties any orchestrator must preserve — migration ordering, probe endpoints, identical secret material, deployment-wide licence posture.

Locales

The six stale translations of each rewritten page are deleted (24 files). Fumadocs falls back to English when a translation is missing, so deleting yields correct English, while leaving them would keep rendering the retired story. Verified in the browser: /zh-Hans/docs/deploy/air-gapped now serves the new English page.

AGENTS.md

Also in scope on this card: the Locale conventions section described en + cn with .cn.mdx siblings, while the site defines seven BCP 47 tags and uses zh-Hans. A .cn.mdx file never renders and raises no error, which is the worst failure mode a translation can have — so the correction says that explicitly. Same pass, same defect class: the "Where things live" table pointed at apps/docs/lib/homepage-i18n.ts, which no longer exists, and the translation workflow now says a rewrite must delete the siblings it invalidates.

Verification

All at commit c5ba923, the head of this branch.

• pnpm run type-check in apps/docs — clean.
• pnpm run build — Compiled successfully, 740/740 static pages generated, no MDX errors.
• Browser, headless Chromium against next start: all four pages render with the expected headings; the Deploy sidebar order matches meta.json exactly (index, docker, kubernetes, air-gapped) on every page; /zh-Hans/docs/deploy/air-gapped falls back to the new English content; every outbound link target answers 200; an unknown Deploy path still 404s (control).
• Licensing mentions per page went from 0 to 40 / 57 / 35 / 86.

One console error appears on every page, including untouched ones — a pre-existing site-wide React hydration warning, filed separately as #61 rather than absorbed here.

Out of scope, filed

• Seven pages outside Deploy still document the retired runtime env contract (OS_ARTIFACT_FILE, OS_BUSINESS_DB_URL, OS_CLOUD_API_KEY, OS_DATABASE_DRIVER) #60 — seven pages outside Deploy still document the retired env contract, reference/environment-variables.mdx worst among them.
• Every docs page throws React hydration error #418 in the browser console #61 — the hydration error above. Referenced here as observations only; neither is addressed by this PR.

---

Generated by Claude Code

[os-zhuang]

Review: accept. Marked ready.

Verified against branch c5ba923 directly, not against the PR description.

The four required properties

	before	after
licence mentioned across the four Deploy pages	0	10 / 16 / 6 / 24 (matching lines)
retired-image traces — moving tags, tag table, git clone + docker build	present	gone
«Leave OS_CLOUD_URL unset to run fully offline»	present	gone
stale locale siblings of rewritten pages	24 live	deleted

The line count above measures matching lines; the author counted occurrences (40/57/35/86). Both are right — no discrepancy.

The content boundary held

All four pages point at the release's deploy bundle rather than reproducing it. The one OS_…= line is not a copyable value but a shape with placeholders, teaching digest-vs-tag:

OS_EE_IMAGE=<the registry reference from your release>@sha256:<64 hex characters>

⇒ That distinction is the whole point of this rewrite. The templates ship with the release and are covered by tests there; prose copies here have nothing pinning them, which is precisely how the previous four pages drifted into documenting a product that no longer exists.

Browser verification was real, and it verified the right things

The repo's own rule is that UI changes get exercised in a browser. Done — headless Chromium against a production build, and notably it measured the things that could silently be wrong:

• all four pages 200 with the expected headings (air-gapped H1 «Air-gapped Deployment», first H2 «Air-gap is a licence mode»);
• sidebar order matches meta.json on every page;
• /zh-Hans/, /ja/, /de/ variants return 200 and serve the new English ⇒ the deletions produce fallback, not 404s. ⚠️ This is the assertion that matters most about deleting translations, and it was measured rather than assumed;
• /docs/deploy/nope → 404 as a control, so "200" means something;
• every outbound link target answers 200.

pnpm build: 740/740 static pages, no MDX errors. Type-check clean.

The hydration error was handled correctly

A React #418 console error fires on every page — and it was measured on untouched pages (/docs/architecture, /docs/quickstart) on the same build to establish it as pre-existing, then filed as #61 rather than absorbed into this change or quietly ignored. ⇒ Correct on both counts: not adopted, not hidden.

Five open questions go to the maintainer unanswered — deliberately

Each is a rule the author could not confirm from a shipped artifact and therefore did not write. ⛔ I am not filling them in, and neither should a follow-up PR without an artifact to point at. The most consequential:

An air-gap licence expires — signature and expiry resolve locally at every boot — and no artifact documents a renewal path. An expiring licence with no documented renewal is a support call with a deadline attached.

Also open: whether Kubernetes is a supported shape at all (no chart, no manifests in the bundle — only Compose, so the page now describes «properties any orchestrator must preserve» and claims no support); how an air-gapped site is supposed to get the image across the boundary (the bundle documents a registry login a disconnected site cannot perform); and whether air-gapped in-product AI is supported. The old os package install … air-gap instruction was deleted rather than carried, since nothing in the artifacts supports it.

⇒ Removing an unverifiable instruction is the correct trade here. This card exists because plausible-but-unverified deployment prose was published once already, and readers followed it.

Follow-up already filed

#60 — seven pages outside Deploy still document the retired runtime env contract, and reference/environment-variables.mdx describes OS_CLOUD_URL as merely a marketplace switch, which now contradicts the rewritten air-gapped page. That contradiction is live the moment this merges, so #60 is the next dispatch rather than a someday item.

No changeset applies — this repo has no changeset gate.

---

Generated by Claude Code