arkgate 4.8.13 → 4.8.15

package/dist/{types-Djbs3KjE.d.ts → types-CN9tVMPz.d.ts}

@@ -1,4 +1,4 @@
-import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-j7so8B4O.js';
+import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-Dt3DpVbd.js';
 
 /**
  * Policy types for the Ark kernel.
@@ -145,6 +145,8 @@ interface ArchitectureLayer {
      */
     match?: (name: string) => boolean;
     description?: string;
+    trustBoundary?: 'public' | 'auth' | 'admin' | 'internal';
+    owners?: string[];
     order?: number;
 }
 type ArchitectureRule = ArkConfigRule;

package/dist/{types-tGhZUiGX.d.ts → types-TBiv0WHL.d.ts}

@@ -1,4 +1,4 @@
-import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-Djbs3KjE.js';
+import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-CN9tVMPz.js';
 
 /**
  * PolicyEngine

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.15`; not published until `publish-npm` for `v4.8.15`).
 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.
 
@@ -44,7 +46,8 @@ ark start → ark start --apply → ark-check --doctor
 
 `arkgate-check --doctor` shows what's wrong and what to do first. From **4.0.0**, doctor may
 also report **`rulesUnderContract`** (ArkRules counts) and **`packageVersionTruth`** when the
-CLI is ahead of the package.json pin. The compact router from `ark start` is enough for normal
+CLI is ahead of the package.json pin. Compact doctor names ArkRules only when the
+`arkRules` map is on — absence stays silent. The compact router from `ark start` is enough for normal
 feature work. Full `/ark-*` skills are **expert depth** and label residual **`[Layer]`** vs
 **`[ArkRules]`** (except experimental `/ark-runtime`):
 
@@ -227,10 +230,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`
@@ -271,7 +280,7 @@ npx ark-check --recommend --json
 `--recommend` does not require `ark.config.json`. It exits `0` and prints a progressive
 adoption plan: archetype id, preset, `confidence`, `runnerUp`, `why` (shape signals),
 structured positive/negative `evidence`, discovered `signals.packageUnits`,
-`adoptInOrder.phase1`, `firstCommand` (`ark init --archetype …`), and `checkCommand`.
+`adoptInOrder.phase1`, `firstCommand` (`ark start --apply --archetype …`), and `checkCommand`.
 When the top two shapes are close or projected governed coverage is below 90%, JSON sets
 `requiresConfirmation: true` and explains why in `confirmationReasons`.
 
@@ -316,12 +325,15 @@ 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
-`ark-check --changed --base <merge-ref>` in local gates. `--contract-diff` + `--author`
+`ark-check --local --base <merge-ref>` (or `--changed --base`) in local gates.
+`--strict-merge` stays the CI merge line. `--contract-diff` + `--author`
 when `stewards` is set (`--author` is a GitHub handle or email, not git `user.name`).
 `ark status --vs <ref>` prints pin / contract / baseline drift.
 
@@ -537,7 +549,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 +770,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 +835,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 +869,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 |
 |---------|------------------|-------------|
@@ -868,7 +885,7 @@ routing only.
 **Canonical authoring source:** flat `templates/skills/<name>.md` (Ark install reads these).
 
 **Agent Skills package root** (generated, 1:1 content): `templates/agent-skills/<name>/SKILL.md`
-— ships in the npm tarball under `templates/`. Drift guard: `npm run check:agent-skills`.
+— ships in the npm tarball under `templates/`. Drift guard: `npm run check:agent-skills` (layout 1:1 **and** 100% product coverage).
 
 ```bash
 # Ark — expert skill pack (preferred when you also want gates)
@@ -883,9 +900,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) ·
@@ -26,7 +28,7 @@ overview: [develop.md](develop.md) · hub: [README.md](README.md).
 | **Claude Code** | Hard PreToolUse for listed ops when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
 | **Grok Build** | Hard PreToolUse for listed ops when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
 | **Google Antigravity** | Hard PreToolUse for listed write tools when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
-| **Cursor** | Hard preToolUse for Write/StrReplace when installed + trusted + runtime-observed | Required CI status (same check) |
+| **Cursor** | Hard preToolUse for Write/StrReplace when installed + trusted + `failClosed` + runtime-observed | Required CI status (same check) |
 | **OpenAI Codex** | Hard PreToolUse for complete local `apply_patch` in CLI/Desktop when installed + trusted + runtime-observed | Required CI status (same check) |
 | **OpenCode** | **Advisory / best-effort** (MCP + optional experimental plugin) — **not** a hard boundary | Required CI status (same check) |
 
@@ -124,6 +126,11 @@ violations relative to the file's current on-disk state, so files with pre-exist
 (baselined) violations stay editable — they just can't get worse. New files block on
 every violation.
 
+The hook classifies import targets with the same `layerForRelativePath` specificity as
+`ark-check` (an explicit file pattern beats a broader glob such as `src/lib/**`).
+`LEXICAL_EVIDENCE_INCOMPLETE` means the single-file check is provisional — `ark-check`
+on the tree is the authority. Do not move files solely because the hook named a layer.
+
 ### Opt-in resident hook pilot (Z07)
 
 Set `ARK_RESIDENT_HOOK=1` on both `ark-mcp` and its hook command. The pilot reuses the
@@ -327,8 +334,10 @@ Cursor supports MCP servers (`.cursor/mcp.json`) and project hooks (`.cursor/hoo
 }
 ```
 
-When that hook is installed and trusted, Cursor **hard-blocks** agent `Write` / `StrReplace`
-for governed TypeScript sources (exit 2 or `permission: "deny"`). Repair envelopes may emit;
+When that hook is installed and trusted **and** `failClosed` is `true`, Cursor **hard-blocks**
+agent `Write` / `StrReplace` for governed TypeScript sources (exit 2 or `permission: "deny"`).
+A hook without `failClosed` is fail-open: if the checker cannot run, the write still lands
+(same idea as a file permission — no checker, no write). Repair envelopes may emit;
 Cursor does **not** guarantee Write `updated_input` reinjection — the agent must fix and retry
 from `agent_message`. Shell, Tab, and human edits still rely on CI.
 

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/brownfield-adoption.md

@@ -48,7 +48,10 @@ regenerate it unasked.
 
 Without this split, broad `**/app/**` Presentation patterns push every API handler into UI and
 create a Presentation→Persistence tsunami. Specificity still wins: more-specific Application
-globs beat Presentation. Adopt writes `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
+globs beat Presentation. **Captions** (what doctor prints next to the layer name) mention Next
+App Router / Pages API / `app/api` only when Next is actually present — a library
+`packages/*` monorepo keeps library-native language. Adopt writes `.ark/golden-pattern.json`
+(load-bearing for `/ark-place`).
 `ark_place` requires `filePath` (fail-closed — never invents `components/*.tsx` or defaults to Presentation).
 ArkRules stay **opt-in** (not forced on by start/adopt).
 

package/docs/configuration.md

@@ -9,7 +9,7 @@ The CLI, MCP server, and ESLint plugin all use the same parser, migration, defau
 
 ```json
 {
-  "$schema": "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json",
+  "$schema": "https://unpkg.com/arkgate@4/schemas/ark.config.schema.json",
   "schemaVersion": "1.3",
   "include": ["src"],
   "layers": [],
@@ -179,6 +179,45 @@ Layer fields:
 ```
 
 That sentence is product copy. Not “Rich domain model, business rules, and domain events.”
+- **`layers[].trustBoundary`** (optional) — who this folder is for: `public` |
+  `auth` | `admin` | `internal`. Anyone, signed-in users, operators, or only
+  other code. `/ark-place` prints `trust: public` next to the layer name;
+  doctor, coverage, and the HTML report show the same tag. Changing the tag
+  does **not** change `policyHash` (same strip as `stewards` and
+  `layers[].description`) and does **not** need a weakening ack. Absence is
+  silent: never fails `--strict-config`, never invents a doctor residual, never
+  flips `valid`. A wrong value (`"trusted"`, empty string) fails the schema.
+  Compact starters may omit it. `/ark-adopt` writes it when the product map
+  already names that door; it does not invent tags. No `/ark-trust`. This is
+  **not** host/CI TLS and does **not** add import-rule teeth.
+- **`layers[].owners`** (optional) — who owns this folder: GitHub handles or
+  emails (same identity as `stewards`). `/ark-place` prints `owner: @handle`
+  next to the layer name; doctor, coverage, and the HTML report show the same
+  names. Changing the list does **not** change `policyHash` and does **not**
+  need a weakening ack. Absence is silent unless **`requireLayerOwners`** is
+  `true`. A display name (`Pedro Knigge`), empty array, or empty string fails
+  the schema. Compact starters may omit it. `/ark-adopt` writes it when the
+  product map already names who owns the house; it does not invent people.
+  No `/ark-owners`. This is **not** import-rule teeth.
+- **`requireLayerOwners`** (optional) — when `true`, every live (non-reserved)
+  layer must name `owners`. Doctor names the first missing house and the next
+  step. `--strict-config` / `--strict-merge` refuse. The write gate denies a
+  write into an unowned house (same idea as a folder with no name on the door).
+  Absence or `false` is silent. This flag **is** policy teeth (it stays in
+  `policyHash`). Flip it on after you have named owners incrementally.
+
+```json
+"layers": [
+  {
+    "name": "Presentation",
+    "patterns": ["src/app/**"],
+    "description": "Storefront checkout — what shoppers see.",
+    "trustBoundary": "public",
+    "owners": ["pedroknigge"]
+  }
+]
+```
+
 - `intentPrefixes`, `forbiddenGlobals`, `mayImportInfrastructure`, `optional`
 - `reserved` / `allowEmpty` — future houses whose globs match nothing yet. `--strict-config` does not fail; `CONFIG_LAYER_PATTERN_NO_MATCHES` (typo warning) is skipped. A typo warning fires only when the glob is not reserved.
 - `capabilities: { deny: [...] }` — opt-in effect walls over the seven capability ids
@@ -297,9 +336,12 @@ steps under `plan.typeOnlyGroup` when volume is high.
 
 ### Next.js API shell (framework overlay / presets)
 
-When Next is detected (or `ui-surface` / monorepo patterns apply), **`app/api/**` and
-`pages/api/**` classify as Application orchestration**, not Presentation. UI routes stay
-Presentation. More-specific Application globs win over broad `**/app/**` Presentation patterns.
+When Next is detected, **`app/api/**` and `pages/api/**` classify as Application
+orchestration**, not Presentation. UI routes stay Presentation. More-specific Application
+globs win over broad `**/app/**` Presentation patterns. Reserved `app/api` globs may still
+appear on `ui-surface` / monorepo presets so a later Next route classifies correctly;
+**layer captions** mention Next App Router / Pages API / `app/api` only when Next is
+actually present. Library and package-monorepo start keep library-native captions.
 See [brownfield adoption](brownfield-adoption.md#nextjs-honesty-default-overlays--ui-surface--monorepo).
 
 ### ArkRules dual plane (when `arkRules` is present)
@@ -359,6 +401,9 @@ invariants, and a covered sample when the map is active.
 a hash-bound policy weakening. Empty `appliesTo: []` fails closed; zero-match globs emit
 `ARKRULE_SCOPE_EMPTY` (advisory warn / enforced fail). Enforced + proven uncovered →
 `INVARIANT_UNCOVERED` with `failsStrict` (partial evidence stays honest, never fake-green).
+When `arkRules` is on and a Domain-role layer has code, empty `invariants[]` is doctor residual
+`INVARIANT_CATALOG_EMPTY` (not “done”). Advisory unless a domain structure rule is already
+`enforced` — then `--strict-merge` can refuse. Absence of `arkRules` stays silent.
 
 **What they do not do:** prove business semantics end-to-end; replace Layers import edges;
 make “green” mean elegant Shape. Promoting structure to enforced can force rename-to-pass
@@ -415,7 +460,7 @@ changing either contract changes its hash and invalidates the acknowledgement.
 
 Optional `stewards` lists **GitHub handles or emails** who may **loosen** the contract or
 **grow** the baseline (`pedroknigge` or `pedroknigge@users.noreply.github.com` — not
-`Pedro Knigge`). The field is metadata — it does not change the policy hash. `layers[].description` is stripped the same way (caption-only edits do not change `policyHash` and do not need a weakening ack; `contractHash` still fingerprints the raw config). The lock
+`Pedro Knigge`). The field is metadata — it does not change the policy hash. `layers[].description`, `layers[].trustBoundary`, and `layers[].owners` are stripped the same way (caption-only, tag-only, or owner-list edits do not change `policyHash` and do not need a weakening ack; `contractHash` still fingerprints the raw config). `requireLayerOwners` stays in the hash. The lock
 matches `--author`, then `GITHUB_ACTOR` / `ARK_STEWARD`, then `GIT_AUTHOR_EMAIL`. A
 noreply GitHub mail and the handle are the same person. Git `user.name` is not identity.
 
@@ -442,6 +487,7 @@ type than product source:
 
 | Check | What it does |
 |-------|----------------|
+| `ark-check --local --base origin/dev` | Opt-in local / multi-worktree cheap check. Same engine as `--changed`. Refused with `--strict-merge`. `ARK_CHECK_LOCAL=1` is the same unless CI or a full-tree report mode is on. |
 | `ark-check --changed --base origin/dev` | Layer check on touched sources only. A CSS/i18n PR pays almost nothing. |
 | `ark-check --against origin/dev` | New violation keys vs **that ref's** baseline (not only HEAD). |
 | `ark-check --contract-diff --base origin/dev` | Classifies tighten / loosen / reclassify / baseline-grow. |
@@ -450,15 +496,18 @@ type than product source:
 | `ark status --vs origin/dev` | One line: pin / contract / baseline drift vs that ref. |
 
 Write-gate ApplyPatch denies a batch that mixes law files with product source. Humans who
-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.
+never hit PreToolUse are unchanged. Local `pnpm` gates should call `--local --base` or
+`--changed --base`, not only full-tree `--strict-merge`. Write hooks stay on the lexical
+snippet path — they do not run a full-tree check. Analysis is per `--root` (each git
+worktree has its own root); there is no machine-wide analysis lock.
+
+`--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
@@ -164,6 +166,7 @@ npx arkgate agents-md --write       # embed/refresh projection markers
 npx arkgate preflight --changes changes.json --json
 npx arkgate upgrade --json          # managed content preview
 npx arkgate upgrade --apply
+npx arkgate-check --local --base origin/dev
 npx arkgate-check --changed --base origin/dev
 npx arkgate-check --against origin/dev
 npx arkgate status --vs origin/dev

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 |
@@ -44,6 +44,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKRULE_INVARIANT`](#ARKRULE_INVARIANT) | arkrules | ArkRule invariant failed |
 | [`ARKRULE_SCOPE_EMPTY`](#ARKRULE_SCOPE_EMPTY) | arkrules | ArkRule appliesTo matched zero files |
 | [`ARKRULE_HINT_BUDGET_EXHAUSTED`](#ARKRULE_HINT_BUDGET_EXHAUSTED) | arkrules | Structural-hint budget exhausted |
+| [`INVARIANT_CATALOG_EMPTY`](#INVARIANT_CATALOG_EMPTY) | arkrules | Domain invariant catalog is empty |
 | [`INVARIANT_UNCOVERED`](#INVARIANT_UNCOVERED) | arkrules | Invariant without coverage evidence |
 | [`INVARIANT_COVERAGE_OUTSIDE_ROOTS`](#INVARIANT_COVERAGE_OUTSIDE_ROOTS) | arkrules | Covering test outside the declared coverage roots |
 | [`ARKRUN_MISSING_ROOT`](#ARKRUN_MISSING_ROOT) | arkrun | No kernel factory in composition roots |
@@ -58,7 +59,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 |
@@ -97,6 +98,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`CONFIG_RULE_UNKNOWN_TO_LAYER`](#CONFIG_RULE_UNKNOWN_TO_LAYER) | config | Rule unknown to layer |
 | [`CONFIG_AMBIGUOUS_LAYERS`](#CONFIG_AMBIGUOUS_LAYERS) | config | Ambiguous layer classification |
 | [`CONFIG_UNCLASSIFIED_FILES`](#CONFIG_UNCLASSIFIED_FILES) | config | Unclassified included files |
+| [`CONFIG_LAYER_MISSING_OWNER`](#CONFIG_LAYER_MISSING_OWNER) | config | Layer missing owner |
 | [`ARK_UNKNOWN`](#ARK_UNKNOWN) | meta | Unknown diagnostic |
 
 ## Layer and dependency graph
@@ -105,9 +107,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>
@@ -289,6 +291,15 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 - **Why:** `orchestration-only`, `thin-adapter`, and `writes-via-aggregate` only evaluate files the hint loader preloaded. When eligible governed files exceed that budget (`coverage.maxFiles`, default `400` — there is no `arkrules.hintBudget`), those sensors never saw the rest of their scope. Enforced + unreviewed is not green. The finding names exact hinted/governed counts and per-sensor reviewed N/M of scope.
 - **Fix:** Raise `coverage.maxFiles` in ark.config.json (this cap also bounds structural-hint preload; `--doctor` names the coupling) so hinted/governed counts match, then re-run with `--strict-config`. An enforced hint sensor that cannot see its scope fails strict.
 
+<a id="INVARIANT_CATALOG_EMPTY"></a>
+
+### `INVARIANT_CATALOG_EMPTY`
+
+**Domain invariant catalog is empty** · often advisory
+
+- **Why:** ArkRules is on and a Domain-role layer has code, but `invariants[]` has no phrases the code must preserve. Empty looks like “done” until someone fills the catalog.
+- **Fix:** Add 1–2 short phrases to `invariants[]` in `arkrules/<Domain>.json` (or the mapped file). Starters show the shape. Advisory unless a domain structure rule is already enforced — then `--strict-merge` can refuse. Do not freeze this finding.
+
 <a id="INVARIANT_UNCOVERED"></a>
 
 ### `INVARIANT_UNCOVERED`
@@ -466,10 +477,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
 
@@ -589,8 +600,8 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 
 **Lexical evidence incomplete**
 
-- **Why:** Single-file validation cannot prove project module resolution. The write hook is already the verdict.
-- **Fix:** Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call `ark_prepare_change` from a hook deny.
+- **Why:** This check only saw one file, so it cannot fully prove how the import resolves. The result is provisional — `ark-check` on the project is the authority.
+- **Fix:** Run `npx arkgate-check --root . --config ark.config.json` to confirm. Do not call `ark_prepare_change` from a hook deny.
 
 <a id="ANALYSIS_COVERS_NO_FILES"></a>
 
@@ -598,7 +609,7 @@ Haken slaving: few slow keys (ξ) determine derived fast state. Field ingest nev
 
 **Analysis covered no files**
 
-- **Why:** No file matched the contract `include` and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a `--root` that is not the tree the contract describes (including a contract found outside the requested root, whose directory is then adopted as the project root), `include` / `exclude` patterns that match nothing, or layer patterns written for a different layout.
+- **Why:** No file matched the contract `include` and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a `--root` that is not the tree the contract describes (including a contract found outside the requested root, whose directory is then adopted as the project root), `include` / `exclude` patterns that match nothing, layer patterns written for a different layout, or an `include` that matched files none of which belong to a layer.
 - **Fix:** Point `--root` at the tree the contract describes, or keep the contract inside that tree, or fix the `include` / `exclude` / layer patterns so they match real files — then re-run `npx arkgate-check --root . --config ark.config.json`. `--plan` and `--coverage` report the empty scope without refusing, and `--adopt-contract --write` proposes an `include` that matches the tree. This is a refusal about ArkGate's own inputs, not a finding about your code; no baseline or policy acknowledgement can suppress it, and `exclude` cannot silence it — the "is there source here" probe deliberately ignores the contract's own `exclude`, skips dot-directories, never follows a symlink, and skips `*.config.*` tooling files so a polyglot repo is not mistaken for a mismatch.
 
 <a id="ANALYSIS_HOST_UNAVAILABLE"></a>
@@ -850,6 +861,15 @@ never opting out of knowing.
 - **Why:** Included source files match no layer pattern; import rules will not enforce on them.
 - **Fix:** Extend layer patterns or narrow include so every governed file is classified.
 
+<a id="CONFIG_LAYER_MISSING_OWNER"></a>
+
+### `CONFIG_LAYER_MISSING_OWNER`
+
+**Layer missing owner**
+
+- **Why:** `requireLayerOwners` is on and this layer has no owners. Writes to that house fail closed, like a folder with no name on the door.
+- **Fix:** Add a GitHub handle or email to that layer’s owners in ark.config.json (`/ark-adopt`), then re-run. Reserved/allowEmpty houses may stay unnamed.
+
 ## Meta
 
 <a id="ARK_UNKNOWN"></a>

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-agent-gates.md

@@ -49,6 +49,11 @@ server with an explicit project root, compact Codex must contain valid project c
 SessionStart/PreToolUse Ark hooks, and CI must execute a fail-closed Ark command. Included but
 unclassified source files therefore remain red.
 
+If gates are required and the tree has no short decision note yet (`docs/adr/` or
+`docs/decisions/`), `--require-gates` and doctor point at that path. Soft hint —
+not a fail, and silent when `--require-gates` is off. Not every change needs a
+note; use one when you loosen a rule or add a real gate.
+
 Doctor JSON includes `writePath.mode` plus `enforcementLadder`: support, installation, observed
 evidence, covered operations, bypassability, and CI honesty. MCP registration stays advisory.