arkgate 4.8.13 → 4.8.14

package/docs/README.md

@@ -10,10 +10,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 Pick your path. Skip everything else.
 
 | You are… | Start here |
@@ -34,7 +36,7 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 | [use.md](use.md) | One flow: install → doctor → day-to-day |
 | [enthusiast/](enthusiast/README.md) | Tutorials and plain-language track |
 | [demos/](demos/) | Short end-to-end demos |
-| [product-voice.md](product-voice.md) | How ArkGate should sound (Write. Check. Ship.) |
+| [product-voice.md](product-voice.md) | How ArkGate should sound (Write. Check. Ship. · Contener · Guiar · Ordenar) |
 
 ### Develop (integrate)
 | Doc | What it is |
@@ -44,7 +46,7 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 | [agent-guide.md](agent-guide.md) | Agent, CLI, and MCP reference (incl. `ark status --json` / MCP `ark_status`) |
 | [diagnostics.md](diagnostics.md) | Public diagnostic `ruleId` catalog (why / fix anchors) |
 | [configuration.md](configuration.md) | `ark.config.json` contract |
-| [arkorder.md](arkorder.md) | Optional ArkOrder extra: library + sensors, not a service |
+| [arkorder.md](arkorder.md) | Optional ArkOrder extra: library + sensors, not a service. Proof: [billing gallery](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) (GitHub, not in the npm tarball) |
 | [brownfield-adoption.md](brownfield-adoption.md) | Existing messy repos |
 | [package-surface.md](package-surface.md) | Stable vs experimental package surface |
 | [typescript-support.md](typescript-support.md) | TS 5 / 6 / 7 analysis boundary |
@@ -52,9 +54,9 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 ### Contribute (library)
 | Doc | What it is |
 |-----|------------|
-| [CONTRIBUTING.md](../CONTRIBUTING.md) | Setup, rules, PR/release |
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | Setup, rules, thin publish |
 | [ROADMAP.md](../ROADMAP.md) | Live implementation queue (one `doing` at a time). History: [archive/roadmap-history.md](archive/roadmap-history.md) |
-| [adr/](adr/README.md) | Architecture decisions ([0032](adr/0032-writes-via-aggregate-sensor.md) writes-via-aggregate · [0033](adr/0033-arkorder-runtime-half-is-arkrun.md) ArkOrder runtime half · [0034](adr/0034-arkorder-valved-loop.md) valved loop) |
+| [adr/](adr/README.md) | Architecture decisions ([0032](adr/0032-writes-via-aggregate-sensor.md) writes-via-aggregate · [0033](adr/0033-arkorder-runtime-half-is-arkrun.md) ArkOrder runtime half · [0034](adr/0034-arkorder-valved-loop.md) valved loop · [0036](adr/0036-skill-catalog-product-capacity.md) skill catalog capacity) |
 | [SECURITY.md](../SECURITY.md) · [threat-model.md](threat-model.md) | Security |
 
 ---
@@ -71,7 +73,7 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Prepared: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.13`; not published).
+Prepared: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.14`; not published until `publish-npm` for `v4.8.14`).
 Current published: [releases/4.8.11.md](releases/4.8.11.md) (`arkgate@4.8.11` on npm `latest`; does not close `K01`).
 Prior published: [releases/4.8.10.md](releases/4.8.10.md) (`arkgate@4.8.10`).
 Prior published: [releases/4.8.9.md](releases/4.8.9.md) (`arkgate@4.8.9`).

package/docs/agent-guide.md

@@ -10,10 +10,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 This guide is the **develop** reference for agents and codegen: write hooks, advisory MCP tools,
 CI, and `/ark-*` skills.
 
@@ -227,10 +229,16 @@ The projection is **non-authoritative**. Enforcement is `ark-check` / host write
 CI (`--strict-merge`) — never AGENTS.md, skills, or this projection. Root API:
 `buildAgentProjectionBlock` / `mergeAgentProjectionDocument`.
 
