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)

[os-zhuang]

Found while rewriting the Deploy section (#59). Filed unassigned; not fixed in that PR — the card's scope was content/docs/deploy/.

What is wrong

The Deploy rewrite replaced the retired variable names with the ones the shipped runtime actually reads. The same retired names are still documented on seven other English pages (plus their locale siblings):

Page	Retired name it documents
reference/environment-variables.mdx	OS_ARTIFACT_FILE, OS_BUSINESS_DB_URL
architecture.mdx	OS_CLOUD_API_KEY (as the cloud-connected mode's credential)
operate/troubleshooting.mdx	OS_ARTIFACT_FILE
operate/production.mdx, configure/runtime.mdx, build/packages.mdx, resources/changelog.mdx	one or more of the above

reference/environment-variables.mdx is the worst of them, because it is the page a reader treats as the contract. It also describes OS_CLOUD_URL as merely switching marketplace features on and off. That is no longer what it is: it is coupled to the licence mode, and unsupported pairings are refused at startup — which is now stated on deploy/air-gapped.mdx. A reference page that contradicts the deployment page is worse than one that is merely thin.

Why it matters

OS_ARTIFACT_FILE in particular reads as a working instruction: a reader who sets it gets a runtime that ignores it, with no error pointing at the mistake.

What the fix needs

The authoritative env contract is the deployment bundle shipped with the release, not this repo. Whoever picks this up should read it there first, the way #59 did, and treat any rule that cannot be read from a shipped artifact as an open question rather than inferring it. Stale locale siblings of any rewritten page should be deleted, not translated (Fumadocs falls back to English).

Backlink: #59.

[os-zhuang]

Claiming — dispatching now. The contradiction this card names went live when #62 merged.

Branch: claude/issue-60-retired-env-contract. Base: current main (contains #62).

⛔ No other claim on this card; filed unassigned by the author of #59's PR.

Why this moved to the front

Before #62, reference/environment-variables.mdx was merely stale. Now it disagrees with a page that ships alongside it. It calls OS_CLOUD_URL a switch for marketplace features; deploy/air-gapped.mdx now states that it is coupled to the licence mode and that unsupported pairings are refused at startup.

⚠️ A reference page is the one a reader treats as the contract. When it contradicts the deployment page, the reader has no way to tell which is current — and the reference page's authority makes the wrong one more likely to be believed.

OS_ARTIFACT_FILE is the other sharp edge: it reads as a working instruction, and a reader who sets it gets a runtime that silently ignores it, with no error pointing at the mistake.

Method — the same one that made #59 defensible

1. Read the shipped deployment bundle first for every variable you touch. This repository is not the authority on the runtime's env contract; the release is.
2. Any rule you cannot read from a shipped artifact is an open question, not an inference. ⛔ Do not reconstruct a variable's meaning from the surrounding prose, and ⛔ do not carry a retired name forward "just in case" — report it instead.
3. Delete stale locale siblings of any page you rewrite; do not translate them. Fumadocs falls back to English, so deleting yields correct English while leaving them keeps serving the retired contract. ⚠️ The Deploy section documents a retired open-source edition — rewrite it for the commercial runtime #59 measured that fallback rather than trusting it — do the same for the pages you touch.
4. ⛔ Do not inline values customers copy. Same boundary as The Deploy section documents a retired open-source edition — rewrite it for the commercial runtime #59: decision shape here, copyable configuration in the release bundle.

Scope

The seven English pages named in this card plus their locale siblings. reference/environment-variables.mdx first — it is both the worst offender and the page carrying the live contradiction.

⚠️ If you find retired names on pages not listed here, add them rather than stopping at the list — the list came from one sweep and does not claim completeness.

Verification

This repo requires UI changes to be exercised in a browser. Confirm the rewritten pages render, the sidebar matches meta.json, no page 404s, and the locale variants fall back correctly. If you cannot drive a browser, say so explicitly rather than implying it passed.

⚠️ This repository is public — ⛔ no internal tracker IDs, hostnames, or credentials in the pages or the PR body.

Report back with a structured JSON summary, listing every open question separately.

---

Generated by Claude Code

[os-zhuang]

{
  "issue": 60,
  "status": "done",
  "branch": "claude/issue-60-retired-env-contract",
  "pr": "https://github.com/objectstack-ai/objectos/pull/63",
  "premise_still_valid": true,
  "summary": "The card's core premise held and the live contradiction was real: reference/environment-variables.mdx described the cloud-posture variable as a marketplace switch while deploy/air-gapped.mdx, shipping beside it, states it is coupled to the licence mode with unsupported pairings refused at startup. Every variable was judged against the shipped deployment bundle and the runtime/CLI source that reads it, never from surrounding prose. Verdicts: OS_ARTIFACT_FILE, OS_BUSINESS_DB_URL, OS_CACHE_DIR and OS_PROJECT_ID are read by NOTHING anywhere (zero occurrences in the deploy bundle, the runtime, or the CLI); OS_ARTIFACT_PATH is retired and REFUSES the boot on the runtime image when non-default; OS_CLOUD_API_KEY is the credential the hosted cloud injects into runtimes it operates plus the CLI's publishing bearer, not a self-hosted deployment variable. Two parts of the card's premise are FALSE and were not acted on as written: OS_DATABASE_DRIVER is NOT retired (it is the live driver override, documented rather than removed), and build/packages.mdx was already CORRECT (its OS_CLOUD_URL + OS_CLOUD_API_KEY usage is the publishing identity; the text is kept and gains a note about the name collision). Two pages beyond the card's seven carried the same defect and are included: operate/backup.mdx (OS_CACHE_DIR) and reference/cli.mdx (OS_ARTIFACT_PATH offered as a working option). Two sites on resources/changelog.mdx were judged historical record rather than current instruction and corrected in place rather than deleted. 54 stale locale siblings deleted across nine pages and six locales.",
  "tests": "All at e4efd5c, the branch head and the commit the PR body quotes. (1) `pnpm install --frozen-lockfile` clean. (2) `npm run type-check` (fumadocs-mdx + next typegen + tsc --noEmit) -> 'Types generated successfully', exit 0. (3) `npm run build` -> 'Compiled successfully in 33.8s', 'Generating static pages using 3 workers (740/740) in 8.0s', exit 0. (4) THE DOCS SITE DID RENDER IN A REAL BROWSER: `next start` on port 3111, driven with Chromium (/opt/pw-browsers/chromium-1194) via Playwright 1.56.1. All 9 rewritten pages plus both Deploy pages returned 200 with correct h1/h2 and tables (env-vars page: 9 tables, h2 chain 'The decisions every deployment makes | Licence and cloud posture | Multi-organization deployments | Multi-node | Running a published app | Runtime services | Observability | Pinning a system setting | Retired names | Legacy names'); a deliberately bad path returned 404. Sidebar hrefs matched content/docs/reference/meta.json order exactly (rest-api, objectql, cel, field-types, skills-cli, cli, environment-variables, runtime-capabilities, security). (5) LOCALE FALLBACK MEASURED, NOT ASSUMED: /zh-Hans/docs/reference/environment-variables (sibling deleted) rendered the NEW English body -- article CJK count 17, and every one of those characters was located in sidebar/nav chrome, not the article prose; the control /zh-Hans/docs/quickstart, whose translation was kept, rendered 1215 CJK characters. Same result for /ja/docs/configure/runtime (deleted, 64 CJK/kana, all chrome) vs its English source (0). (6) No changeset: this repo has no .changeset directory and .github/workflows/ci.yml runs only type-check, build and test -- there is no changeset gate and therefore no skip-changeset label to apply. (7) Control-byte scan of every changed page clean; no internal tracker ids, internal hostnames or credentials in the pages or the PR body. The dev server was started with a recorded PID and torn down by PID (port 3111 confirmed closed).",
  "open_questions": [
    {
      "question": "Four cache-tuning variables the old reference page documented -- OS_KERNEL_CACHE_SIZE (default 32), OS_KERNEL_TTL_MS, OS_ENV_CACHE_TTL_MS, OS_ARTIFACT_CACHE_TTL_MS -- appear in NO shipped deployment artifact and in no open runtime source. They exist only in the hosted control-plane distribution. I removed them rather than restate defaults I cannot ground, and removed the same reference from architecture.mdx's performance table. Does a self-hosted deployment read any of them?",
      "options": [
        "A: they are hosted-only; the removal is correct and they should never return to a self-hosted reference",
        "B: the self-hosted image reads them too; restore them with defaults confirmed from the image, and add them to the deploy bundle template so they have a shipped source of truth"
      ],
      "recommendation": "A until someone can point at a shipped artifact. Startup focus: a tuning knob with no pull and no shipped template entry is a declared surface nobody asked for, and documenting a default I cannot read is exactly the failure this card exists to end. If B turns out to be true, the fix belongs in the deploy bundle first and the docs second."
    },
    {
      "question": "OS_PLATFORM_SSO and OS_RUNTIME_PORT were documented as runtime/auth configuration. Neither occurs in the open runtime source; both occur only in the hosted distribution. Removed for the same reason. Same question: does the shipped image read them?",
      "options": [
        "A: hosted-only, removal correct",
        "B: shipped-image variables that need a bundle entry and a documented default"
      ],
      "recommendation": "A. OS_ROOT_DOMAIN, which is genuinely read by the runtime's serve path, is kept and still covers the platform-SSO subdomain case a reader would come here for."
    },
    {
      "question": "OS_ORGANIZATION_ID was documented as 'default organization id for file-backed mode (default org_local)'. Its only occurrence anywhere is inside the hosted runtime's file-artifact client. Removed. Is it reachable on a self-hosted deployment at all?",
      "options": [
        "A: not a self-hosted variable; removal correct",
        "B: it is reachable, and the reference should say so with the default confirmed from the image"
      ],
      "recommendation": "A, and if B, it needs a bundle entry: a default organization id is exactly the kind of value that must not live only in a docs page."
    },
    {
      "question": "resources/changelog.mdx recorded, as history, that a release made 'a cloud deployment point OS_ARTIFACT_FILE at a published artifact URL'. Nothing has ever read OS_ARTIFACT_FILE, so I could not confirm what the variable was actually called at that release. I restated the entry to describe the capability (an artifact named by URL) and pointed at the current contract, rather than inventing a name or leaving a false one.",
      "options": [
        "A: leave it as capability-only, which is true at every release",
        "B: someone who knows that release supplies the real name and the entry is restored with it"
      ],
      "recommendation": "A. A changelog entry that names no variable is weaker than one that names the right variable, but it is strictly better than one that names a variable that never existed -- and it cannot rot again."
    },
    {
      "question": "The retired-name table says the runtime image refuses a boot carrying a non-default OS_ARTIFACT_PATH. That refusal is documented in the shipped bundle and implemented in the deployment configuration, and it is specific to the ObjectOS runtime image -- the framework CLI still reads the variable on its own `serve` path. I wrote the CLI reference to say 'on the ObjectOS runtime image'. Is that distinction one this customer-facing site should be drawing at all?",
      "options": [
        "A: keep the distinction -- a CLI reference that hid it would send a reader to a refused boot",
        "B: drop the CLI mention entirely and let OS_ARTIFACT_URL be the only documented spelling"
      ],
      "recommendation": "A. B reads cleaner but leaves a reader who already has OS_ARTIFACT_PATH in a file with no way to find out why their boot was refused."
    }
  ],
  "out_of_scope_findings": [
    "NOT FILED -- the GitHub issues API returned 'rate limit already exceeded' for this account while I was searching for duplicates, and the dispatch says to stop rather than retry-loop. Two findings are therefore reported here for the PM to file. (1) Every default-locale (unprefixed) docs page throws React error #418, a hydration mismatch, in the browser console. Reproduced at this branch head on pages this branch does not touch (/docs, /docs/why, /docs/quickstart, /docs/configure/ai, /docs/reference/rest-api) and on the Deploy pages from the earlier rewrite, so it predates this work. Prefixed-locale routes (/zh-Hans/..., /ja/...) throw nothing, which points at the hideLocale: 'default-locale' middleware rewrite as the asymmetry. Concrete defect, unlabeled for triage.",
    "NOT FILED (same rate limit). (2) architecture.mdx still describes the runtime with the hosted multi-environment model -- 'per-kernel warmup (first request to a project)', '~10-30MB per active project kernel', concurrent kernels per instance -- on a page whose subject is the single-environment self-hosted product. I removed the one variable name that made the claim unverifiable but deliberately did not rewrite the performance model, which is outside this card. Observation-class; suggest the `finding` label and no pm:queue."
  ]
}

---

Generated by Claude Code

[os-zhuang]

Closed — PR #63 merged.

The live contradiction is gone: reference/environment-variables.mdx and deploy/air-gapped.mdx now agree that an unset cloud URL resolves to the public control plane, and that an ordinary licence paired with off is refused at startup.

9 English pages rewritten, 54 stale locale siblings deleted — every deletion a translation, no English content removed.

Two of this card's claims were wrong, and the record was corrected rather than the code

• OS_DATABASE_DRIVER is not retired — the runtime reads it. It was documented instead of removed.
• build/packages.mdx was already correct: that OS_CLOUD_API_KEY is the publishing identity, a name collision rather than a stale contract. Kept, with the collision noted.

⇒ A filed card is a hypothesis. Implementing these two as written would have deleted a live variable and broken a correct page.

Independently confirmed while reviewing: OS_ARTIFACT_FILE has zero occurrences in the runtime — the "set it and nothing reads it" claim is measured.

Retired names were kept, not deleted

They live in a Retired names table — "listed here so that a configuration file you inherited can be read and corrected, not so they can be used" — each with its replacement. The failure this card describes is silent; the fix therefore has to be findable by someone already suffering it.

Two pages beyond this card's list were included (operate/backup.mdx, reference/cli.mdx).

The locale deletions were proved safe, not assumed

200 OK cannot distinguish "fell back to English" from "still serving the stale translation". Counting article-body CJK did: a page whose sibling was deleted rendered 17 (all in nav chrome), against 1215 on a control whose translation was kept.

Left open for the maintainer

Seven variables (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) appear only in the hosted distribution and in no shipped artifact. They were removed rather than have ungrounded defaults restated. ⚠️ If any is in fact read by the self-hosted image, the fix belongs in the deploy bundle first and the docs second — a default that exists only in a docs page is how this class of problem started.

Related: #61 (hydration error, now with a locale-asymmetry diagnosis), #64 (architecture.mdx still describes the hosted multi-environment model).

---

Generated by Claude Code