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

Activity

1. os-zhuang commented on Aug 18, 2026

   

   os-zhuang

   on Aug 18, 2026 – with Claude

   ContributorAuthor

   More actions

   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
2. os-zhuang commented on Aug 18, 2026

   

   os-zhuang

   on Aug 18, 2026 – with Claude

   ContributorAuthor

   More actions

   {
     "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
3. os-zhuang

   added a commit that references this issue on Aug 18, 2026

   docs: replace the retired runtime env contract outside Deploy (#60) (#63

   ...

   7eaf3a9
4. os-zhuang

   closed this as completedin #63on Aug 18, 2026
5. os-zhuang commented on Aug 18, 2026

   

   os-zhuang

   on Aug 18, 2026 – with Claude

   ContributorAuthor

   More actions

   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