arkgate 4.6.1 → 4.6.2

package/docs/README.md

@@ -53,15 +53,15 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · [CHANGELOG.md](../CHANGELOG.md) |
-| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. [team-parliament](plans/team-parliament/README.md) **4.6.1 prepared**; [five-door-autonomy](plans/five-door-autonomy/README.md) **4.6.1 prepared**; [understandable-ark-4.6](plans/understandable-ark-4.6/README.md) **4.6.0**; [field-upgrade-mcp-truth](plans/field-upgrade-mcp-truth/README.md) **shipped in 4.5.6**; deep-module coach **shipped in 4.5.5**; domain fitness & session truth for **4.5.0**; improvement compass for **4.4.0**; agent contract surface for **4.3.0**). Product how-to stays in use/develop/agent-guide; plans are not required reading to use the package. |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. [team-parliament](plans/team-parliament/README.md) **shipped in 4.6.1**; [five-door-autonomy](plans/five-door-autonomy/README.md) **shipped in 4.6.1**; [understandable-ark-4.6](plans/understandable-ark-4.6/README.md) **4.6.0**; [field-upgrade-mcp-truth](plans/field-upgrade-mcp-truth/README.md) **shipped in 4.5.6**; deep-module coach **shipped in 4.5.5**; domain fitness & session truth for **4.5.0**; improvement compass for **4.4.0**; agent contract surface for **4.3.0**). Product how-to stays in use/develop/agent-guide; plans are not required reading to use the package. |
 | 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) |
 
-Prepared: [releases/4.6.1.md](releases/4.6.1.md) (`arkgate@4.6.1` — not yet npm `latest`).  
-Current published: [releases/4.6.0.md](releases/4.6.0.md) (`arkgate@4.6.0` on npm `latest`).  
-Prior: [releases/4.5.7.md](releases/4.5.7.md) (`arkgate@4.5.7`).  
-Previous: [releases/4.5.6.md](releases/4.5.6.md) · [releases/4.5.5.md](releases/4.5.5.md) · [releases/4.5.0.md](releases/4.5.0.md) · [releases/4.4.0.md](releases/4.4.0.md) · [releases/4.3.0.md](releases/4.3.0.md) · [releases/4.2.1.md](releases/4.2.1.md) · [releases/4.2.0.md](releases/4.2.0.md) · [releases/4.1.1.md](releases/4.1.1.md).  
+Prepared: [releases/4.6.2.md](releases/4.6.2.md) (`arkgate@4.6.2` — not yet npm `latest`).  
+Current published: [releases/4.6.1.md](releases/4.6.1.md) (`arkgate@4.6.1` on npm `latest`).  
+Prior: [releases/4.6.0.md](releases/4.6.0.md) (`arkgate@4.6.0`).  
+Previous: [releases/4.5.7.md](releases/4.5.7.md) · [releases/4.5.6.md](releases/4.5.6.md) · [releases/4.5.5.md](releases/4.5.5.md) · [releases/4.5.0.md](releases/4.5.0.md) · [releases/4.4.0.md](releases/4.4.0.md) · [releases/4.3.0.md](releases/4.3.0.md) · [releases/4.2.1.md](releases/4.2.1.md) · [releases/4.2.0.md](releases/4.2.0.md) · [releases/4.1.1.md](releases/4.1.1.md).  
 Previous major: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0`).  
 Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-guide.md](agent-guide.md).
 

package/docs/agent-guide.md

@@ -493,7 +493,7 @@ generating project structure on greenfield or early-adoption repos.
 coverage is low or the config is fresh:
 
 ```
-New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend
+New to Ark? /ark-adopt or: arkgate-check --doctor
 ```
 
 The `/ark-adopt` skill ships in `templates/skills/ark-adopt.md` (leftover

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

@@ -33,7 +33,7 @@ local, MCP, CI, and repair guarantees. The table above only lists installed path
 `arkgate-mcp --session-context` appends when governed coverage is low:
 
 ```
