docs: replace the retired runtime env contract on the nine pages outside Deploy

[os-zhuang]

Fixes#60

Nine pages outside deploy/ still documented environment variables the shipped
runtime does not read. reference/environment-variables.mdx was the worst of
them — a reference page is the one a reader treats as the contract — and since
the Deploy rewrite landed it also contradicted a page shipping beside it:
it described the cloud-posture variable as a switch for marketplace features,
while deploy/air-gapped.mdx states it is coupled to the licence mode with
unsupported pairings refused at startup.

How each variable was judged

Every name was checked against the deployment bundle that ships with the
release, and against the runtime and CLI source that reads it. Nothing here is
reconstructed from surrounding prose.

Name	Verdict	Evidence
OS_ARTIFACT_FILE	Read by nothing. Zero occurrences in the runtime, the CLI, or the deployment bundle	Documented on 3 pages as the way to select an app
OS_BUSINESS_DB_URL	Read by nothing. Zero occurrences anywhere	A deployment that set only this had no database configured
OS_CACHE_DIR	Read by nothing. Zero occurrences anywhere	Found outside the card's list, on operate/backup.mdx
OS_PROJECT_ID	No longer read. Documented as an accepted legacy alias	Was true at the release the changelog records; is not true now
OS_ARTIFACT_PATH	Retired — refuses the boot on the runtime image when non-default, naming its replacement	Documented as a supported alternative on 2 pages, including the CLI reference
OS_CLOUD_API_KEY	Not a self-hosted deployment variable. It is the service credential the hosted cloud injects into runtimes it operates, and separately the CLI's publishing bearer	3 pages presented it as the deployment's cloud credential
OS_DATABASE_DRIVER	NOT retired. It is the live driver override	Documented, not removed — the card's premise is wrong on this one name

OS_CLOUD_URL keeps its name and loses its description. It is not a
marketplace switch: it decides whether the deployment has a control plane at
all, it is coupled to the licence mode, unset resolves to the public control
plane rather than to "off", and an ordinary licence paired with no control
plane is refused at startup.

What the reference page is now

Rebuilt around the decisions a deployment actually makes — licence and cloud
posture as a coupled pair, the walled-posture decisions that refuse to default,
multi-node, artifact selection — plus a retired-name table so an inherited
configuration file can be read and corrected rather than merely failing.

Variable names stay, because on a reference page the names are the contract.
The values a customer copies do not: those stay in the release's deploy bundle,
where they can be pinned to a version. That is the same boundary the Deploy
rewrite drew, and the reason neither page will rot.

Rows that could not be confirmed against any shipped artifact are not carried
forward on a guess. They are listed as open questions on the issue rather than
restated with a plausible-sounding description.

Pages changed

Seven from the card: reference/environment-variables.mdx, architecture.mdx,
operate/troubleshooting.mdx, operate/production.mdx, configure/runtime.mdx,
build/packages.mdx, resources/changelog.mdx.

Two found by sweeping the whole content tree rather than stopping at the list:
operate/backup.mdx (OS_CACHE_DIR) and reference/cli.mdx
(OS_ARTIFACT_PATH presented as a working option).

build/packages.mdx was the one page where the card's premise did not hold —
its use of the publishing credentials is correct, so the text is kept and gains
a note about the name collision with the deployment contract.

Two sites were judged historical record rather than current instruction, on
resources/changelog.mdx, and were corrected in place rather than deleted: one
restated without a name nothing ever read, one moved to past tense.

Stale translations of all nine pages are deleted in six locales (54 files).

Verification

Built and driven in a real browser at e4efd5c, the branch head.

• npm run type-check — clean.
• npm run build — 740 static pages generated, no errors.
• Chromium over all nine rewritten pages plus both Deploy pages: every page 200,
  headings and tables render, sidebar order matches reference/meta.json
  exactly, and a deliberately bad path still 404s.
• The locale fallback was measured, not trusted. A deleted zh-Hans
  sibling serves the new English body with localized navigation chrome (17 CJK
  characters, all of them sidebar and link text); the control — a page whose
  translation was kept — still renders 1215 CJK characters of its own
  translated body. Same result for a deleted ja sibling.

One pre-existing finding, not caused by this branch: every default-locale
(unprefixed) page throws a React hydration error in the browser console,
including untouched pages and the Deploy pages. Prefixed-locale routes do not.
Filed separately.

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Review: accept. Marked ready — ⛔ not merged, since merging publishes and this repo has no auto-merge.

Verified against branch e4efd5c directly. 63 files, −7922: 9 English pages modified, 54 locale siblings deleted — and every deletion is a translation. No English content was removed (checked with git diff --name-status, not inferred from the total).

It contradicted the card in two places, and both corrections are right

I verified each against the shipped source rather than taking them:

• OS_DATABASE_DRIVER is not retired.service-cloud/src/boot-env.ts reads it. It was documented rather than deleted.
• build/packages.mdx was already correct. That OS_CLOUD_API_KEY is the publishing identity, not a self-hosted deployment variable — a name collision, not a stale contract. Text kept, collision noted.

Also confirmed independently: OS_ARTIFACT_FILE has zero occurrences across the runtime's apps/ and packages/ — the "set it and it is silently ignored" claim is measured, not asserted.

⇒ A card is a hypothesis. Two of its seven claims were wrong, and the right outcome was to correct them on the record instead of implementing them as written.

The live contradiction is resolved

The reference page now says what the deployment page says:

Unset is not "off". An unset OS_CLOUD_URL resolves to the public control plane… A deployment meant to talk to nobody must say off out loud.

Retired names were kept, not deleted — and that is better

They moved into a Retired names table, framed as "listed here so that a configuration file you inherited can be read and corrected — not so they can be used", each with what to use instead. Deleting them would have left a reader holding OS_ARTIFACT_FILE with no way to discover it is inert. ⇒ The failure mode this card names is a silent one; the fix has to be findable by someone already suffering it.

Two pages beyond the card's list were included (operate/backup.mdx, reference/cli.mdx) — the list came from one sweep and never claimed completeness.

⭐ How the locale fallback was proved — the transferable bit

Deleting a translation is only safe if the site falls back to English, and 200 OK cannot tell you that — a stale translation returns 200 too. So the check counted CJK characters in the article body:

page	article CJK
/zh-Hans/…/environment-variables (sibling deleted)	17 — every one located in nav chrome, not prose
/zh-Hans/docs/quickstart (translation kept, control)	1215

Same shape for /ja/docs/configure/runtime. ⇒ That distinguishes "fell back to English" from "still serving the old translation". A status-code check would have passed either way.

Build 740/740 static pages, sidebar hrefs match reference/meta.json order exactly, bad path 404s as a control, no internal identifiers in pages or PR body.

Five open questions — all the same shape, all left for the maintainer

OS_KERNEL_CACHE_SIZE, OS_KERNEL_TTL_MS, OS_ENV_CACHE_TTL_MS, OS_ARTIFACT_CACHE_TTL_MS, OS_PLATFORM_SSO, OS_RUNTIME_PORT, OS_ORGANIZATION_ID — each occurs only in the hosted distribution and in no shipped artifact. They were removed rather than have their defaults restated from an ungrounded source.

⚠️ If any turn out to be read by the self-hosted image, the fix belongs in the deploy bundle first and the docs second — a default that lives only in a docs page is how this whole class started.

Two judgement calls I agree with: the changelog entry citing a variable name nothing ever read was restated as a capability rather than given an invented name; and OS_ARTIFACT_PATH keeps its "on the ObjectOS runtime image" qualifier, because dropping it would leave a reader whose boot was refused with no way to find out why.

---

Generated by Claude Code