arkgate 4.8.13 → 4.8.15

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/enthusiast/how-to-pick-shape.md

@@ -26,7 +26,7 @@ Run **`/ark-adopt`** on a greenfield or early-adoption repo (leftover `/ark-arch
 | `adoptInOrder.phase1` | Folders to create first |
 | `analogy` | Plain-language mental model |
 | `antiPatterns` | What Ark will block later |
-| `firstCommand` | Usually `ark init --archetype <id> --yes` |
+| `firstCommand` | Usually `ark start --apply --archetype <id>` |
 
 Framework names appear only as secondary `toolHints` in JSON — never as the archetype label.
 

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`).
@@ -37,7 +39,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
-| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**, **report**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **`arkgate report` / `ark report`** drafts an upstream GitHub issue for `pedroknigge/arkgate` (`package.json` `bugs.url`) — never the consumer repo. **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**, **report**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. Soft ADR presence: when that demand (or doctor `required-merge`) is on and `docs/adr/` / `docs/decisions/` is missing, doctor JSON may add `adrPresence` and human copy points at a short decision note — never a fail, omitted when the demand is off. Soft states/transitions: when a conventional domain doc is already in play and the map is missing or heading-only, doctor JSON may add `statesTransitions` and human copy points at a short table (or one link) — never a fail, omitted when that doc is absent. Narrow status/transition catalog: when Domain-role code already names a closed status/state vocabulary and that map is still thin, doctor JSON may add `statusTransitionCatalog` with those names — never a fail, omitted when Domain has no such vocabulary, the domain doc is absent, or the map is already present. Soft no-Domain / UI-logic residual: when a Domain-role layer is declared but empty and presentation holds the tree (or `domain-logic-in-ui` is already present), doctor JSON may add `noDomainFrontend` and human copy points at one Domain file — never a fail, omitted when there is no frontend, Domain already has files, or the UI bag is too thin. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **`arkgate report` / `ark report`** drafts an upstream GitHub issue for `pedroknigge/arkgate` (`package.json` `bugs.url`) — never the consumer repo. **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
 | **Upstream report CLI (4.8.10)** | `arkgate report` / `ark report` on the existing dual bins (no new bin, no new skill) | Default prints a draft for **upstream** `pedroknigge/arkgate` (`package.json` `bugs.url`) with the arkgate version and optional last-check snippet. Create only with `--submit` **and** `--i-confirm-submit` (after HITL) or TTY `Type submit to send`. `--yes` does not submit. Missing/unauthenticated `gh`: print the draft plus the exact `gh issue create --repo pedroknigge/arkgate` command, exit 2. Never files against the consumer repo. Not `ark-check --report` (HTML architecture report). |
 | **Host write boundaries** | Generated trusted PreToolUse/preToolUse hooks + `ark-mcp --hook`; inspect with doctor/status | Hard is always operation-scoped and runtime-evidenced. From 4.6.3, Codex CLI and local ChatGPT Desktop/App Server can hard-block a complete `apply_patch` sent as `tool_input.command`; `.codex/hooks.json` on disk remains unverified until a fresh covered invocation. Hosted tools, specialized hook opt-outs, shell/direct writes, incomplete reconstruction, and humans rely on required CI. Repair envelopes may emit, but Codex reinjection is not guaranteed. |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
@@ -64,15 +66,17 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth\|arkRun"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. Thin `arkRun` on `latest.json` is `notAScore` residual honesty for `ark status`. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
 | **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
-| **`ark.config.json`** | Layer globs, optional `layers[].description`, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **`ark.config.json`** | Layer globs, optional `layers[].description`, optional `layers[].trustBoundary`, optional `layers[].owners`, optional `requireLayerOwners`, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
 | **Layer caption (`layers[].description`, 4.8.7)** | Optional string on each layer. Projected onto `ark_place` / prepare-write / MCP place JSON, doctor JSON + human, coverage JSON, and the HTML Purpose column when present. `/ark-adopt` writes it from the product map or glossary; `/ark-place` prints it next to layer name + globs. | Existing optional field — **no `schemaVersion` bump**, no new key, no 14th skill. Copy is **app context** (a product sentence such as `Purchase requests — from asked to received.`), not architecture jargon. Stripped from `policyHash` like `stewards`; caption-only edits are neutral. Absence is silent: never a residual, never a score, never `--strict-config` fail, never flips `valid`. Compact starters may omit. |
