From 7d4ca798ad6aa05dbae7208809d8b19a12c8fc0f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:49:49 +0000 Subject: [PATCH] docs: use one canonical name for the config-authored boot shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two current pages named the same boot shape differently, and the deploy bundle ships one environment template per shape — so a reader who has seen both pages could not tell whether "Config-authored" and "Shipped runtime" were one shape or two, while deploy/index.mdx warns against adapting one template into another. The card guessed deploy/index.mdx's "Shipped runtime" was canonical because it is the newer page. It is not the newer page, and the corpus does not use that name anywhere else: - Three pages carry this table, not two. configure/runtime.mdx:24 also names row one "Config-authored", so the corpus stands 2-1. - The commit order inverts the guess. deploy/index.mdx's table landed in #62 at 13:14; "Config-authored" was written into architecture.mdx and configure/runtime.mdx by #63 at 14:49 — after it, by a pass whose scope was explicitly "outside Deploy" and which reconciled contradictions with the Deploy rewrite. #69 then rewrote architecture.mdx at 17:40 and kept the name. "Shipped runtime" is the oldest of the three writes. - #63 checked its rows "against the deployment bundle that ships with the release, and against the runtime and CLI source that reads it" — the template-mapping authority, and it sits with "Config-authored". - "Artifact-pinned" is the framework's own term (packages/runtime/src/ artifact-reference.ts, packages/cli/src/commands/serve.ts). The paradigm is a past-participle describing where the app came from; "Shipped runtime" is a noun phrase naming the runtime, and is the odd one out even inside its own table. - "the shipped runtime" is already an established generic phrase for the product runtime — three uses upstream, plus environment-variables.mdx:158 ("Nothing in the shipped runtime reads OS_ARTIFACT_FILE"). Promoting it to a proper noun would make the boot-contract reference page use the phrase in two senses at once. Row three differed in substance too, and the evidence settles it rather than contradicting: air-gapped.mdx and the OS_COMPOSED_ARTIFACT_URL entry both state the two claims jointly — the composed shape is the hosted multi-organization shape AND is air-gap-licensed only, enforced at startup. deploy/index.mdx already carried both; architecture.mdx carried only the licence half, so it gains the purpose half and the link to where the refusal is stated. No headings are renamed, so no anchor moves: /docs/architecture#boot-modes still resolves. Fixes #71 --- content/docs/architecture.mdx | 2 +- content/docs/deploy/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index 500ace1..c728be0 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -118,7 +118,7 @@ carries the exact contract for each. |---|---|---| | **Config-authored** | The shipped shape. Single app, evaluation, air-gapped, most production deployments | The runtime boots the metadata authored in the image, plus anything installed into it | | **Artifact-pinned** | The app is released on its own cadence, separately from the runtime image | One variable names a published artifact by URL, with an optional integrity pin. Upgrading the app is a change to that variable plus a restart | -| **Composed** | Several organizations behind the isolation wall, sharing one database, running a published app | The same artifact reference, consumed from the deployment's own configuration so the enterprise plugins load alongside it. Air-gap licensed only | +| **Composed** | Several organizations behind the isolation wall, sharing one database, running a published app — the hosted single-app SaaS shape | The same artifact reference, consumed from the deployment's own configuration so the enterprise plugins load alongside it. Air-gap licensed only, and [refused at startup](/docs/deploy/air-gapped) otherwise | Whether the deployment also talks to a **control plane** is a separate decision, made by the cloud-posture variable — a connected deployment can be diff --git a/content/docs/deploy/index.mdx b/content/docs/deploy/index.mdx index 95fd45d..136e63e 100644 --- a/content/docs/deploy/index.mdx +++ b/content/docs/deploy/index.mdx @@ -44,7 +44,7 @@ available to you — it is not just a matter of packaging. | Shape | The app comes from | Use it when | |---|---|---| -| **Shipped runtime** | The image's own bundled application | A single-organization deployment; the default the Compose stack configures. | +| **Config-authored** | The image's own bundled application — the metadata authored in the image, plus anything installed into it | A single-organization deployment; the default the Compose stack configures, and the shape that needs no configuration. | | **Artifact-pinned** | A published app artifact named by URL, resolved before any deployment config runs | You run one published app and want app upgrades to be an environment change and a restart, with no image rebuild. Note that the deployment's enterprise plugins do **not** load on this path. | | **Composed** | A published app artifact composed *with* this deployment's enterprise plugins | Several organizations share one database. This is the hosted single-app SaaS shape — and it is **air-gap-licensed only**, enforced at startup. |