arkgate 4.7.0 → 4.7.2

package/docs/README.md

@@ -1,6 +1,8 @@
 # ArkGate documentation
 
-**ArkGate** keeps AI-written TypeScript inside an architecture you can trust.
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules
+file is just documentation.
 
 Pick your path. Skip everything else.
 
@@ -53,14 +55,14 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · npm [CHANGELOG.md](../CHANGELOG.md) (Unreleased + 4.6.x) · [pre-4.6 archive](archive/CHANGELOG-pre-4.6.md) |
-| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN15` done; `RN16` preparing **4.7.0**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). |
+| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN16` done; shipped **4.7.0**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current tree: [releases/4.7.0.md](releases/4.7.0.md) (`arkgate@4.7.0` prepared).
-Current published: [releases/4.6.7.md](releases/4.6.7.md) (`arkgate@4.6.7` on npm `latest`).
-Prior: [releases/4.6.6.md](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
+Current tree: [releases/4.7.2.md](releases/4.7.2.md) (`arkgate@4.7.2`, prepared).
+Current published: [releases/4.7.1.md](releases/4.7.1.md) (`arkgate@4.7.1` on npm `latest`).
+Prior: [releases/4.7.0.md](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
 Older notes: [releases/](releases/). Config: [configuration.md](configuration.md).
 
 ---
@@ -71,3 +73,4 @@ Older notes: [releases/](releases/). Config: [configuration.md](configuration.md
 2. **One primary flow** — `start` → doctor → optional guided work.
 3. **Honest hardness** — host write guarantees differ; a **required GitHub status context** running the merge CLI is the shared hard boundary.
 4. **History is not the product** — version archaeology lives under `releases/` and `plans/`, not the front door.
+5. **Common language** — first-contact copy uses ordinary software words (import rules, rejected write, required CI). Brands are categorical. Voice: [product-voice.md](product-voice.md).

package/docs/agent-guide.md

@@ -1,7 +1,8 @@
 # ArkGate — Agent Integration Guide
 
-**ArkGate** (`arkgate`) — architecture co-pilot for AI TypeScript. This guide is the **develop**
-reference for agents and codegen: write hooks, advisory MCP tools, CI, and `/ark-*` skills.
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
+This guide is the **develop** reference for agents and codegen: write hooks, advisory MCP tools,
+CI, and `/ark-*` skills. Not an API Gateway. Not a folder linter.
 
 - Product path (anyone): [use.md](use.md)  
 - Integration overview: [develop.md](develop.md)  
@@ -28,7 +29,7 @@ ark start → ark start --apply → ark-check --doctor
   optional: arkRules map + arkrules/*.json (intra-layer; starts advisory)
 ```
 
-Doctor is the **control plane** (status light + primary next action). From **4.0.0**, doctor may
+`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
 feature work. Full `/ark-*` skills are **expert depth** and label residual **`[Layer]`** vs
@@ -540,7 +541,7 @@ reference, and explanation for the full path (recommend → init → gallery →
 
 ### Agent workflow (before codegen)
 
-**Default path first:** `ark start` → `ark start --apply` → `ark-check --doctor`. Doctor’s primary next action is the control plane; do not skill-shop around it.
+**Default path first:** `ark start` → `ark start --apply` → `ark-check --doctor`. Do action #1; do not skill-shop around it.
 
 Greenfield / empty-tree **depth** (only when doctor or a thin tree points here — not a second day-zero curriculum):
 
@@ -626,7 +627,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 | Host | Installed paths | Skills path |
 |------|-----------------|-------------|
 | Claude Code | `.claude/settings.json` hook + `.mcp.json` / `claude mcp add` | **Repo:** `.claude/skills/<name>/SKILL.md`; **home:** `$CLAUDE_HOME/skills` (default `~/.claude/skills`, `--claude-home`) |
-| Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` (Cursor also loads Claude **home** skills from `~/.claude/skills`) |
+| Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | **Repo:** `.agents/skills/<name>/SKILL.md` (same catalog as Codex). Do not also copy into `.cursor/commands/` or `$CODEX_HOME/skills` — Cursor lists every path it scans. |
 | OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`; configured on disk is not runtime-active until restart + `ark_identity` match); optional legacy `$CODEX_HOME/config.toml` fallback uses absolute roots and scoped secondaries — see [ai-gates.md](ai-gates.md) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
 | **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | **Repo:** `.grok/skills/<name>/SKILL.md`; **home:** `$GROK_HOME/skills` (default `~/.grok/skills`, `--grok-home`) |
 | Google Antigravity | `.agents/hooks.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |

package/docs/ai-gates.md

@@ -1,6 +1,7 @@
 # Gating AI Agents with ArkGate
 
-**ArkGate** (`arkgate`) is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
+This page is host install depth (hooks / MCP / CI). Not an API Gateway. Not a folder linter.
 
 This page is **develop** depth (install hooks/MCP/CI per host). Product path: [use.md](use.md) ·
 overview: [develop.md](develop.md) · hub: [README.md](README.md).
@@ -449,7 +450,7 @@ writes a scoped secondary table:
 | Add B to the legacy home fallback | `ark-check --install-agent-gates --codex-home` |
 | Make B the legacy home primary | `ark-check --install-agent-gates --codex-home --force` |
 | Doctor: primary points at another permanent project | gap id `codex-home-multi-project` (warn if no secondary yet and session host is unknown/Codex; **info + `deferred`** when the session host is known and not Codex — e.g. Grok/Claude/Cursor; info if a scoped secondary is already present) |
-| When using Codex: refresh home skills | `ark-check --install-agent-gates --skills-only --codex-home --force` |
+| When using Codex: refresh home skills | Prefer project `.agents/skills`. If Codex lists `/ark-*` twice, prune home copies: `ark-check --install-agent-gates --skills-only --prune-home-duplicates`. `--codex-home` skips when the project catalog exists. |
 
 When a valid project `.codex/config.toml` exists, it is the expected binding, but files alone
 cannot prove which already-running process answered. Doctor therefore keeps an unrelated home
@@ -488,7 +489,7 @@ Codex discovers skills as directories containing `SKILL.md` (Agent Skills standa
 | Scope | Path |
 |-------|------|
 | **Repo** (written by `--tools codex`) | `.agents/skills/<name>/SKILL.md` |
-| **Home** (optional `--codex-home`) | `$CODEX_HOME/skills/<name>/SKILL.md` |
+| **Home** (optional `--codex-home`) | `$CODEX_HOME/skills/<name>/SKILL.md` — skipped when the project catalog exists; Codex lists both otherwise |
 
 Flat `.codex/prompts/*.md` files are **not** the invocable skill catalog. Install writes the
 repo catalog above so AGENTS.md `/ark-*` references match what Codex can load. After install,

package/docs/develop.md

@@ -2,6 +2,10 @@
 
 For **developers** integrating ArkGate into a product repo: agents, CI, config, brownfield, and power tools.
 
+If the AI writes an illegal import, the write is rejected. The same check fails the pull
+request. Not an API Gateway. Not a folder linter. Without a required CI status,
+`ark.config.json` is just documentation.
+
 If you only want the happy path, start at [use.md](use.md).
 
 ---

package/docs/enthusiast/README.md

@@ -1,5 +1,8 @@
 # ArkGate — Architecture Co-pilot (enthusiast track)
 
+If the AI writes an illegal import, the write is rejected. The same check fails the pull
+request. Not an API Gateway. Not a folder linter.
+
 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`;

package/docs/enthusiast/how-to-agent-gates.md

@@ -21,7 +21,7 @@ Installs:
 | Host | Extra paths |
 |------|-------------|
 | Claude Code | `.claude/settings.json`, `.claude/skills/` |
-| Cursor | `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
+| Cursor | `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursor/rules/ark.mdc`, `.agents/skills/` |
 | Codex | `.codex/hooks.json`, `.codex/config.toml`, `.agents/skills/` |
 | **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
 

package/docs/package-surface.md

@@ -1,6 +1,7 @@
 # ArkGate package surface policy
 
-**Product wedge:** write gate · CI gate · co-pilot (plan / loop / skills).  
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
+That is the product wedge (host hook + required CI). Skills name the next step after that.
 **Not the wedge:** the optional in-process **ArkRun** kernel (`@arkgate/runtime`).
 
 **Public product site:** [arkgate.online](https://www.arkgate.online/) (promise + only flow).
@@ -213,8 +214,10 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current tree: [4.7.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.0.md);
-current published: [4.6.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.7.md);
+(current tree: [4.7.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.2.md);
+current published: [4.7.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.1.md);
+prior published: [4.7.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.7.0.md);
+prior published: [4.6.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.7.md);
 prior published: [4.6.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.6.md);
 prior published: [4.6.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.5.md);
 prior published: [4.6.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.4.md);

package/docs/product-voice.md

@@ -11,13 +11,106 @@ deliberately in the same change). Voice is product surface, not marketing decora
 
 ---
 
+## Canonical misreader (old-school engineer)
+
+First-contact copy has a **named test reader**: a senior who learned Fowler, ESLint, and CI
+quality gates — and does not live in agent hosts. If they can walk away with any of the
+three documented misreads, the line failed. Rewrite it. Do not argue the config at them.
+
+This reader is not a junior to educate and not a vibe-coder to simplify for. They are why
+“gate”, “contract”, and “architecture config” in the first sentence lose the room.
+
+### Misread A — “file structure keeper for TypeScript”
+
+**Cause:** the first sentence is folders, layers, `ark.config.json`, or “who may import whom.”
+**They hear:** eslint-plugin-boundaries, dependency-cruiser, Nx tags.
+
+The layer plane *is* import rules. That is not the product. The product is **when** those
+rules fire: the host blocks the write; required CI blocks the merge.
+
+### Misread B — “a Gateway”
+
+**Cause:** bare “gate” as the first unexplained noun; or verbs from the wrapper family:
+access, wrap, abstract, “extend without touching what it represents.”
+**They hear:** Fowler Gateway / API Gateway / facade — an intermediate object that talks
+to a resource so callers do not.
+
+A Gateway **lets traffic through and translates**. ArkGate **decides whether the write
+enters**. It is not a layer in the app. It does not wrap Stripe, a database, or HTTP.
+
+### Misread C — “not a contract, a manifesto”
+
+**Cause:** calling `ark.config.json` a **contract** (or leading with the file) before the
+deny is visible.
+**They hear:** Agile Manifesto, a principles doc, AGENTS.md — intent you hope people follow.
+
+They are right whenever the checkpoint is off. A contract in this reader’s dictionary has
+two parties and a consequence. Ours is: the host blocks the write; required CI blocks the
+merge. Without that, the file **is** a manifesto. Do not win the argument by repeating
+“it is a contract.” Show the teeth. Human copy already prefers **architecture config**
+over contract; **law / constitution** only after the checkpoint is named.
+
+Advisory-only adoption (`stance: "advisory-only"`, or no required merge status) is the
+honest manifesto case. Say so. Do not dress it as a binding contract.
+
+### First-contact order (required)
+
+On README, `docs/use.md`, develop, enthusiast, the docs hub, and the product site, use
+**common software English**. Do not invent a synonym and then explain it.
+
+**Locked sentences:**
+
+1. **Deny:** `If the AI writes an illegal import, the write is rejected. The same check fails the pull request.`
+2. **Not-that (one line):** `Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules file is just documentation.`
+3. **How:** `One rules file. One check. One next step.`
+
+The 4.6.2 line `One architecture config. One check. One coach.` is **historical**. Do not
+lead with it. First-run CLI help stays under the AL04 noun budget.
+
+ADR 0001 keeps the product title **ArkGate — Architecture Co-pilot for AI TypeScript**.
+That identity line is not a substitute for the deny.
+
+---
+
+## Common language (allowlist)
+
+First-contact copy (README hero, use/develop/hub openings, site home / start / how-it-works
+heroes, npm description, `llms.txt` lede) may use **only** these kinds of words:
+
+| Say | Do not say on first contact |
+|-----|-----------------------------|
+| illegal import / import rules / who may import whom | architecture config, contract, constitution, law |
+| the write is rejected / the hook rejects the write | write checkpoint, write gate, write firewall, pre-write block |
+| required CI check / fails the pull request / required GitHub status | merge gate, extra merge teeth |
+| rules file (`ark.config.json`) | the contract, the manifesto (except the one honest “just documentation” line) |
+| `arkgate-check --doctor` — shows what's wrong and what to do first | doctor is the control plane, coach, co-pilot |
+| warning, not blocked | advisory write |
+| extra rules inside a layer | dual plane, intra-layer sensors |
+| optional extra (off unless you turn it on) | third extra, gated complement |
+
+**Categorical brands** (do not hide, do not replace with a synonym): **ArkGate**, **ArkRules**
+(opt-in extra rules inside a layer), **ArkRun** (opt-in; not required). Gloss once. Then the
+common word.
+
+**Command names stay command names:** `arkgate`, `arkgate-check --doctor`, `--strict-merge`.
+Do not nickname them.
+
+If a term is not on this allowlist and is not a brand or a command, **cut it** or move it
+below the fold (develop docs, JSON field names, ADRs).
+
+Where we cannot use a common word — because the thing is ours — **one sentence, no hedging:**
+“ArkRules is optional. It is extra rules inside a layer. It is off unless you turn it on.”
+
+---
+
 ## North star
 
 A track so simple a newcomer enters, so strict a senior trusts — and the AI ships faster
 because the design space is small and honest.
 
-- **Gate side:** architecture config (`ark.config.json`) + pre-write block where the host
-  supports it + required CI. Deterministic. Don’t show green if we could not verify.
+- **Checkpoint side (write checkpoint — deny / pass; not a Gateway):** architecture
+  config (`ark.config.json`) + pre-write block where the host supports it + required CI.
+  Deterministic. Don’t show green if we could not verify.
   Two planes: **import rules** (who may import whom) always; **ArkRules** (structure rules
   inside a layer) opt-in. Third extra: **ArkRun** (kernel usage + declarations) via companion
   `@arkgate/runtime` — not a durability claim.
@@ -25,7 +118,7 @@ because the design space is small and honest.
   design work; one small refactor at a time; never silent auto-reshape; never weaken the config.
 - **Five-door autonomy:** invoking `/ark-adopt`, `/ark-place`, `/ark-autopilot`, `/ark-explore`,
   or `/ark-upgrade` **is** the approval. The agent writes or maps in that turn. CLI/MCP are
-  sensor + gate. Silent reshape from the compact router (unasked) stays forbidden.
+  sensor + checkpoint. Silent reshape from the compact router (unasked) stays forbidden.
 - **Team parliament:** the architecture file is a **constitution**. A product change must not
   amend it. Stewards own loosen and baseline-grow. The ratchet is **new vs the branch you
   merge to**, not only the file on this checkout. A small PR pays `--changed --base`, not
@@ -73,7 +166,8 @@ stay stable unless a change explicitly adds an alias.
 
 | Prefer (human) | Was / JSON | Use for |
 |----------------|------------|---------|
-| **architecture config** | contract | `ark.config.json` layers, rules, include |
+| **architecture config** | contract | `ark.config.json` layers, rules, include. Never the first noun. Without the checkpoint, this reader hears **manifesto** |
+| **manifesto** (honesty only) | advisory-only / no required CI | What the file is until a write checkpoint binds it. Never the product name |
 | **import rules** / **allowed dependencies** | Layers plane / edges | Who may import whom; placement, purity, isolation |
 | **ArkRules** (opt-in; gloss: structure rules inside a layer) | ArkRules | Intra-layer sensors + domain invariant catalogs (`arkrules/*`) |
 | **ArkRun** (opt-in; gloss: kernel usage + complete declarations) | arkRun | Extra plane on the gate; companion kernel is `@arkgate/runtime`; factory `createStrictArkKernel` (per instance, no singleton). Never a score. |
@@ -82,6 +176,7 @@ stay stable unless a change explicitly adds an alias.
 | **label `[Layer]` vs `[ArkRules]`** | dual-plane residual | Never blur import-rule findings with ArkRules findings |
 | **ArkRules counts** | rulesUnderContract | Doctor/inventory counts — **never a score** |
 | **type-only import debt** | type-only placement debt | `import type` on the violations list with `failsStrict:false` |
+| **write checkpoint** | gate (as first noun) | Pass/fail boundary: pre-write block + required CI. **Not** Fowler Gateway, not a resource wrapper, not a layer in the app |
 | **pre-write block** | hard write | Host actually blocks listed edit ops (installed + trusted) |
 | **warning only (not blocked)** | advisory write | MCP/rules coach; not a hard block |
 | **import graph** | edges | Allowed imports (fix these first) |
@@ -178,6 +273,8 @@ gate  →  same binary verdict on every parity-capable adapter
 
 | Do | Example |
 |----|---------|
+| Lead first-contact with the deny, then not-that | “If the AI writes an illegal import, the write is rejected. The same check fails the pull request. Not an API Gateway. Not a folder linter.” |
+| Name manifesto only when teeth are off | “No required merge status — the architecture file is advisory (a manifesto). Next: require `arkgate-check --strict-merge`.” |
 | Name the status light + plain fact + next action | “Enforce · leftover design work. Import rules check out; design smells remain. Next: one Shape door — explore → plan B → autopilot with OK.” |
 | Rank one primary door under residual | Doctor **Primary next action** #1; **Also** only for secondary |
 | Label expert skills as escapes | “Install skill pack only when doctor or a STOP handoff names a skill.” |
@@ -203,6 +300,12 @@ gate  →  same binary verdict on every parity-capable adapter
 
 | Avoid | Why |
 |-------|-----|
+| Leading first-contact with folders, layers, or `ark.config.json` | Old-school SE hears “file structure keeper” |
+| Bare “gate” as the first unexplained noun on README / use / hub / first-run | They load Fowler Gateway / API Gateway / facade |
+| Calling ArkGate a Gateway, facade, adapter, or “abstraction layer” | A Gateway wraps a resource; this checkpoint denies the write |
+| “Access resources”, “extend without touching what it represents” | Wrapper-family verbs. The architecture file is law, not a port |
+| Calling `ark.config.json` a **contract** as the first noun | Old-school SE hears manifesto — intent with no consequence |
+| “Our architecture manifesto” as product copy | Insult when teeth exist; a lie when they do not. Honesty case = advisory-only |
 | vibes, “crush it,” emoji rain | Cheap; seniors dismiss it |
 | “eh amigo,” fake familiarity | Condescension |
 | “you don’t need to understand anything” | Lies about the product |
@@ -253,7 +356,10 @@ Skills table in docs = **escapes / expert**, not a second onboarding track.
 
 ## Hero phrases (approved)
 
-- One architecture config. One check. One coach.
+- If the AI writes an illegal import, the write is rejected. The same check fails the pull request.
+- Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules file is just documentation.
+- One rules file. One check. One next step.
+- One architecture config. One check. One coach. *(historical 4.6.2 — never the first sentence)*
 - Green must mean something real.
 - You arrive at Enforce; you never turn it on.
 - Enforce does not mean the design is elegant — only that checked imports are honest.
@@ -273,6 +379,10 @@ Skills table in docs = **escapes / expert**, not a second onboarding track.
 - Ship it 🚀 / crush the spaghetti with vibes.
 - The AI validated your architecture / model pass/fail.
 - Follow AGENTS.md to pass the architecture gate.
+- Keep your file structure / folders clean.
+- An abstraction layer over your architecture.
+- A Gateway for your architecture / resources.
+- Our architecture manifesto / the contract file.
 
 ---
 
@@ -370,3 +480,6 @@ while leftover design work remains; batch every Shape bet in one turn.
 - [ ] Codes, sensors, and capabilities stay inside the guardrail catalog.
 - [ ] Projection / AGENTS.md never claimed as enforcement.
 - [ ] Seniors would not be embarrassed to paste the line into a PR.
+- [ ] First-contact sentence would not read as Fowler Gateway, a folder linter, or a manifesto of intent.
+- [ ] Bare “gate” is glossed as write checkpoint / pre-write block / required CI on first use.
+- [ ] “Contract” never appears as the first noun; without required CI, the file is named a manifesto.

package/docs/use.md

@@ -2,7 +2,12 @@
 
 For **anyone** shipping TypeScript with an AI coding agent. You do not need to study clean architecture first.
 
-**One architecture config. One check. One coach.**
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules
+file is just documentation.
+
+**One rules file. One check. One next step.**
 
 ---
 
@@ -11,12 +16,12 @@ For **anyone** shipping TypeScript with an AI coding agent. You do not need to s
 ```bash
 npm install -D arkgate typescript
 npx arkgate start                 # preview what will change
-npx arkgate start --apply         # install compact contract + host router + CI plan
-npx arkgate-check --doctor        # where am I? one status light, one next action
-npx arkgate-check --doctor --all  # encyclopedia (Details)
+npx arkgate start --apply         # install compact config + host router + CI plan
+npx arkgate-check --doctor        # what's wrong, what to do first
+npx arkgate-check --doctor --all  # full details
 ```
 
-Then keep working with your agent. The doctor is the **control plane**: when stuck, run doctor and do action **#1**. Compact first; `--all` for Details.
+Then keep working with your agent. Stuck? Run `--doctor` and do action **#1**. Compact first; `--all` for details.
 
 | Stuck on… | Do this |
 |-----------|---------|
@@ -36,7 +41,8 @@ Skip ArkGate (or treat it as overkill) when:
 - The project has **no AI coding agents** and **no multi-layer integration boundaries** worth pinning.
 - It is a **single-developer hobby CRUD** with no pressure to keep layers honest over time.
 - The team will **not** maintain `ark.config.json` layers or make `arkgate-check --strict-merge` a
-  **required** GitHub status context — without that, local advisory write stays avoidable.
+  **required** GitHub status context — without that, the rules file is just documentation and a
+  warning at write time can be ignored.
 
 In those cases a boundary linter or editor rules may be enough; see [README — Why not only ESLint / Nx / cruiser?](../README.md#why-not-only-eslint--nx--cruiser). When you *do* adopt, day-to-day honesty is still: advisory write on soft hosts → required merge status. Surface that with `npx arkgate-check --doctor` or `npx arkgate status --json` ([agent guide — Write-path honesty](agent-guide.md#write-path-honesty)).
 
@@ -46,7 +52,7 @@ In those cases a boundary linter or editor rules may be enough; see [README —
 
 | When | What happens |
 |------|----------------|
-| While the AI writes | Host write gate or advisory MCP (depends on host) |
+| While the AI writes | The write is rejected, or you get a warning (depends on the host) |
 | Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`). Until that status is required — or you write `.ark/adoption-stance.json` with `stance: "advisory-only"` — doctor will not call the tree adopted. |
 | Anytime | Doctor: Suggest / Adapt / Enforce (+ leftover design work if the design is still messy) |
 
@@ -57,7 +63,8 @@ shell/direct writes, and incomplete patches still rely on CI. **OpenCode:** loca
 advisory (warning only, not blocked). An unverified host hook is environment evidence, not
 unfinished architecture; **Not finished** is reserved for real project/config debt.
 
-ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + a coach for AI TypeScript.
+ArkGate is **not** an API Gateway, a folder linter, a web framework, ORM, or app runtime.
+The rules file only binds when the write is rejected and CI is required.
 
 ### Planes (you choose)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "arkgate",
-  "version": "4.7.0",
-  "description": "One architecture config. One check. One coach.",
+  "version": "4.7.2",
+  "description": "If the AI writes an illegal import, the write is rejected. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "When your agent writes TypeScript, ArkGate stops it from breaking the layers.",
+  "description": "If the AI writes an illegal import, the write is rejected. The same check fails the pull request.",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.7.0",
+  "version": "4.7.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.7.0",
+      "version": "4.7.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -31,7 +31,7 @@
           "type": "named",
           "name": "--config",
           "value": "ark.config.json",
-          "description": "Path to the ArkGate architecture config"
+          "description": "Path to the rules file (ark.config.json)"
         }
       ]
     }

package/templates/agent-skills/README.md

@@ -7,7 +7,7 @@
 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.**
 
-Package version when last generated context: **arkgate@4.7.0**
+Package version when last generated context: **arkgate@4.7.2**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -1,11 +1,11 @@
 ---
 name: ark-adopt
-description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield honesty. Write ark.config, optional advisory ArkRules, baseline, and gates in this turn. CLI validates.
+description: Session 0 — write the rules file (ark.config.json) to match the real folders. Optional extra rules inside a layer. CLI validates.
 ---
 
 # /ark-adopt — Mark the path (session 0)
 
-**When:** empty tree, or the architecture config does not match the real folders (session 0).
+**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`).
 
 ## Steps

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

@@ -1,6 +1,6 @@
 ---
 name: ark-architect
-description: Shortcut to /ark-adopt for greenfield shape. Deprecated as a first-class door. Do adopt’s job.
+description: Shortcut to /ark-adopt for a new tree. Deprecated as a first-class door.
 ---
 
 # /ark-architect — Shortcut to /ark-adopt

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

@@ -1,6 +1,6 @@
 ---
 name: ark-autopilot
-description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (shape); write mechanical-safe and judgment in this turn; one Shape refactor. Empty plan A is not healthy if leftover design remains. CLI is a sensor; you edit files.
+description: Fix illegal imports and one leftover-design refactor. CLI is a sensor; you edit files.
 ---
 
 # /ark-autopilot — Apply the path
@@ -14,7 +14,7 @@ description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (sh
 2. Fix import-rule debt; if leftover design remains, apply **one** small refactor.
 3. Re-run doctor. Never weaken `ark.config.json`.
 
-**This is the apply door.** Invoking it **is** the approval. Doctor remains the control plane.
+**This is the apply door.** Invoking it **is** the approval. Run `arkgate-check --doctor` for the next step.
 
 ## Autonomy contract
 

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

@@ -1,6 +1,6 @@
 ---
 name: ark-contract
-description: Shortcut to /ark-adopt (session 0) or /ark-autopilot (later config tighten). Deprecated as a first-class door.
+description: Shortcut — edit the rules file or extra rules. Use /ark-adopt or /ark-autopilot.
 ---
 
 # /ark-contract — Shortcut to adopt / autopilot
@@ -17,8 +17,9 @@ preview-only. Never weaken the architecture config.
 
 | Use this leftover name when… | Prefer instead |
 |------------------------------|----------------|
-| Layers / include / ArkRules need an edit | **`/ark-adopt`** (path) or **`/ark-autopilot`** (tighten) |
+| Layers / include / ArkRules / **ArkRun extra** need an edit | **`/ark-adopt`** (path, first `arkRun`) or **`/ark-autopilot`** (tighten) |
 | False-green / concentrated edge | **`/ark-adopt`** — write the honest config |
+| Companion install / one kernel candidate | **`/ark-runtime`** — this leftover name does not wire `@arkgate/runtime` |
 
 ## Dual engine (mandatory)
 
@@ -40,7 +41,7 @@ restart/retargeting is required. `ark://manifest` never satisfies this preflight
 
 ## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
 
-Label findings **`[Layer]`** vs **`[ArkRules]`**. Absence of `arkRules` is valid.
+Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`**. Absence of `arkRules` or `arkRun` is valid. First-time extra is **`/ark-adopt`** (advisory). Wire one candidate with **`/ark-runtime`**. New kernel-managed file with **`/ark-place`**. Do not invent `/ark-run`.
 
 ## Subagent fan-out (optional, host-dependent)
 
@@ -54,9 +55,9 @@ If the host supports **parallel subagents**, fan out read-only scouts; otherwise
 
 ## Steps
 
-1. If the path is missing or lying → execute **`/ark-adopt`**.
-2. If the path is honest and you are tightening rules → execute **`/ark-autopilot`**.
-3. `ark-check --strict-config`.
+1. If the path is missing or lying → execute **`/ark-adopt`** (including first advisory `arkRun`).
+2. If the path is honest and you are tightening rules or the ArkRun extra → execute **`/ark-autopilot`**.
+3. Companion / one candidate → **`/ark-runtime`**. `ark-check --strict-config`.
 
 ## Completion contract (skill incomplete if missing)
 
@@ -66,7 +67,7 @@ Skill incomplete if missing any field below.
 - **Sensor:** commands/tools run
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
-- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** vs **[ArkRun]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-adopt` / `/ark-autopilot` / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`

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

@@ -1,6 +1,6 @@
 ---
 name: ark-coverage
-description: Ark adoption fitness audit — governed%, gates, baseline honesty, capability gaps. CLI is a sensor; read enough source to prove gaps. Full product recon and pattern dual-plan belong to /ark-explore.
+description: How much of the tree the rules file covers. CLI is a sensor; read the source.
 ---
 
 # /ark-coverage — Ark adoption fitness (not full recon)

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

@@ -1,6 +1,6 @@
 ---
 name: ark-explain
-description: Explain this project's architecture in plain language and generate the showcase HTML report — layers, rules, coverage, gates, and why the contract exists.
+description: Explain the rules file in plain language and generate the HTML report.
 ---
 
 # /ark-explain — Understand this project's architecture

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

@@ -1,6 +1,6 @@
 ---
 name: ark-explore
-description: Map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when leftover design work remains. CLI is a sensor; you read the tree. No gate bypass.
+description: Map import rules and leftover design. No apply. CLI is a sensor; you read the tree.
 ---
 
 # /ark-explore — Recon the real project (map only)

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

@@ -1,6 +1,6 @@
 ---
 name: ark-fix
-description: Shortcut to /ark-autopilot for a small violation cluster. Deprecated as a first-class door.
+description: Shortcut to /ark-autopilot for a small illegal-import cluster.
 ---
 
 # /ark-fix — Shortcut to /ark-autopilot

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

@@ -1,6 +1,6 @@
 ---
 name: ark-loop
-description: Shortcut to /ark-autopilot for driving plan A to zero. Deprecated as a first-class door. CLI validates — you edit code.
+description: Shortcut to /ark-autopilot for illegal-import fixes. CLI validates — you edit code.
 ---
 
 # /ark-loop — Shortcut to /ark-autopilot

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

@@ -1,6 +1,6 @@
 ---
 name: ark-place
-description: "Where does new code go? Names the layer, directory, and naming for a new artifact from the contract, and writes it there. Autonomous."
+description: "Where does new code go? Names the folder from the rules file and writes the file there."
 ---
 
 # /ark-place — Where does this code go?

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

@@ -1,6 +1,6 @@
 ---
 name: ark-runtime
-description: Evaluate and wire the experimental ArkRun companion (@arkgate/runtime) against hand-rolled event bus, outbox, saga, projection, policy, or NestJS code. One candidate. Extra on via /ark-adopt; new files via /ark-place. Skills never enforce.
+description: Wire the optional ArkRun extra (@arkgate/runtime). One candidate. Extra on via /ark-adopt.
 ---
 
 # /ark-runtime — Evaluate and wire ArkRun (experimental opt-in)

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

@@ -1,6 +1,6 @@
 ---
 name: ark-think
-description: Host-side architectural reasoning — 2–3 enforceable options on layer and/or ArkRules planes for ONE decision. Not full recon (use /ark-explore). No gate bypass. No package LLM call.
+description: 2–3 options for one import-rule or ArkRules decision. Not a full map (use /ark-explore).
 ---
 
 # /ark-think — Architectural reasoning (host LLM only)