+| **Layer trust (`layers[].trustBoundary`)** | Optional closed tag on each layer: `public` \| `auth` \| `admin` \| `internal`. Projected onto `ark_place` / prepare-write / MCP place JSON, doctor JSON + human, coverage JSON, and the HTML report when present. `/ark-adopt` writes it when the product map names that door; `/ark-place` prints `trust: public`. | Additive optional field — **no `schemaVersion` bump**, no new skill. Stripped from `policyHash` like `stewards` and `layers[].description`; tag-only edits are neutral. Absence is silent: never a residual, never a score, never `--strict-config` fail, never flips `valid`. Invalid values fail the schema. Compact starters may omit. Not host/CI TLS. Not an import-rule matrix. |
+| **Layer owners (`layers[].owners` + `requireLayerOwners`)** | Optional GitHub handles or emails on each layer. Projected onto place / prepare-write / MCP / doctor / coverage / HTML when present. `requireLayerOwners: true` asks for owners on every live (non-reserved) layer: doctor names the first missing house, `--strict-config` refuses, and the write gate denies a write into that house. | Additive optional fields — **no `schemaVersion` bump**, no new skill. Owners are stripped from `policyHash` like captions; owner-only edits are neutral. The require flag stays in the hash. Absence of owners is silent unless the require flag is on. Invalid identity (display name) fails the schema. Compact starters may omit. Not import-rule teeth. No `/ark-owners`. |
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **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 `--local` / `--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. `--local` (or `ARK_CHECK_LOCAL=1`) is the same cheap path and stays per `--root`; it cannot combine with `--strict-merge`. Check JSON may add `local`, `scope: "changed"`, `analysisRoot`. `stewards`, `layers[].description`, `layers[].trustBoundary`, and `layers[].owners` are excluded from policy hash. `requireLayerOwners` stays in the 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 +88,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` / `validateSkillProductCapacity`; `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). `check:agent-skills` fails closed when a product plane or the north star drops out of skill bodies or living hubs. 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` + `validateSkillProductCapacity`; drift `npm run check:agent-skills` (layout **and** 100% product coverage). 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,11 +26,16 @@ 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
 ```
 
+`start --apply` refuses when projected governed coverage is below 50% or
+shape confidence is weak (below 0.6 with coverage under 80%). That lock is
+deliberate. Lock the shape with `--archetype <id>`, `--preset <name>`, or
+`--force`, or inspect ranked shapes with `npx arkgate-check --recommend`.
+
 Then keep working with your agent. Stuck? Run `--doctor` and do action **#1**. Compact first; `--all` for details.
 
 | Stuck on… | Do this |
@@ -56,11 +63,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 +92,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 +103,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 +240,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.15",
   "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",

package/schemas/ark.config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json",
+  "$id": "https://unpkg.com/arkgate@4/schemas/ark.config.schema.json",
   "title": "ArkGate architecture contract",
   "description": "Versioned contract consumed identically by ArkGate CLI, MCP, and ESLint surfaces.",
   "type": "object",
@@ -16,7 +16,7 @@
     "$schema": {
       "type": "string",
       "minLength": 1,
-      "default": "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json",
+      "default": "https://unpkg.com/arkgate@4/schemas/ark.config.schema.json",
       "description": "Editor-facing URL or local path for this JSON Schema."
     },
     "schemaVersion": {
@@ -650,6 +650,9 @@
       },
       "uniqueItems": true,
       "default": []
+    },
+    "requireLayerOwners": {
+      "type": "boolean"
     }
   },
   "$defs": {
@@ -694,6 +697,24 @@
           "type": "string",
           "minLength": 1
         },
+        "trustBoundary": {
+          "type": "string",
+          "enum": [
+            "public",
+            "auth",
+            "admin",
+            "internal"
+          ]
+        },
+        "owners": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        },
         "forbiddenGlobals": {
           "type": "array",
           "items": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.8.13",
+  "version": "4.8.15",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.13",
+      "version": "4.8.15",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/README.md

@@ -4,13 +4,15 @@
 > Author skill bodies in `templates/skills/<name>.md`, then run
 > `npm run generate:agent-skills`. Drift: `npm run check:agent-skills`.
 
-This directory is the **Agent Skills–compatible** packaging of the same **13**
-`/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
+This directory is the **Agent Skills–compatible** packaging of the same
+closed `/ark-*` catalog shipped as flat templates for Ark install.
+**Closed catalog** (`ARK_SKILL_NAMES`) — first-class doors plus one-release
+redirect stubs. Add a name only with a live ROADMAP item.
 