-**Agent Skills packaging (4.3):** the same frozen **13** skill names are also shipped as
+**Agent Skills packaging (4.3 / #216):** the same closed catalog ships as
 an Agent Skills–compatible package under `templates/agent-skills/<name>/SKILL.md` for hosts that
 install via `npx skills` (in addition to Ark `--install-agent-gates`). See
-[Install skills — Ark and ecosystem](#install-skills-ark-and-ecosystem). No new skill names.
+[Install skills — Ark and ecosystem](#install-skills-ark-and-ecosystem).
+Closed catalog (`ARK_SKILL_NAMES`): first-class doors plus one-release stubs.
+The *set* must exercise Layers + ArkRules + ArkRun + ArkOrder (when / not when / handoff).
+First-class `/ark-order` mirrors `/ark-runtime`. ACS05 freeze was opened for that door
+([ADR 0036](adr/0036-skill-catalog-product-capacity.md)); Domain still closes the list.
+Add a name only with a live ROADMAP item. Filter: **Contener · Guiar · Ordenar**
+— contain the write, guide the next step, order leftover mess.
 Skill bodies coach residual lenses and anti false-done; they never enforce.
 
 ## Architecture playbook and `ark-check --recommend`
@@ -316,8 +324,10 @@ as unresolved decisions, and restores the integration with `ark start --tools <h
 **Five doors (emphasize):** `/ark-adopt` = session 0 (greenfield scaffold + brownfield honesty —
 write the path). `/ark-place` = new feature (place **and write**). `/ark-autopilot` = apply
 plan A + one Shape refactor (invoke = approval). `/ark-explore` = map + dual-plan seed (no
-apply). `/ark-upgrade` = preview then apply in-turn. Other `/ark-*` names stay installed as
-**shortcuts**. Empty plan A is not “architecture healthy” if leftover design remains.
+apply). `/ark-upgrade` = preview then apply in-turn. First-class extras: `/ark-runtime` wires
+ArkRun; **`/ark-order`** wires ArkOrder. Other `/ark-*` names stay installed as
+**one-release shortcuts**. Empty plan A is not “architecture healthy” if leftover design remains.
+Filter: **Contener · Guiar · Ordenar** — contain the write, guide the next step, order leftover mess. Skills never enforce.
 
 **Team parliament:** adopt is a **contract session** (law-only). Feature work must not edit
 `ark.config.json` / `arkrules/*` / `.ark-baseline.json`. Prefer
@@ -537,7 +547,7 @@ ArkOrder — with its plane, its tier and whether it can *ever* be enforced, so
 Tier-2 shows up before you write the rule rather than after you wait for a run.
 ArkOrder: `proposeRelease` then `apply`; `refreshSigma`; ingest residual;
 capacity pack; `ReleaseStore`; ArkRun `decisionTape`. Extras door:
-`/ark-adopt`. First contact: doctor + `[ArkOrder]` on the check.
+`/ark-adopt` (turn on) then **`/ark-order`** (wire one candidate). First contact: doctor + `[ArkOrder]` on the check.
 It also says *how*: only the ArkRules plane is promoted per rule; ArkRun and
 ArkOrder are switched by the plane-level `arkRun.mode` / `arkOrder.mode`, and
 `--promote --apply` writes ArkRules documents only.
@@ -758,7 +768,7 @@ Greenfield / empty-tree **depth** (only when doctor or a thin tree points here
 1. Run `ark-check --recommend --json` or MCP `ark_recommend`.
 2. Read `archetype`, `preset`, and `adoptInOrder.phase1` — scaffold only those directories first.
 3. Run `ark init --archetype <id> --yes`, `--apply-policy-pack enthusiast-<preset>`, or `ark init --preset <preset> --yes` when no `ark.config.json` exists (or let `ark start --apply` install the compact contract).
-4. Optional: `--write-plan` for `ark-adoption-plan.json`; copy a gallery starter from `examples/README.md`.
+4. Optional: `--write-plan` for `ark-adoption-plan.json`; copy a gallery starter from `examples/README.md`. ArkOrder proof on that index is [arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) (not a starter; GitHub tree, not in the npm tarball).
 5. Use `/ark-place` or `ark_place` for individual files after the contract exists.
 6. Re-check with `ark-check --doctor`, then `ark-check --root . --config ark.config.json --strict`.
 
@@ -823,7 +833,7 @@ directories (`utils/`, `lib/`) must be classified explicitly via `/ark-adopt`.
 
 ## Supported agent hosts
 
-**Day zero** is the compact path from `ark start` / `ark start --apply` (router + write path + CI plan) — not the full skill pack.
+**Day zero** is the compact path from `ark start` / `ark start --apply` (router + write path + CI plan; merges Ark into an existing project-owned `AGENTS.md` / `.mcp.json`) — not the full skill pack.
 
 Wire write-gate + MCP for the active host; add the full `/ark-*` skill pack only as **expert depth** (`--skills-only` or full install when you want guided autopilot):
 
@@ -857,8 +867,13 @@ and [shared Claude/Grok/Antigravity homes](ai-gates.md#shared-claude--grok-home-
 
 ### Install skills — Ark and ecosystem {#install-skills-ark-and-ecosystem}
 
-The same **13** skill names ship two ways. **No new skill names** (4.3 freeze): packaging and
-routing only.
+The same closed catalog ships two ways. **Closed catalog** (`ARK_SKILL_NAMES`): first-class
+doors plus one-release stubs. The *set* must exercise Layers + ArkRules + ArkRun + ArkOrder
+and route (when / not when / handoff). First-class `/ark-order`; leftover names stay as
+one-release stubs. ACS05 freeze was opened for `/ark-order`; Domain still closes the list.
+Add a name only with a live ROADMAP item
+([ADR 0036](adr/0036-skill-catalog-product-capacity.md) / issue #216).
+Filter: **Contener · Guiar · Ordenar** — contain the write, guide the next step, order leftover mess. Skills never enforce.
 
 | Channel | What it installs | When to use |
 |---------|------------------|-------------|
@@ -883,9 +898,10 @@ npx skills add https://github.com/pedroknigge/arkgate/tree/main/templates/agent-
 npx skills add ./node_modules/arkgate/templates/agent-skills --list
 ```
 
-Frozen names: `ark-adopt`, `ark-architect`, `ark-autopilot`, `ark-contract`, `ark-coverage`,
-`ark-explain`, `ark-explore`, `ark-fix`, `ark-loop`, `ark-place`, `ark-runtime`, `ark-think`,
-`ark-upgrade`. Root API: `ARK_SKILL_NAMES` / `validateAgentSkillsPackage` (Domain
+Closed names: first-class `ark-adopt`, `ark-autopilot`, `ark-coverage`, `ark-explain`,
+`ark-explore`, `ark-order`, `ark-place`, `ark-runtime`, `ark-upgrade`; one-release stubs
+`ark-architect`, `ark-contract`, `ark-fix`, `ark-loop`, `ark-think`. Root API:
+`ARK_SKILL_NAMES` / `ARK_FIRST_CLASS_SKILL_NAMES` / `validateAgentSkillsPackage` (Domain
 `agentSkillsPackage`). Skills are **process** depth — they never decide pass/fail; enforcement
 remains `ark-check` / hooks / CI.
 

package/docs/ai-gates.md

@@ -10,10 +10,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 This page is host install depth (hooks / MCP / CI).
 
 This page is **develop** depth (install hooks/MCP/CI per host). Product path: [use.md](use.md) ·

package/docs/arkorder.md

@@ -8,9 +8,14 @@ Import: `arkgate/order` (same npm package `arkgate`). Off until you add
 `arkOrder`. Absence is silent. In-memory. Not durable. A library plus
 sensors, not a service. Does **not** replace ArkRun.
 
-Turn the extra on with `/ark-adopt`. First contact is doctor + `[ArkOrder]`
+Turn the extra on with `/ark-adopt`. Wire one candidate with **`/ark-order`**
+(mirrors `/ark-runtime`). First contact is doctor + `[ArkOrder]`
 on the check. Names like ξ live below, in the valve and sensor tables.
 
+Proof (GitHub, not in the npm tarball):
+[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
+First freeze is `release()`. Later plan change is `proposeRelease` then `apply`.
+
 Canonical plan seed: [plans/arkorder/README.md](plans/arkorder/README.md).
 ADRs: [0027](adr/0027-arkorder-gated-extra-plane.md)–[0030](adr/0030-opt-in-extras-same-npm-package.md),
 [0033](adr/0033-arkorder-runtime-half-is-arkrun.md) (runtime half is ArkRun),
@@ -255,15 +260,17 @@ In-memory `ReleaseStore` is **not** durable. Doctor / status `arkOrder` stays
 
 ## Doctor / start / status
 
-`--doctor` always emits an ArkOrder row (`notAScore`). Absence is a silent
-line. When the extra is on, the first human line is the one-breath:
+`--doctor` always emits an ArkOrder row (`notAScore`). Verdicts stay silent
+when the extra is off (Layers unchanged, not a score). The first human line
+is always the one-breath — including the compact first screen:
 
 **Layers stop a bad import. ArkOrder stops rewriting a big product choice —
 like the billing plan — as if it were a seat count. Change those choices
 through a valve, not a generic update.**
 
 `ark start` leaves extras off (`Optional extras stay off. This start is
-layers only — they stop bad imports.`).
+layers only — they stop bad imports.`) and still prints that one-breath plus
+`Next: examples/arkorder-billing`, then `/ark-adopt` and `/ark-order`.
 `ark status` projects a thin `arkOrder` slice (present / mode / leftover
 count). A deny prints `[ArkOrder]` next to `ARKORDER_*`, the same envelope
 as a bad import.

package/docs/configuration.md

@@ -453,12 +453,13 @@ Write-gate ApplyPatch denies a batch that mixes law files with product source. H
 never hit PreToolUse are unchanged. Local `pnpm` gates should call `--changed --base`, not
 only full-tree `--strict-merge`.
 
-`--changed` honors the touched-file list for **file-local** ArkRules structure sensors
-(class shape, orchestration-only, thin-adapter, writes-via-aggregate) and for
-structural-hint preload. Import-edge, layer, and cycle sensors still evaluate the full
-governed graph. That is a bound on the existing scan, not a second analysis engine, and
-it does not turn a full-tree run into a seconds-long one. A `--changed` pass is not a
-full-tree structural verdict.
+`--changed` resolves the touched sources plus their import closure — not the whole
+include tree. File-local ArkRules sensors (class shape, orchestration-only, thin-adapter,
+writes-via-aggregate) and hint preload stay on the touched set. Layer and cycle sensors
+see that closure, so a new illegal import or a cycle the change can complete still
+fails. Untouched files outside the closure are left to the full-tree CI check. Same
+engine; not a second analysis path. A `--changed` pass is not a full-tree structural
+verdict.
 
 MCP clients can call `ark_policy_delta` with the previous `baseConfig`, an optional candidate
 contract (the current project contract is the default), and the same optional acknowledgement.

package/docs/develop.md

@@ -11,10 +11,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 For **developers** integrating ArkGate into a product repo: agents, CI, config, brownfield, and power tools.
 
 If you only want the happy path, start at [use.md](use.md). Optional ArkOrder

package/docs/diagnostics.md

@@ -24,7 +24,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 
 | ruleId | Category | Title |
 |--------|----------|-------|
-| [`LAYER_IMPORT_VIOLATION`](#LAYER_IMPORT_VIOLATION) | layer | Layer import not allowed |
+| [`LAYER_IMPORT_VIOLATION`](#LAYER_IMPORT_VIOLATION) | layer | This import is not allowed |
 | [`LAYER_INTENT_REFERENCE_VIOLATION`](#LAYER_INTENT_REFERENCE_VIOLATION) | layer | Intent referenced across a blocked layer edge |
 | [`LAYER_REFERENCE_VIOLATION`](#LAYER_REFERENCE_VIOLATION) | layer | Layer reference blocked (snippet / AI gate) |
 | [`CIRCULAR_DEPENDENCY`](#CIRCULAR_DEPENDENCY) | layer | Dependency cycle |
@@ -58,7 +58,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKORDER_GENERIC_UPDATE`](#ARKORDER_GENERIC_UPDATE) | arkorder | Generic update of ξ |
 | [`ARKORDER_TOO_MANY_PARAMS`](#ARKORDER_TOO_MANY_PARAMS) | arkorder | Too many slow keys |
 | [`ARKORDER_INGEST_WRITES_XI`](#ARKORDER_INGEST_WRITES_XI) | arkorder | ingest assigned into ξ |
-| [`ARKORDER_UNVALVED_RELEASE`](#ARKORDER_UNVALVED_RELEASE) | arkorder | Unvalved second freeze of ξ |
+| [`ARKORDER_UNVALVED_RELEASE`](#ARKORDER_UNVALVED_RELEASE) | arkorder | Second freeze without the valve |
 | [`INVALID_CHANGE_PATH`](#INVALID_CHANGE_PATH) | preflight | Unsafe change path |
 | [`DUPLICATE_CHANGE_PATH`](#DUPLICATE_CHANGE_PATH) | preflight | Duplicate path in change set |
 | [`DELETE_TARGET_MISSING`](#DELETE_TARGET_MISSING) | preflight | Delete target missing |
@@ -105,9 +105,9 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 
 ### `LAYER_IMPORT_VIOLATION`
 
-**Layer import not allowed**
+**This import is not allowed**
 
-- **Why:** A module import (or re-export) crosses a layer edge that ark.config.json does not allow. The architecture contract forbids that dependency direction so outer infrastructure cannot leak into pure or inner layers.
+- **Why:** This file imported a folder it may not reach. The write doesn’t land. The same check fails the pull request.
 - **Fix:** Branch by import kind: constants/types/pure → adopt into DomainModel or SharedKernel (do not invent a port); kernel/events/bootstrap from Persistence → inject a port or move the map to SharedTypes (Persistence must not emit); define a port only when the target is a real use-case. Type-only edges use `import type`. Then preflight again. Do not weaken the layer rule without a hash-bound policy acknowledgement.
 
 <a id="LAYER_INTENT_REFERENCE_VIOLATION"></a>
@@ -466,10 +466,10 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 
 ### `ARKORDER_UNVALVED_RELEASE`
 
-**Unvalved second freeze of ξ**
+**Second freeze without the valve**
 
-- **Why:** release() ran after a pattern was already frozen and the new ξ differs. First freeze is release(); later pattern change is proposeRelease then apply.
-- **Fix:** Change ξ with proposeRelease then apply(ProposeResult). release() is only the first freeze. Never mechanical-safe.
+- **Why:** release() already froze the big choice. A later release() with a different value does not land. First freeze is release(); later change is proposeRelease then apply.
+- **Fix:** Change the choice with proposeRelease then apply. release() is only the first freeze. Never mechanical-safe.
 
 ## Atomic preflight and change sets
 

package/docs/enthusiast/README.md

@@ -11,10 +11,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 Plain-language onboarding for builders who use AI agents but are not professional
 developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-to,
 reference, and explanation. Package: **`arkgate`** (CLI: `arkgate` / `arkgate-check`;
@@ -70,6 +72,7 @@ Reproducible scripts — no video required:
 - [Write-gate self-correction](../demos/01-write-gate-self-correction.md)
 - [Brownfield baseline adoption](../demos/02-brownfield-baseline-adoption.md)
 - [Co-pilot autopilot, end to end](https://github.com/pedroknigge/arkgate/blob/main/docs/demos/03-copilot-autopilot.md)
+- [ArkOrder billing — first freeze, then valve](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) (GitHub tree, not in the npm tarball; not a gallery starter)
 
 ## Gallery starters
 
@@ -84,6 +87,8 @@ Reproducible scripts — no video required:
 
 Deep teaching example (runnable API + break exercises): [hexagonal-order-api](https://github.com/pedroknigge/arkgate/tree/main/examples/hexagonal-order-api).
 
+ArkOrder proof (optional extra, not a starter): [arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) — first freeze is `release()`; later plan change is `proposeRelease` then `apply`. Index: [examples/README.md](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md).
+
 ## Brownfield vs greenfield
 
 | Situation | Use |

package/docs/enthusiast/how-to-gallery-starter.md

@@ -12,12 +12,13 @@ npm run check
 
 Pick by archetype — see [examples/README.md](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md).
 
-## When to use a starter vs hexagonal-order-api
+## When to use a starter vs hexagonal-order-api vs billing
 
 | Need | Use |
 |------|-----|
 | Fast baseline layout | `*-starter/` gallery |
 | Runnable API + break exercises | `hexagonal-order-api/` |
+| ArkOrder freeze / valve (optional extra) | [arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) — not a starter, not in the npm tarball |
 
 ## After copying
 

package/docs/package-surface.md

@@ -10,10 +10,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 That is the product wedge (host hook + required CI). Skills name the next step after that.
 **Not the wedge:** the optional in-process **ArkRun** runtime (`arkgate/runtime`) and the
 optional **ArkOrder** pattern extra (`arkgate/order`).
@@ -72,7 +74,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
 | **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
-| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources. `stewards` and `layers[].description` are excluded from policy hash. Identity is handle or email, not git `user.name`. No org plane. |
+| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources plus their import closure. `stewards` and `layers[].description` are excluded from policy hash. Identity is handle or email, not git `user.name`. No org plane. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
 | **Structural convergence (3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
@@ -84,11 +86,11 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Diagnostic code catalog** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. ArkRun `ARKRUN_*` codes (RN05) share dual-depth `nextAction` / `enthusiastHint`; declaration-list adds are mechanical-safe only when the call-site literal already exists. Docs ship in the npm tarball. |
 | **Status manifest** | CLI `ark status [--json] [--vs <ref>]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` / `projectStatusImprovementCompass` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action, **`improvementCompass`** with honesty **`mode`** `full`\|`subset`\|`unavailable` (residual ids only; always `notAScore: true`; optional `reasonCode`/`reason`/`factsSource`/`contractHash`), optional **`vsBase`** (pin / contract / baseline grow vs a git ref; advisory only), and additive **`arkRun`** (`notAScore`; `present` / `mode` / `extraMergeTeeth` / residual count — null residual is unknown, not green). **Not a score.** Residual never changes gate verdicts. Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
 | **Agent contract projection** | CLI `ark agents-md [--write] [--check] [--stdout] [--json]`; install/upgrade AGENTS templates; root API `buildAgentProjectionBlock` / `mergeAgentProjectionDocument` | Schema `1.0` (projection markers). Version-stamped managed block (`arkgateVersion` + contract summary + diagnostic short list). **Non-authoritative** — not a gate input; enforcement is ark-check / hooks / CI. Content-identity merge preserves customized regions outside markers. Drift: `--check` vs package version. |
-| **Agent Skills packaging** | `templates/agent-skills/<name>/SKILL.md` (+ package README); root API `ARK_SKILL_NAMES` / `validateAgentSkillsPackage`; `npm run check:agent-skills` | Schema `1.0` (package contract). Same **13** skill names as flat templates; Agent Skills–compatible layout for `npx skills add`. No new skill names. Layout is generated 1:1 from `templates/skills/*.md`. |
+| **Agent Skills packaging** | `templates/agent-skills/<name>/SKILL.md` (+ package README); root API `ARK_SKILL_NAMES` / `ARK_FIRST_CLASS_SKILL_NAMES` / `validateAgentSkillsPackage`; `npm run check:agent-skills` | Schema `1.0` (package contract). Closed catalog (`ARK_SKILL_NAMES`): first-class doors plus one-release stubs, 1:1 with flat `templates/skills/*.md`. First-class `/ark-order` (issue #216 / ADR 0036). Add a name only with a live ROADMAP item. |
 | **`arkgate/schema/arkrules`** or **`arkgate/schema/ark.arkrules.schema.json`** | Per-layer structure sensors + invariant catalog (ADR 0012) | Schema `1.0`. Opt-in via root `arkRules` map (`ark.config` schema `1.1`). |
 | **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.2` is additive: optional `classShapes` (1.1) plus ArkRun `arkRunKernelCalls` / `arkRunManagedNews` / `arkRunCompositionRootHits` / `arkRunDeclarations` (RN03–RN04) and ArkOrder `arkOrderPlaneCalls` / `arkOrderGenericUpdates` / `arkOrderRootHits` (OR05). `1.0`/`1.1` payloads remain loadable. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, candidate tree/facts hashes, and (when present) ArkRun/ArkOrder call-site evidence. Tier-1 sensors emit `ARKRUN_*` / `ARKORDER_*` diagnostics from those facts: advisory never flips `valid`; enforced blocks. Extra absence is silent. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
-| **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) **or** Agent Skills ecosystem path | **Day zero** is the compact router from `ark start` / `start --apply` + doctor — not the full skill pack. Skill *names* (frozen **13**) and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve. **4.0:** all skills except experimental `/ark-runtime` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. **4.3:** Agent Skills–compatible layout at `templates/agent-skills/<name>/SKILL.md` (1:1 with flat `templates/skills/*.md`); install via `npx skills add ./node_modules/arkgate/templates/agent-skills` (or the GitHub tree). Domain `ARK_SKILL_NAMES` + `validateAgentSkillsPackage`; drift `npm run check:agent-skills`. Skills never enforce. |
+| **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) **or** Agent Skills ecosystem path | **Day zero** is the compact router from `ark start` / `start --apply` + doctor — not the full skill pack. Closed catalog (`ARK_SKILL_NAMES`): first-class doors (including `/ark-order`) plus one-release stubs. Guided expert path remains `/ark-autopilot` after pack install. **4.0:** first-class doors except experimental `/ark-runtime` / `/ark-order` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. **4.3:** Agent Skills–compatible layout at `templates/agent-skills/<name>/SKILL.md` (1:1 with flat `templates/skills/*.md`); install via `npx skills add ./node_modules/arkgate/templates/agent-skills` (or the GitHub tree). **#216:** first-class `/ark-order`; ACS05 freeze opened (ADR 0036). Domain `ARK_SKILL_NAMES` + `validateAgentSkillsPackage`; drift `npm run check:agent-skills`. Skills never enforce. |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import/purity rules plus ArkRun import/`new` envelope (`ark/no-arkrun-kernel-in-domain`, `ark/no-arkrun-direct-new`, `ark/no-arkrun-transport-bypass`) when `arkRun` is on, and ArkOrder envelope (`ark/no-arkorder-kernel-in-domain`, `ark/no-arkorder-generic-update`) when `arkOrder` is on; loads consumer `ark.config.json`. Absence of an extra is silent. Missing-root / missing-plane and undeclared-* stay CLI/MCP. |
 | **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 | **Package metadata** | `arkgate/package.json` | Stable resource subpath for tooling that needs the installed manifest. |

package/docs/product-voice.md

@@ -42,6 +42,26 @@ ArkOrder  optional   big product choices (billing plan, not seat counts)
 Status first (`arkgate-check --doctor`). One next step. CLI flag `--doctor` stays;
 human copy says **status**.
 
+**Contener · Guiar · Ordenar** is the product north star (not a score). First
+contact says it in ordinary English: contain the write, guide the next step,
+order leftover mess.
+
+- **Contener** — decide what the AI may write, and in what shape. ArkGate is
+  this: import rules, write + required CI. ArkRules is optional shape inside a
+  part.
+- **Guiar** — show a proven next step so a non-expert is not stuck. Doctor
+  action #1. Skills. ArkRun is an optional experimental runtime.
+- **Ordenar** — tidy a messy tree toward a clean one, one small refactor at a
+  time. ArkOrder is the optional extra for the few big product choices (billing
+  plan, not seat counts).
+
+The skill *set* must cover Layers + ArkRules + ArkRun + ArkOrder and say when /
+not when / handoff. First-class `/ark-order`; leftover `/ark-*` names are
+one-release stubs. ACS05 freeze was opened for that door
+([ADR 0036](adr/0036-skill-catalog-product-capacity.md)); Domain `ARK_SKILL_NAMES`
+still closes the list. See [agent guide — skills](agent-guide.md#install-skills-ark-and-ecosystem).
+Skills never enforce. ξ / Haken stay below the fold.
+
 ---
 
 ## Locked first-contact
@@ -53,8 +73,9 @@ On the eight canonical public openings — `README.md`, `docs/use.md`,
 1. **Verbs:** `Write. Check. Ship.`
 2. **Deny:** `When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.`
 3. **Not-that (below the fold, one line):** `Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config is just documentation.`
-4. **Story:** the exact four-paragraph introduction below, with no visible heading or labels.
-5. **Technical nouns (below the introduction):** ArkGate is import rules. ArkRules is optional policies. ArkRun is an optional experimental runtime. ArkOrder stops rewriting a big product choice (like billing plan) as if it were a seat count — named when the consumer opts in, never as the first noun. No ξ / Haken / slaving on the first screen.
+4. **Story:** the exact four-paragraph introduction below, with no visible heading or labels. Paragraph 3 is the north star in ordinary English.
+5. **Caption (immediately after the four paragraphs):** `That is **Contener · Guiar · Ordenar**.`
+6. **Technical nouns (below the introduction):** ArkGate is import rules. ArkRules is optional policies. ArkRun is an optional experimental runtime. ArkOrder is the extra for the few big product choices (billing plan, not seat counts) — named when the consumer opts in, never as the first noun. No ξ / Haken / slaving on the first screen.
 
 Do not lead with folders, `ark.config.json`, “contract”, “gate”, “house”, or “doctor”
 as the first noun. Historical: `If the AI writes an illegal import, the write is rejected`
@@ -75,10 +96,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 Do not add technical terms to these four paragraphs. In the next section, explain that
 ArkGate checks imports, ArkRules is optional, ArkRun is experimental and in-memory,
 and ArkOrder is optional and stops rewriting a big product choice like the billing plan.
@@ -173,7 +196,7 @@ a product PR — that is an owner `--contract-session` (config change).
 - Emoji rain, crush-it, fake amigo, “you don’t need to understand”
 - Auto-fix-everything / magic codemod
 - Suggest / Adapt / Enforce as settings you pick — they are lights (Setup / In progress / Ready)
-- Skill-shopping thirteen names as onboarding
+- Skill-shopping leftover shortcut names as onboarding
 - “Healthy / done” while leftover design work remains
 - “MCP is active” because a file exists
 - Package AI decided pass/fail
@@ -193,13 +216,16 @@ npx arkgate start → start --apply → arkgate-check
 ```
 
 Five commands, not a menu exam: adopt · place · autopilot · explore · upgrade.
-Invoking a command **is** the approval. CLI checks; it does not silently rewrite.
+First-class extras: runtime (ArkRun) · **order** (ArkOrder). Other `/ark-*` names
+are one-release shortcuts. Invoking a command **is** the approval. CLI checks; it
+does not silently rewrite.
 
 ---
 
 ## Checklist before shipping copy
 
-- [ ] **Write. Check. Ship.** is on first-contact.
+- [ ] **Write. Check. Ship.** is on first-contact (the deny / wedge).
+- [ ] **Contener · Guiar · Ordenar** is on first-contact in ordinary English (contain the write, guide the next step, order leftover mess).
 - [ ] Deny is `When the agent writes a bad import, the write doesn’t land.`
 - [ ] One next action is obvious.
 - [ ] ArkGate / ArkRules / ArkRun / ArkOrder are import rules / policies / experimental runtime / the extra that stops a big product choice being rewritten like a seat count.

package/docs/threat-model.md

@@ -33,7 +33,7 @@ infrastructure beyond how this package is published.
 | T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | semantic policy-delta guard in strict merge; hash-bound `--policy-ack`; `--contract-session` required even when `stewards[]` is empty; present-state safety diagnostics |
 | T5 | Baseline ratcheted open | Debt reintroduced | `--update-baseline` requires `--contract-session` even with an empty steward list (`--force` is concentration, not parliament); unused/stale signals; occurrence keys |
 | T6 | Stale MCP/global CLI or wrong root | Gate points at old package / wrong tree | project identity binding; stale process non-authoritative + `PROCESS_PACKAGE_STALE`; project-local upgrade handoff |
-| T7 | Malicious dependency in publish | Compromised gate | signed tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
+| T7 | Malicious dependency in publish | Compromised gate | annotated tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
 | T8 | Path traversal in hooks/check | Read/write outside project | root resolution + under-root import resolve |
 | T9 | Runtime InMemory mistaken for durable | Data loss | durability stance docs + safety InMemory production detector |
 | T10 | Repair payload silently applied | Unexpected rewrites | repair never writes; host must re-inject; exit 2 on deny |
@@ -48,7 +48,7 @@ Codex apply_patch --PreToolUse--> arkgate-mcp (hard for complete trusted + obser
 Any MCP host     --tool call----> arkgate-mcp (advisory validation)
 Human IDE        --disk/git-----> working tree
 working tree     --PR-----------> CI ark-check --strict-merge
-npm publish <-- signed tag ---  GitHub Release + provenance
+npm publish <-- annotated tag ---  GitHub Release + provenance
 ```
 
 Codex hosted tools, specialized hook opt-outs, shell/direct writes, and incomplete patch

package/docs/typescript-support.md

@@ -176,10 +176,10 @@ The release compatibility workflow packs the candidate first, then tests clean c
 - **npm / pnpm / Yarn**;
 - project TypeScript **5.9.3 / 6.0.3 / 7.0.2**.
 
-That is **36** installed-artifact cells on the **full matrix** path (`push` to `main`, PR labels
-`full-matrix` / `release`, or release-prep branch names such as `feat/4.1*`). Ordinary PRs run a
+That is **36** installed-artifact cells on the **full matrix** path (`push` to `main`, or an
+explicit `full-matrix` label). Ordinary PRs run a
 **slim** packed smoke: **one** cell (Node 20 + npm) that still exercises TS 5/6/7 in-process.
-See [CONTRIBUTING.md — CI profiles](../CONTRIBUTING.md#ci-profiles-pr-slim-vs-full-matrix).
+See [CONTRIBUTING.md — CI](../CONTRIBUTING.md#ci-this-repo).
 
 Each cell verifies that the project's `tsc` stays on the requested project compiler and that
 ArkGate resolves its fallback as exact 6.0.3 when the project API is unusable. Reports record

package/docs/use.md

@@ -11,10 +11,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 For **anyone** shipping TypeScript with an AI coding agent.
 
 ---
@@ -24,7 +26,7 @@ For **anyone** shipping TypeScript with an AI coding agent.
 ```bash
 npm install -D arkgate typescript
 npx arkgate start                 # preview what will change
-npx arkgate start --apply         # install compact config + host router + CI plan
+npx arkgate start --apply         # install compact config + host router + CI; merge write-path gates into existing AGENTS.md / .mcp.json
 npx arkgate-check --doctor        # status — one next step
 npx arkgate-check --doctor --all  # full details
 ```
@@ -56,11 +58,10 @@ In those cases a boundary linter or editor rules may be enough; see [README —
 
 ### Why it exists
 
-AI coding agents write code at unprecedented speeds, but they tend to take the shortest path to solve a problem. If an agent needs data in a Domain layer, it might directly import a database adapter. Left unchecked, this creates spaghetti code and technical debt at light speed.
-
-Traditional linters catch these architectural violations in CI *after* the agent has finished its work, breaking the flow and requiring manual intervention.
-
-ArkGate solves this by shifting the check to the exact moment of writing. By intercepting file writes, it ensures that if the agent writes a bad import, the write doesn't land. The agent gets immediate feedback and can self-correct before the code even touches your disk.
+AI takes the shortest path. Contain the write so a bad import never lands. Guide
+the next step so a non-expert is not stuck. Order leftover mess toward a clean
+tree, one small refactor at a time. Traditional linters catch this only after
+the agent finished; ArkGate checks at write time and again on the PR.
 
 ---
 
@@ -86,10 +87,10 @@ The config only binds when the write doesn’t land and CI is required.
 
 | | Plain English | Default |
 |--|---------------|---------|
-| **ArkGate** (layers) | Import rules. The write doesn’t land. The PR fails. | Always — this is the product |
-| **ArkRules** | Optional policies *inside* a layer. | Off until you turn it on (start may ship advisory templates) |
-| **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off. In-memory. Not Postgres. |
-| **ArkOrder** | Stops rewriting a big product choice (like billing plan) as if it were a seat count. Change it through a valve, not a generic update. Library + sensors, [not a service](arkorder.md). | Off. Same npm package (`arkgate/order`). Name the few choices (`xiKeys`). Invoices and seats still flow. In-memory. Not durable. |
+| **ArkGate** (layers) | **Contener** — import rules. The write doesn’t land. The PR fails. | Always — this is the product |
+| **ArkRules** | **Contener** — optional policies *inside* a layer. | Off until you turn it on (start may ship advisory templates) |
+| **ArkRun** | **Guiar** — optional experimental runtime (`arkgate/runtime`) | Off. In-memory. Not Postgres. |
+| **ArkOrder** | **Ordenar** extra — the few big choices (billing plan, not seat counts). Library + sensors, [not a service](arkorder.md). | Off. Same npm package (`arkgate/order`). Name the few choices (`xiKeys`). Invoices and seats still flow. In-memory. Not durable. |
 
 Start always gives you **layers**. Compact starters do **not** turn on ArkRun or
 ArkOrder. No extras is fine — only ArkGate runs. Leftovers are labeled
@@ -97,6 +98,11 @@ ArkOrder. No extras is fine — only ArkGate runs. Leftovers are labeled
 imports ≠ elegant design. Green imports also ≠ a frozen billing plan. ArkRun ≠
 durable stores. ArkOrder does not replace ArkRun.
 
+Want to see the freeze and valve? The billing gallery lives on GitHub, not in
+the npm tarball:
+[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
+First freeze is `release()`. Later plan change is `proposeRelease` then `apply`.
+
 ### New modules vs config edits
 
 **Happy path:** put a new module under an existing layer directory/glob (`layers[].patterns`). Usually
@@ -229,6 +235,7 @@ Empty plan A is **not** “architecture finished.”
 - Plain-language track: [enthusiast/](enthusiast/README.md)  
 - First project tutorial: [enthusiast/tutorial-first-project.md](enthusiast/tutorial-first-project.md)  
 - Demos: [demos/](demos/)  
+- ArkOrder proof (first freeze, then valve): [billing gallery](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) (GitHub, not in the npm tarball)  
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.13",
+  "version": "4.8.14",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",