arkgate 4.7.1 → 4.7.2

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.1",
-  "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.1",
+  "version": "4.7.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.7.1",
+      "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.1**
+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). Edit layers, ArkRules, or the ArkRun extra. 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

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)

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

@@ -1,6 +1,6 @@
 ---
 name: ark-upgrade
-description: Upgrade ArkGate through a content-identity preview, preserve customized files, and verify the active host and architecture contract.
+description: Upgrade ArkGate. Preview first, keep customized files, then apply.
 ---
 
 # /ark-upgrade — managed ArkGate upgrade

package/templates/skills/ark-adopt.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/skills/ark-architect.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/skills/ark-autopilot.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/skills/ark-contract.md

@@ -1,6 +1,6 @@
 ---
 name: ark-contract
-description: Shortcut to /ark-adopt (session 0) or /ark-autopilot (later config tighten). Edit layers, ArkRules, or the ArkRun extra. 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

package/templates/skills/ark-coverage.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/skills/ark-explain.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/skills/ark-explore.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/skills/ark-fix.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/skills/ark-loop.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/skills/ark-place.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/skills/ark-runtime.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/skills/ark-think.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)

package/templates/skills/ark-upgrade.md

@@ -1,6 +1,6 @@
 ---
 name: ark-upgrade
-description: Upgrade ArkGate through a content-identity preview, preserve customized files, and verify the active host and architecture contract.
+description: Upgrade ArkGate. Preview first, keep customized files, then apply.
 ---
 
 # /ark-upgrade — managed ArkGate upgrade