-Package version when last generated context: **arkgate@4.8.9**
+Package version when last generated context: **arkgate@4.8.15**
 Schema: agent-skills package contract `1.0`
 
-## Skills (frozen catalog)
+## Skills (closed catalog)
 
 - `ark-adopt`
 - `ark-architect`
@@ -21,6 +23,7 @@ Schema: agent-skills package contract `1.0`
 - `ark-explore`
 - `ark-fix`
 - `ark-loop`
+- `ark-order`
 - `ark-place`
 - `ark-runtime`
 - `ark-think`

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -5,6 +5,10 @@ description: Session 0 — write the rules file (ark.config.json) to match the r
 
 # /ark-adopt — Mark the path (session 0)
 
+**Contener · Guiar · Ordenar.** In plain words: contain the write, guide the next
+step, order leftover mess. This door is **Contener**: write the path so the tree
+has honest houses. Skills never enforce — CLI / hooks / CI do.
+
 **When:** empty tree, or the rules file does not match the real folders (session 0).
 **Not when:** a single new file (`/ark-place`) or leftover design after the path is honest (`/ark-explore` then `/ark-autopilot`).
 
@@ -17,11 +21,33 @@ description: Session 0 — write the rules file (ark.config.json) to match the r
 ## Checklist
 
 - Existing tree: propose **SharedKernel** (types/constants) + **CompositionRoot** (wiring) + `src/**/domain/**`. Never dump bare `src/lib/**` into Application.
+- Every `include` path must land in a layer. Include that classifies no file is the
+  same as an empty check — not a pass. Fix globs here; do not leave a loose gap.
 - Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
 - Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
 - When the product map or glossary names a house, write `layers[].description` as
   app-context copy (what this folder is *in the product*). Compact starter may omit.
   Do not invent captions. Do not invent `/ark-describe`.
+- When the product map names who a folder is for, write `layers[].trustBoundary`
+  (`public` | `auth` | `admin` | `internal`). Compact starter may omit. Do not
+  invent tags. Absence is silent. No `/ark-trust`.
+- When the product map names who owns a folder, write `layers[].owners`
+  (GitHub handle or email). Compact starter may omit. Do not invent people.
+  Absence is silent unless the user asked for required owners — then write
+  `requireLayerOwners: true` after the live houses have names. No `/ark-owners`.
+- When the user wants required gates (`--require-gates` / `--strict-merge` /
+  required GitHub check) and there is no `docs/adr/` (or `docs/decisions/`),
+  leave a short decision note there — only if they loosen a rule or add a real
+  gate. Not every change. Doctor residual is soft. No `/ark-adr`.
+- When a product-domain doc is already in play (`docs/domain.md` or a sibling)
+  and doctor JSON has `statesTransitions` or `statusTransitionCatalog`, add a
+  short states → transitions table (or one link) there. Use catalog names when
+  present. No flag soup. Soft residual. Silent when that doc is absent or
+  Domain has no status vocabulary. No `/ark-states`.
+- When doctor JSON has `noDomainFrontend`, keep the empty Domain house — do not
+  delete it to “clean” empty layers. Next is one Domain file (`/ark-place`), not
+  a weaker contract. Soft. Silent when there is no frontend or Domain already
+  has files. No `/ark-domain`.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
@@ -102,6 +128,46 @@ received."), not architecture jargon. Compact starter / `ark start` may omit the
 field. Absence is silent — never fail `--strict-config` for a missing caption.
 Do **not** invent captions. Do not invent `/ark-describe`.
 