-New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend
+New to Ark? /ark-adopt or: arkgate-check --doctor
 ```
 
 ## Verify gates

package/docs/package-surface.md

@@ -210,9 +210,9 @@ 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)
-(prepared: [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md);
- current published: [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md);
- prior published: [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
+(prepared: [4.6.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.2.md);
+ current published: [4.6.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.1.md);
+ prior published: [4.6.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.6.0.md), [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md), [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
 [4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);
 previous: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md),
 [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md),

package/docs/use.md

@@ -49,9 +49,9 @@ In those cases a boundary linter or editor rules may be enough; see [README —
 | Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) |
 | Anytime | Doctor: Suggest / Adapt / Enforce (+ leftover design work if the design is still messy) |
 
-**Codex / Cursor / OpenCode:** local write stays advisory forever — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that local writes are advisory; **Not finished** is reserved for real project/contract debt.
+**Cursor:** pre-write block for Write/StrReplace when `.cursor/hooks.json` is trusted. **Codex / OpenCode:** local write stays advisory (warning only, not blocked) — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that those hosts do not hard-block writes; **Not finished** is reserved for real project/contract debt.
 
-ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + co-pilot for AI TypeScript.
+ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + a coach for AI TypeScript.
 
 ### Two planes (you choose)
 
@@ -83,7 +83,7 @@ list: [configuration.md](configuration.md).
 | **Suggest** | New or thin project | Finish `start`, re-run doctor |
 | **Adapt** | Not fully protected yet | Doctor action #1 until clean |
 | **Enforce** | Edges honest under the contract | Keep write path + CI |
-| **Enforce · design-weak** | Edges clean; design still messy | Shape door — not “done” |
+| **Enforce · leftover design work** | Edges clean; design still messy | Shape door — not “done” |
 
 **Green edges ≠ elegant design.** Empty remediation plan is not “architecture finished” if design residual remains.
 
@@ -175,7 +175,7 @@ Human doctor prints the short section above.
 | **Stabilize** | Edges under Enforce | Real debt only in baseline; write path + CI honest |
 | **Shape** | One golden pattern + pilots | Residual lenses shrink pilot by pilot — never silent multi-pilot |
 
-Green edges under **Enforce · design-weak** mean Align/Stabilize may be fine while Shape remains open.
+Green edges under **Enforce · leftover design work** mean Align/Stabilize may be fine while Shape remains open.
 Empty plan A is **not** “architecture finished.”
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "arkgate",
-  "version": "4.6.1",
-  "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
+  "version": "4.6.2",
+  "description": "One architecture config. One check. One coach.",
   "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": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "description": "When your agent writes TypeScript, ArkGate stops it from breaking the layers — and CI rejects the merge if it still does.",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.6.1",
+  "version": "4.6.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.6.1",
+      "version": "4.6.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

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

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

@@ -5,8 +5,17 @@ description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield
 
 # /ark-adopt — Mark the path (session 0)
 
+**When:** empty tree, or the architecture config 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
+
+1. Read `arkgate-check --doctor` (one light, one next action).
+2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
+3. Re-run doctor. Day-to-day new files: `/ark-place`.
+
 Invoking this skill **is** the approval. Write the architecture config in this turn.
-Greenfield: scaffold like `--recommend` / today’s architect. Brownfield: match **product
+Greenfield: scaffold like `--recommend`. Brownfield: match **product
 reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.
 
 ## Autonomy contract
@@ -36,7 +45,7 @@ write them in this turn. If they say the list is still right, leave it. Never in
 or auto-remove stewards.
 
 **Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
-spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+spaghetti leftover design work. Always end with dual-plan **B** seeds (or handoff explore)
 when design smells remain after the contract is honest.
 
 ## Improvement compass (process preflight)
@@ -152,7 +161,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
 3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
    across **≥4 dirs**).
-4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+4. **“How to fix”** — concrete layer globs, file moves, manifest/intent proposals.
 5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
 6. Never freeze a concentrated edge without investigating contract smell / false-green.
 
@@ -182,7 +191,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
      land structure/invariant entries under `arkrules/<Layer>.json` **in this turn** (ADR 0015 routing).
    - Write the config; move pure rules into Domain when safe; validate with ark-check.
-   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+   - Deliver section **How to fix the architecture config** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
 7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
@@ -197,7 +206,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
-**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+**Guard on the contract ≠ Shape done.** Say leftover design work remains when B residual remains.
 
 ## Verify
 

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

@@ -5,8 +5,8 @@ description: Shortcut to /ark-adopt for greenfield shape. Deprecated as a first-
 
 # /ark-architect — Shortcut to /ark-adopt
 
-**Deprecated as a first-class door.** Session 0 is **`/ark-adopt`**. Do that job now
-(greenfield scaffold via `ark-check --recommend` / MCP `ark_recommend` after `ark_identity`).
+**Not a first-run door.** This leftover name is a shortcut. Session 0 is **`/ark-adopt`**.
+Do that job now. Do not send the user to `/ark-contract` or `/ark-fix`.
 
 ## Autonomy contract
 

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

@@ -5,9 +5,16 @@ description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (sh
 
 # /ark-autopilot — Apply the path
 
-**This is the apply door.** Invoking it **is** the approval. Prefer it when the user wants
-architecture cleaned end-to-end, not when they only need a map (`/ark-explore`). Doctor
-remains the control plane: re-check status after each major step.
+**When:** the user wants architecture cleaned end-to-end, or leftover design after a map.
+**Not when:** map only (`/ark-explore`), session 0 / config lying (`/ark-adopt`), or one new file (`/ark-place`).
+
+## Steps
+
+1. Read `arkgate-check --doctor` (do #1).
+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.
 
 ## Autonomy contract
 
@@ -81,7 +88,7 @@ decision-grade explore pass **and** without opening violating files.
 2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
 3. **Dual plan** always emitted (sections A and B).
 4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
-5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+5. **“How to fix”** for each A cluster and each B pattern bet.
 6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
 7. **One-pilot loop for B:** when leftover design / design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
    → apply **only** that pilot **in this turn** → **re-doctor**. Never multi-pilot batch B; residual
@@ -153,7 +160,7 @@ Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot rep
 Include explore **§G** when spaghetti / design-weak signals fire.
 
 1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
-   **ENFORCE·design-weak** risk).
+   leftover design work risk).
 2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
 3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
 4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.

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

@@ -5,7 +5,7 @@ description: Shortcut to /ark-adopt (session 0) or /ark-autopilot (later config
 
 # /ark-contract — Shortcut to adopt / autopilot
 
-**Deprecated as a first-class door.** Writing `ark.config.json` / `arkrules/*` is
+**Not a first-run door.** This leftover name is a shortcut. Writing `ark.config.json` is
 **`/ark-adopt`** at session 0 and **`/ark-autopilot`** afterward. Do that job now.
 
 ## Autonomy contract

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

@@ -5,8 +5,9 @@ description: Ark adoption fitness audit — governed%, gates, baseline honesty,
 
 # /ark-coverage — Ark adoption fitness (not full recon)
 
-**Shortcut.** Fitness numbers only. Full map / leftover design → **`/ark-explore`**.
-Apply → **`/ark-autopilot`**. Session 0 → **`/ark-adopt`**. This is not `/ark-explore`.
+**Not a first-run door.** Fitness numbers only (governed files, gates, baseline).
+Session 0 → **`/ark-adopt`**. Leftover design → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
 what adoption gaps remain. Work autonomously. End with a ranked fitness report.
@@ -56,7 +57,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 2. **Product surface** — name the app/package(s) in one line (not a full recon).
 3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
    across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
-4. **“Así te lo re-soluciono”** for adoption gaps (globs, install, baseline, intents).
+4. **“How to fix”** for adoption gaps (globs, install, baseline, intents).
 5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
    list them briefly and **STOP — do not continue this skill as complete** for pattern work —
    **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.
@@ -159,7 +160,7 @@ because governed% is 100% and plan is empty.
 2. **Adoption map** — clusters you read for *fitness* (paths) — keep short.
 3. **Ranked table** (adoption residual + install/capability opportunities)
 
-| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) | Next |
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | How to fix (concrete) | Next |
 
 Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity` | `design-weak`
 
@@ -169,7 +170,7 @@ Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity`
 ## Done criteria
 
 - ≥10 source files read and cited; product surface named.
-- At least one **Así te lo re-soluciono** block with real paths or install commands.
+- At least one **How to fix** block with real paths or install commands.
 - CLI numbers used as evidence, not as the whole report.
 - Design residual either absent with evidence or explicitly handed to `/ark-explore`.
 

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

@@ -5,8 +5,9 @@ description: Explain this project's architecture in plain language and generate
 
 # /ark-explain — Understand this project's architecture
 
-**Shortcut.** Teach / HTML tour only. Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** Teach / HTML tour only. Session 0 → **`/ark-adopt`**.
+Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.
 

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

@@ -5,6 +5,15 @@ description: Map skill — decision-grade recon of layers + ArkRules opportuniti
 
 # /ark-explore — Recon the real project (map only)
 
+**When:** you need a map, or leftover design work remains after imports look green.
+**Not when:** the user wants edits applied (`/ark-autopilot`) or session 0 (`/ark-adopt`).
+
+## Steps
+
+1. Read `arkgate-check --doctor`.
+2. Open the real tree (≥12 files across ≥4 dirs). CLI JSON alone is incomplete.
+3. Rank leftover work. Hand off to `/ark-autopilot` to apply one refactor. Do not write config or product code here.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval to **map**. Open the real tree. CLI JSON alone is
@@ -308,7 +317,7 @@ Prefer bets the user can run next (`command` / skill), not vague “improve DX
 | **Stabilize** | ENFORCE + honest baseline only for real debt | 0 new edges; doctor not lying about write path/CI |
 | **Shape** | One **golden** pattern + pilot cluster | Pilot smells cleared; rest is migrate-on-touch; B bets have success signals |
 
-ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out loud. It is **not** “healthy finished.”
+ENFORCE without Shape progress is leftover design work — say that out loud. It is **not** “healthy finished.”
 
 **Agent-detected design smells** (list any that apply; paths required — these may predate doctor IDs):
 
@@ -374,16 +383,16 @@ and the ranked **`pilotLoop.nextPilot`**.
 
 State **Mode: recon | dual-plan seed | shape-focus** and **Phase: Align | Stabilize | Shape** in the first lines.
 
-1. **Headline** — product one sentence + honesty (mode, governed%, false-green / semantic false-green / **ENFORCE·design-weak** / false-promise risk). ENFORCE is context, not the story.
+1. **Headline** — product one sentence + honesty (mode, governed%, false-green / leftover design work / false-promise risk). ENFORCE is context, not the story.
 2. **Map** — entry points, major dirs, shape name (or “no honest shape yet”). One screen. **Patterns concurrent** table when §B/§G requires it.
 3. **What I opened** — paths + sensors (include field/hook/origin when used).
 4. **Ranked table** — **only rows that change a decision**. Prefer **3–6** hard rows.
 
-| # | Kind | Finding | Evidence (path) | Así te lo re-soluciono | Success signal | Next skill / command |
+| # | Kind | Finding | Evidence (path) | How to fix | Success signal | Next skill / command |
 
 Kinds: `risk` | `false-green` | `debt` | `opportunity` | `shape` | `manifiesto` | `agent-dx` | `design-weak`
 
-**Así te lo re-soluciono** must be concrete: files to touch, command to run.  
+**How to fix** must be concrete: files to touch, command to run.  
 **Success signal** must be falsifiable (see §F).
 
 5. **Field path summary**.

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

@@ -5,7 +5,7 @@ description: Shortcut to /ark-autopilot for a small violation cluster. Deprecate
 
 # /ark-fix — Shortcut to /ark-autopilot
 
-**Deprecated as a first-class door.** Gate violations and judgment remediations are
+**Not a first-run door.** This leftover name is a shortcut. Gate violations are
 **`/ark-autopilot`**. Do that job now. CLI only validates.
 
 ## Autonomy contract

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

@@ -5,7 +5,7 @@ description: Shortcut to /ark-autopilot for driving plan A to zero. Deprecated a
 
 # /ark-loop — Shortcut to /ark-autopilot
 
-**Deprecated as a first-class door.** Driving `--plan` to `goal.met` is **`/ark-autopilot`**.
+**Not a first-run door.** This leftover name is a shortcut. Driving `--plan` to `goal.met` is **`/ark-autopilot`**.
 Do that job now. Auto-apply only the four `mechanical-safe` kinds; judgment you write.
 
 ## Autonomy contract

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

@@ -5,6 +5,15 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 # /ark-place — Where does this code go?
 
+**When:** you are adding a new file or artifact and need the layer, folder, and name.
+**Not when:** session 0 / config is missing or lying (`/ark-adopt`) or an existing violation cluster (`/ark-autopilot`).
+
+## Steps
+
+1. Bind identity if using MCP (`ark_identity` with the exact project root).
+2. Place the file (`ark_place` or read `ark.config.json`).
+3. Write it there. Then `arkgate-check`.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval. If the user described an artifact, **write the
@@ -155,7 +164,7 @@ the same files or weaken the gate.
 
 - If the user needs bulk adoption / wrong config, not a single artifact: **STOP — do not continue this skill as complete.** Switch to **`/ark-adopt`** (write the path) instead of ad-hoc multi-file grinding without a plan.
 - If the config lacks a home for the artifact: add the layer **in this turn**, then write the file.
-- If doctor is **ENFORCE · design-weak** and the user is asking to reshape existing structure
+- If doctor shows leftover design work and the user is asking to reshape existing structure
   (not place one new artifact): place only the new file under the golden/contract home, then
   hand off **one** pilot via `pilotLoop.nextPilot` / `/ark-explore` shape-focus — never multi-pilot
   batch reshape from this skill.

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

@@ -5,8 +5,9 @@ description: Host-side architectural reasoning — 2–3 enforceable options on
 
 # /ark-think — Architectural reasoning (host LLM only)
 
-**Shortcut.** One decision only. Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** One decision only. Session 0 → **`/ark-adopt`**.
+Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You are the user's architecture thinking partner **inside** the project's Ark contract.
 This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)

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

@@ -5,9 +5,16 @@ description: Upgrade ArkGate through a content-identity preview, preserve custom
 
 # /ark-upgrade — managed ArkGate upgrade
 
-Upgrade the published `arkgate` package and its managed gates without treating a
-filename, package version, or similar-looking file as proof of ownership. The
-preview is the source of truth: inspect it before applying anything.
+**When:** bump the published `arkgate` package and refresh managed gates.
+**Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).
+
+## Steps
+
+1. Preview: `arkgate upgrade` (no writes).
+2. Apply in this turn: `arkgate upgrade --apply` (needs `--plan-digest` when applying managed files).
+3. Re-run `arkgate-check --doctor`. Customized files stay unless you pass `--accept-conflicts` / `--refresh-skills`.
+
+The preview is the source of truth. Do not treat a filename or package version as proof of ownership.
 
 ## Autonomy contract
 

package/templates/skills/ark-adopt.md

@@ -5,8 +5,17 @@ description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield
 
 # /ark-adopt — Mark the path (session 0)
 
+**When:** empty tree, or the architecture config 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
+
+1. Read `arkgate-check --doctor` (one light, one next action).
+2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
+3. Re-run doctor. Day-to-day new files: `/ark-place`.
+
 Invoking this skill **is** the approval. Write the architecture config in this turn.
-Greenfield: scaffold like `--recommend` / today’s architect. Brownfield: match **product
+Greenfield: scaffold like `--recommend`. Brownfield: match **product
 reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.
 
 ## Autonomy contract
@@ -36,7 +45,7 @@ write them in this turn. If they say the list is still right, leave it. Never in
 or auto-remove stewards.
 
 **Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
-spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+spaghetti leftover design work. Always end with dual-plan **B** seeds (or handoff explore)
 when design smells remain after the contract is honest.
 
 ## Improvement compass (process preflight)
@@ -152,7 +161,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
 3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
    across **≥4 dirs**).
-4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+4. **“How to fix”** — concrete layer globs, file moves, manifest/intent proposals.
 5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
 6. Never freeze a concentrated edge without investigating contract smell / false-green.
 
@@ -182,7 +191,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
      land structure/invariant entries under `arkrules/<Layer>.json` **in this turn** (ADR 0015 routing).
    - Write the config; move pure rules into Domain when safe; validate with ark-check.
-   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+   - Deliver section **How to fix the architecture config** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
 7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
@@ -197,7 +206,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
-**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+**Guard on the contract ≠ Shape done.** Say leftover design work remains when B residual remains.
 
 ## Verify
 

package/templates/skills/ark-architect.md

@@ -5,8 +5,8 @@ description: Shortcut to /ark-adopt for greenfield shape. Deprecated as a first-
 
 # /ark-architect — Shortcut to /ark-adopt
 
-**Deprecated as a first-class door.** Session 0 is **`/ark-adopt`**. Do that job now
-(greenfield scaffold via `ark-check --recommend` / MCP `ark_recommend` after `ark_identity`).
+**Not a first-run door.** This leftover name is a shortcut. Session 0 is **`/ark-adopt`**.
+Do that job now. Do not send the user to `/ark-contract` or `/ark-fix`.
 
 ## Autonomy contract
 

package/templates/skills/ark-autopilot.md

@@ -5,9 +5,16 @@ description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (sh
 
 # /ark-autopilot — Apply the path
 
-**This is the apply door.** Invoking it **is** the approval. Prefer it when the user wants
-architecture cleaned end-to-end, not when they only need a map (`/ark-explore`). Doctor
-remains the control plane: re-check status after each major step.
+**When:** the user wants architecture cleaned end-to-end, or leftover design after a map.
+**Not when:** map only (`/ark-explore`), session 0 / config lying (`/ark-adopt`), or one new file (`/ark-place`).
+
+## Steps
+
+1. Read `arkgate-check --doctor` (do #1).
+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.
 
 ## Autonomy contract
 
@@ -81,7 +88,7 @@ decision-grade explore pass **and** without opening violating files.
 2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
 3. **Dual plan** always emitted (sections A and B).
 4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
-5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+5. **“How to fix”** for each A cluster and each B pattern bet.
 6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
 7. **One-pilot loop for B:** when leftover design / design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
    → apply **only** that pilot **in this turn** → **re-doctor**. Never multi-pilot batch B; residual
@@ -153,7 +160,7 @@ Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot rep
 Include explore **§G** when spaghetti / design-weak signals fire.
 
 1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
-   **ENFORCE·design-weak** risk).
+   leftover design work risk).
 2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
 3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
 4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.

package/templates/skills/ark-contract.md

@@ -5,7 +5,7 @@ description: Shortcut to /ark-adopt (session 0) or /ark-autopilot (later config
 
 # /ark-contract — Shortcut to adopt / autopilot
 
-**Deprecated as a first-class door.** Writing `ark.config.json` / `arkrules/*` is
+**Not a first-run door.** This leftover name is a shortcut. Writing `ark.config.json` is
 **`/ark-adopt`** at session 0 and **`/ark-autopilot`** afterward. Do that job now.
 
 ## Autonomy contract

package/templates/skills/ark-coverage.md

@@ -5,8 +5,9 @@ description: Ark adoption fitness audit — governed%, gates, baseline honesty,
 
 # /ark-coverage — Ark adoption fitness (not full recon)
 
-**Shortcut.** Fitness numbers only. Full map / leftover design → **`/ark-explore`**.
-Apply → **`/ark-autopilot`**. Session 0 → **`/ark-adopt`**. This is not `/ark-explore`.
+**Not a first-run door.** Fitness numbers only (governed files, gates, baseline).
+Session 0 → **`/ark-adopt`**. Leftover design → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
 what adoption gaps remain. Work autonomously. End with a ranked fitness report.
@@ -56,7 +57,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 2. **Product surface** — name the app/package(s) in one line (not a full recon).
 3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
    across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
-4. **“Así te lo re-soluciono”** for adoption gaps (globs, install, baseline, intents).
+4. **“How to fix”** for adoption gaps (globs, install, baseline, intents).
 5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
    list them briefly and **STOP — do not continue this skill as complete** for pattern work —
    **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.
@@ -159,7 +160,7 @@ because governed% is 100% and plan is empty.
 2. **Adoption map** — clusters you read for *fitness* (paths) — keep short.
 3. **Ranked table** (adoption residual + install/capability opportunities)
 
-| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) | Next |
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | How to fix (concrete) | Next |
 
 Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity` | `design-weak`
 
@@ -169,7 +170,7 @@ Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity`
 ## Done criteria
 
 - ≥10 source files read and cited; product surface named.
-- At least one **Así te lo re-soluciono** block with real paths or install commands.
+- At least one **How to fix** block with real paths or install commands.
 - CLI numbers used as evidence, not as the whole report.
 - Design residual either absent with evidence or explicitly handed to `/ark-explore`.
 

package/templates/skills/ark-explain.md

@@ -5,8 +5,9 @@ description: Explain this project's architecture in plain language and generate
 
 # /ark-explain — Understand this project's architecture
 
-**Shortcut.** Teach / HTML tour only. Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** Teach / HTML tour only. Session 0 → **`/ark-adopt`**.
+Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.