+## Layer trust (process)
+
+Optional `layers[].trustBoundary`: `public` | `auth` | `admin` | `internal`.
+Marks who this folder is for (anyone, signed-in users, operators, or only
+other code). Write it when the product map already names that door. Compact
+starter / `ark start` may omit it. Absence is silent — never fail
+`--strict-config`, never invent a doctor residual. Do **not** invent tags.
+This is not host/CI TLS and does not add import-rule teeth. No `/ark-trust`.
+
+## Layer owners (process)
+
+Optional `layers[].owners`: GitHub handles or emails (same identity as
+`stewards` — not a display name). Write them when the product map already
+names who owns the house. Compact starter / `ark start` may omit. Absence is
+silent unless the user asked for required owners. Then write
+`requireLayerOwners: true` only after every live (non-reserved) layer has
+at least one owner. Do **not** invent people. No `/ark-owners`. The require
+flag is the fail-closed switch; owners themselves are metadata.
+
+## Decision notes (process)
+
+When gates are required (`--require-gates` / `--strict-merge` / required merge
+status) and there is no short decision-note home yet, doctor may ask for one
+under `docs/adr/` or `docs/decisions/`. Write a note when you loosen a rule or
+add a real gate — not on every file. Absence is silent unless that demand is
+on. The hint does not fail the check. Do **not** invent `/ark-adr`. Policy
+weaken still uses `--policy-ack`; this is only a place to write the why.
+
+## States and transitions (process)
+
+When a product-domain / domain-model doc is already on disk (`docs/domain.md`,
+`docs/data-model.md`, or a dedicated `docs/states.md`) and there is no short
+states → transitions table (or one link), doctor may ask for one. Write the
+table on that home — entity · states · allowed from → to. Names from the
+code or the captain. When doctor JSON has `statusTransitionCatalog`, use those
+entity · states names — Domain already opted in by having that vocabulary.
+Do **not** invent states or flag soup. Absence of the domain doc, or Domain
+with no status union/enum, stays silent. The hint does not fail the check.
+Do **not** invent `/ark-states`. Do not walk the tree to invent a roster.
+
 ## When / not when
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
@@ -111,7 +177,7 @@ Do **not** invent captions. Do not invent `/ark-describe`.
 | Mine loose business rules into Domain / advisory ArkRules | Apply leftover design after the path is honest → `/ark-autopilot` |
 | Freeze **real** debt after the config is honest | User said map only |
 | Turn **advisory** ArkRun on (`arkRun` extra, schema `1.2+`; **`kernelRoots` preferred**) | Evaluate / wire a hand-rolled bus → `/ark-runtime`; new kernel-managed file → `/ark-place` |
-| Turn **advisory** ArkOrder on (`arkOrder` extra, schema `1.3+`, `planeRoots`) | New plane-root file after extra is on → `/ark-place`; grind skip clusters → `/ark-autopilot` |
+| Turn **advisory** ArkOrder on (`arkOrder` extra, schema `1.3+`, `planeRoots`) | Wire one plane candidate after extra is on → `/ark-order`; new plane-root file → `/ark-place`; grind skip clusters → `/ark-autopilot` |
 
 ## Dual engine (mandatory)
 
@@ -147,14 +213,15 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
 3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
 4. Editing `arkrules/*` or promoting modes is **this skill** (session 0) or **`/ark-autopilot`** later; never invent `mechanical-safe`.
-5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` / `INVARIANT_CATALOG_EMPTY` with `evidence.arkruleId`.
 6. Absence of `arkRun` is **valid**. Write it only when the user wants the extra. Skills never enforce.
-7. Absence of `arkOrder` is **valid**. Write it only when the user wants the extra. Do not invent `/ark-order`. Skills never enforce.
+7. Absence of `arkOrder` is **valid**. Write it only when the user wants the extra. After the extra is honest: handoff **`/ark-order`** to wire one candidate. Skills never enforce.
 
 
 ### Adopt + ArkRules
 - After classify: emit or refresh `arkRules` for matched layers (exact names; generic mold for unknowns).
 - Mine rules → inventory + write advisory invariants/structure into `arkrules/<Layer>.json` **in this turn**.
+- Empty `invariants[]` on a populated Domain while `arkRules` is on is residual (`INVARIANT_CATALOG_EMPTY`), not done. Fill 1–2 short phrases. Advisory until a domain structure rule is `enforced`.
 - Application / Features templates include advisory `writes-via-aggregate`: driver import + write token in a use case is the skip. Do not copy `Externals/` / `admission.ts` folder religion.
 - Freeze baseline is **[Layer]** debt; inventory residual is **[ArkRules]** — report both.
 
@@ -191,9 +258,9 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 - A use-case that `prisma.*.update({ plan })` while `plan` is in `xiKeys` is **[ArkOrder]** `ARKORDER_XI_FIELD_WRITE`. Invoices and seats still flow through `ingest`.
 
 - Do **not** put `arkOrder` on the compact starter / `ark start` scaffold. Domain stays plane-free. Import `createOrderPlane` from `arkgate/order` (same npm package).
-- Absence is valid and **silent** — never force the extra. Do not invent `/ark-order`.
+- Absence is valid and **silent** — never force the extra.
 - Demoting enforced → advisory or deleting the extra is policy-delta **weakening**.
-- After the extra is honest: handoff `/ark-place` for new plane-root files; grind skip via `/ark-autopilot`. Skills never enforce.
+- After the extra is honest: handoff **`/ark-order`** to wire one candidate, `/ark-place` for new plane-root files; grind skip via `/ark-autopilot`. Skills never enforce.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -218,6 +285,9 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 - **Brownfield:** this skill — match config to reality; do not force a starter preset.
 - **Deep map only:** `/ark-explore`.
 - **Default path:** `ark start` → **`/ark-adopt`** → `/ark-place` / `/ark-autopilot`.
+  `start --apply` may refuse (coverage below 50% or weak shape) — that lock is
+  deliberate. Lock the shape with `--archetype`, `--preset`, or `--force`, or
+  inspect ranked shapes with `ark-check --recommend`.
 
 ## Anti-wrapper rule (mandatory)
 
@@ -244,6 +314,9 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    If `src/contexts` or `src/bounded-contexts` exists, prefer `ddd-bounded-contexts`.
    **Next.js:** `app/api/**` / `pages/api/**` (and route-group `app/(…)/api/**`) default to
    **ApplicationOrchestration**, not Presentation — do not reclassify API shells as UI.
+   Write Next-flavored `layers[].description` only when Next is actually present
+   (`next` dependency, `next.config.*`, or `app/page` / `pages/*` routes). Library and
+   package monorepos keep framework-free captions — `ark start` already does this.
    User wants the ArkRun extra → write **advisory** `arkRun` (schema `1.2+`, real
    `kernelRoots` preferred — `compositionRoots` alias, existing `managedLayers`) **in this turn**.
    User wants the ArkOrder extra → write **advisory** `arkOrder` (schema `1.3+`, real
@@ -251,6 +324,12 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    to a compact starter. Do not promote to enforced as the session-0 default.
    When the product map or glossary names a house, write `layers[].description` on that
    layer (app-context sentence). Compact starter may omit. Do not invent captions.
+   When the product map names who a folder is for, write `layers[].trustBoundary`
+   (`public` | `auth` | `admin` | `internal`). Do not invent tags.
+   When the product map names who owns a folder, write `layers[].owners`
+   (GitHub handle or email). Do not invent people. Write `requireLayerOwners`
+   only when the user asked for required owners and the live houses already
+   have names.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
    The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
@@ -264,6 +343,8 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
 3. **Classify ungoverned** — use coverage `suggestions` **plus** dirs you discovered by reading;
    add layers/patterns **here** (write `ark.config.json`). When adding a layer the product map
    or glossary already names, write `layers[].description` on it (do not invent filler).
+   Write `layers[].trustBoundary` only when the product map already names that door.
+   Write `layers[].owners` only when the product map already names who owns the house.
 4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
    - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
    - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
@@ -301,8 +382,12 @@ proposals applied or deferred, **phase**, **top Shape / design-weak opportunitie
 - Force runtime kernel over existing Nest/DI.
 - Put `arkRun` or `arkOrder` on the compact starter / `ark start` scaffold.
 - Claim in-memory kernel stores are production durability.
-- Invent `/ark-run` or `/ark-order`.
+- Invent `/ark-run`. Use `/ark-order` after this door turns the extra on.
 - Invent `layers[].description` filler or a `/ark-describe` skill.
+- Invent `layers[].trustBoundary` tags or a `/ark-trust` skill.
+- Invent `layers[].owners` names or a `/ark-owners` skill.
+- Invent `/ark-adr` or require a decision note on every change.
+- Invent `/ark-states` or invent entity states / flag soup.
 - Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
 - End adopt with only “baseline written” when design-weak residual is visible in files you opened.