arkgate 3.8.3 → 3.9.0

package/docs/agent-guide.md

@@ -1,8 +1,13 @@
 # ArkGate — Agent Integration Guide
 
-**ArkGate** (`arkgate`) — architecture co-pilot for AI TypeScript. This guide describes how AI
-agents and codegen tools safely interact with write hooks, advisory MCP tools, CI, and `/ark-*`
-skills. Guarantees differ by host; start with the
+**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.
+
+- Product path (anyone): [use.md](use.md)  
+- Integration overview: [develop.md](develop.md)  
+- Docs hub: [README.md](README.md)  
+
+Guarantees differ by host; start with the
 [canonical host support matrix](../README.md#host-enforcement-support). The advisory-local /
 hard-CI split is a deliberate trade-off, not a gap: local hooks and MCP coach at write time,
 while a required merge status is the one boundary a repository can make every write path share.
@@ -10,8 +15,30 @@ while a required merge status is the one boundary a repository can make every wr
 CLI names: prefer **`arkgate` / `arkgate-check` / `arkgate-mcp`**; aliases `ark` / `ark-check` /
 `ark-mcp` still work for one major. **arkgate@3.8.0+** tests packed project TypeScript
 **5.9.3 / 6.0.3 / 7.0.2** and uses an exact, physically distinct TypeScript 6 analysis host when
-the project API is unusable. Published 3.7.0 predates that correction; see the distribution and
-completeness boundary in [typescript-support.md](typescript-support.md).
+the project API is unusable. See the distribution and completeness boundary in
+[typescript-support.md](typescript-support.md). Product English and progressive-disclosure rules:
+[product-voice.md](product-voice.md).
+
+### Default path (3.9.0)
+
+```text
+ark start → ark start --apply → ark-check --doctor
+  day to day: compact router / MCP place + validate + check
+  guided work: install skill pack → /ark-autopilot
+```
+
+Doctor is the **control plane** (status light + primary next action). The compact router from
+`ark start` is enough for normal feature work. Full `/ark-*` skills are **expert depth**:
+
+```bash
+npx ark-check --install-agent-gates --skills-only --force
+```
+
+**Write-path honesty:** Claude/Grok/Antigravity can hard-block listed PreToolUse ops when
+installed and trusted. Cursor/Codex/OpenCode remain **advisory at write**. For every host, the
+repository-wide hard boundary is a **required** CI status (`arkgate-check --strict-merge`) —
+never claim Cursor/Codex/OpenCode hard write. See [ai-gates.md](ai-gates.md) and the README host
+matrix.
 
 ## Architecture playbook and `ark-check --recommend`
 
@@ -72,8 +99,8 @@ npx ark-check --watch                           # debounced re-check when govern
 ```
 
 **Day-zero origin (2.12+):** `ark init` freezes `.ark/reports/origin.*` before writing agent
-docs or CI templates. Compact `ark start` previews first and keeps the applied setup under five
-project files and 25 KB;
+docs or CI templates. Compact `ark start` previews first and keeps the applied setup small
+(budget: 8 files / 32 KB including project `.mcp.json`);
 run `ark-check --report ark-report.html` explicitly when you want to establish an origin/evolution
 baseline. Do not `--reset-origin` unless the user explicitly wants a new baseline.
 `ark-check --report --no-archive` still creates `origin.*` on the first report (or on an explicit
@@ -89,12 +116,13 @@ To remove a compact host integration, preview `ark start --remove-host <host>` a
 only after review. Ark removes only its exact compact artifacts, leaves customized files untouched
 as unresolved decisions, and restores the integration with `ark start --tools <host> --apply`.
 
-**Skill roles (avoid overlap):** `/ark-explore` = map + dual-plan **seed** + Shape residual
-(no apply). `/ark-coverage` = Ark **fitness** only (governed/gates). `/ark-think` = one decision
-(2–3 options). `/ark-adopt` = brownfield Align/Stabilize + seed Shape B. `/ark-autopilot` =
-explore then apply A + propose/apply-with-ok B. `/ark-loop` = plan A only. Empty plan A is not
+**Skill roles (expert depth — avoid overlap):** `/ark-autopilot` = **guided end-to-end** default
+when skills are installed (explore → apply A + propose/apply-with-ok B). `/ark-explore` = map +
+dual-plan **seed** + Shape residual (no apply); primary post-green map half. `/ark-coverage` = Ark
+**fitness** only (governed/gates). `/ark-think` = one decision (2–3 options). `/ark-adopt` =
+brownfield Align/Stabilize + seed Shape B. `/ark-loop` = plan A only. Empty plan A is not
 “architecture healthy” if design-weak residual remains. Full routing table: full-install
-`AGENTS.md` / [README skill table](../README.md#other-skills-only-when-you-need-them).
+`AGENTS.md` / [README expert skills](../README.md#expert-skills-escapes--not-onboarding).
 
 **Design fitness (3.0.1+ / Phase Q 3.0.3):** after edges are clean, doctor can still report **ENFORCE · design-weak**.
 
@@ -335,12 +363,16 @@ 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.
+
+Greenfield / empty-tree **depth** (only when doctor or a thin tree points here — not a second day-zero curriculum):
+
 1. Run `ark-check --recommend --json` or MCP `ark_recommend`.
 2. Read `archetype`, `preset`, and `adoptInOrder.phase1` — scaffold only those directories first.
-3. Run `ark init --archetype <id> --yes`, `--apply-policy-pack enthusiast-<preset>`, or `ark init --preset <preset> --yes` when no `ark.config.json` exists.
+3. Run `ark init --archetype <id> --yes`, `--apply-policy-pack enthusiast-<preset>`, or `ark init --preset <preset> --yes` when no `ark.config.json` exists (or let `ark start --apply` install the compact contract).
 4. Optional: `--write-plan` for `ark-adoption-plan.json`; copy a gallery starter from `examples/README.md`.
 5. Use `/ark-place` or `ark_place` for individual files after the contract exists.
-6. Verify with `ark-check --root . --config ark.config.json --strict`.
+6. Re-check with `ark-check --doctor`, then `ark-check --root . --config ark.config.json --strict`.
 
 ### Golden pattern for new code (Q03)
 
@@ -403,10 +435,14 @@ directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`
 
 ## Supported agent hosts
 
-Wire write-gate + MCP + the full `/ark-*` skill set with:
+**Day zero** is the compact path from `ark start` / `ark start --apply` (router + write path + CI plan) — not the full skill pack.
+
+Wire write-gate + MCP for the active host; add the full `/ark-*` skill pack only as **expert depth** (`--skills-only` or full install when you want guided autopilot):
 
 ```bash
-npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity,opencode
+# expert pack on an existing compact install:
+# npx ark-check --install-agent-gates --skills-only --force
 # alias: npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
 ```
 
@@ -416,6 +452,8 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 | Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` |
 | OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`); 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` | `.grok/skills/<name>/SKILL.md` |
+| Google Antigravity | `.agents/hooks.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |
+| OpenCode | `opencode.json` MCP (`type: local`; advisory) | `.opencode/skills/<name>/SKILL.md` |
 
 This is a path reference, not a guarantee table. Full copy-paste setups:
 [ai-gates.md](ai-gates.md). Skill inventory: main
@@ -866,7 +904,11 @@ Register the server itself in `.mcp.json` so the agent can read `ark://manifest`
 On Claude/Grok, the installed PreToolUse hook makes matched writes an enforced checkpoint. MCP
 registration by itself remains advisory on every host because the agent must call the tool.
 
-## Recommended Agent Workflow
+## Experimental runtime kernel workflow (not the default path)
+
+This section is for adopters who **opt into** the experimental `@arkgate/runtime` / kernel surfaces.
+It is **not** the Beautiful Path day-zero curriculum. Default remains: `ark start` → doctor → compact
+router (and `/ark-autopilot` only after the skill pack).
 
 1. **Read** manifest via `ark.manifest().toJSON()`
 2. **Generate** code using registered intents, profiles, metadata, projections, and workflow definitions

package/docs/ai-gates.md

@@ -1,13 +1,30 @@
 # Gating AI Agents with ArkGate
 
 **ArkGate** (`arkgate`) is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
-On Claude Code and Grok Build, an installed and trusted PreToolUse hook can block matched writes
-before they land on disk. Cursor and OpenAI Codex use advisory MCP validation at write time; CI is
-their hard repository check. Codex 0.123+ dispatches hooks for its native `apply_patch` handler,
-but Code Mode hosts can execute deferred nested writes without that project hook event. See the
-[canonical host support matrix](../README.md#host-enforcement-support) before installing. The
+
+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).
+
+### Host write honesty (fail-closed)
+
+| Host | Write-time boundary | Hard merge boundary |
+|------|---------------------|---------------------|
+| **Claude Code** | Hard PreToolUse for listed ops when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
+| **Grok Build** | Hard PreToolUse for listed ops when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
+| **Google Antigravity** | Hard PreToolUse for listed write tools when installed + trusted + (for `hard:true`) runtime-observed | Required `arkgate-check --strict-merge` status |
+| **Cursor** | **Advisory only** (MCP/rules) — no hard PreToolUse | Required CI status (same check) |
+| **OpenAI Codex** | **Advisory / best-effort** (MCP + optional hooks.json) — **not** equivalent to Claude/Grok hard block | Required CI status (same check) |
+| **OpenCode** | **Advisory / best-effort** (MCP + optional experimental plugin) — **not** a hard boundary | Required CI status (same check) |
+
+On Claude Code, Grok Build, and Google Antigravity, an installed and trusted PreToolUse hook can
+block matched writes before they land on disk. Cursor, OpenAI Codex, and OpenCode use advisory MCP
+validation at write time; CI is their hard repository check. Codex 0.123+ dispatches hooks for its
+native `apply_patch` handler, but Code Mode hosts can execute deferred nested writes without that
+project hook event. OpenCode `tool.execute.before` plugins have known subagent bypass holes. See
+the [canonical host support matrix](../README.md#host-enforcement-support) before installing. The
 advisory-local / hard-CI split is a deliberate trade-off: local surfaces optimize feedback speed,
 while a required merge status is the one boundary a repository can make every write path share.
+Prefer fail-closed honesty over fake hard guarantees on advisory hosts.
 
 Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
 contract shared by every surface. Generate it once:
@@ -37,7 +54,8 @@ npx arkgate-check --install-agent-gates
 
 The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,
 GitHub Actions, `AGENTS.md`, Codex `.codex/hooks.json` plus a TOML snippet under `docs/`, and (when
-selected) Grok Build project files under `.grok/`. It skips existing files unless
+selected) Grok Build project files under `.grok/`, Antigravity `.agents/hooks.json`, and OpenCode
+`opencode.json` MCP registration. It skips existing files unless
 you pass `--force`, so review and commit only the templates that match your project.
 
 **Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
@@ -338,9 +356,10 @@ When a valid project `.codex/config.toml` exists, doctor treats it as the effect
 does not report an unrelated home primary. Without a project binding, doctor surfaces the
 legacy multi-project state. **Deferred (fix when using Codex):**
 non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/skills`) are
-severity **info**, marked `deferred: true`, and omitted from Top actions when the session
-host is known and not Codex — `/ark-upgrade` on Grok/Claude is not Incomplete because of
-them. **Temp/upgrade primary roots** stay fail-closed urgent (rewritten, not multi-project).
+severity **info**, marked `deferred: true`, and omitted from doctor **Primary next action** /
+**Also** list (formerly “Top actions”) when the session host is known and not Codex —
+`/ark-upgrade` on Grok/Claude is not Incomplete because of them. **Temp/upgrade primary roots**
+stay fail-closed urgent (rewritten, not multi-project).
 
 ### Codex skill catalog (SKILL.md, not flat prompts)
 
@@ -412,6 +431,69 @@ args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
 Then restart Grok or refresh via `/mcps`. Pair with CI `ark-check`; require that status if it
 must block merges.
 
+## Google Antigravity (`antigravity` / `agy`)
+
+Antigravity loads project hooks from **`.agents/hooks.json`** (also
+`~/.gemini/config/hooks.json` for user-global). Official PreToolUse **`decision: "deny"`** is a
+hard block for matched tools.
+
+Install:
+
+```bash
+npx ark-check --install-agent-gates --tools antigravity
+# alias:
+npx ark-check --install-agent-gates --tools agy
+```
+
+| File | Role |
+|------|------|
+| `.agents/hooks.json` | Named hook `ark-write-gate` with PreToolUse on write tools |
+| `GEMINI.md` | Instruction rule for Gemini CLI / legacy consumers sharing the tree |
+| `.agents/skills/*/SKILL.md` | Agent Skills catalog (shared path with Codex) |
+| `AGENTS.md` + `.mcp.json` + CI | Shared with other hosts |
+
+**Write tools covered:** `write_to_file`, `replace_file_content`, `multi_replace_file_content`.
+`ark-mcp --hook` accepts the Antigravity stdin shape (`toolCall.name` / `toolCall.args` with
+PascalCase fields such as `TargetFile`, `CodeContent`, `TargetContent`, `ReplacementContent`,
+`ReplacementChunks`). **Gating is stdout `decision`** (official PreToolUse contract): allow →
+`{ "decision": "allow" }` on stdout (exit 0); deny → `{ "decision": "deny", "reason": "…" }` on
+stdout (exit 2). Exit codes are secondary/plumbing for hosts that also honor them.
+
+**Honesty:** hard for listed ops when installed + trusted, and for `hard:true` only with
+runtime-observed covered PreToolUse evidence (same ladder as Claude/Grok). Alternate tools,
+`run_command` shell writes, and human edits still rely on required CI. Doctor reports installed
+evidence under host `antigravity`.
+
+**Do not** confuse with the instruction-tier `gemini` tool id (GEMINI.md only) — selecting
+`antigravity` also refreshes `GEMINI.md` for shared consumers without removing the separate
+`gemini` install path.
+
+## OpenCode
+
+OpenCode is first-class for MCP (`opencode.json` / `~/.config/opencode/opencode.json`) and supports
+plugin hooks such as `tool.execute.before`. Plugin coverage is **not** a complete write boundary
+(subagent and alternate tool paths may bypass).
+
+Install:
+
+```bash
+npx ark-check --install-agent-gates --tools opencode
+```
+
+| File | Role |
+|------|------|
+| `opencode.json` | Merges local MCP server `ark` (`type: "local"`, command argv) |
+| `.opencode/skills/*/SKILL.md` | Optional skill catalog when skills are installed |
+| `AGENTS.md` + CI | Shared with other hosts |
+
+**Write path (honest):** advisory MCP only. An optional experimental plugin template lives at
+`templates/hooks/opencode-ark-write-gate.mjs` (copy into `.opencode/plugins/` if you want
+best-effort `tool.execute.before` → `ark-mcp --hook`). Never claim hard write for OpenCode.
+Pair with required CI `--strict-merge`.
+
+Doctor detects `opencode.json` / `opencode.jsonc` MCP registration as advisory-write evidence for
+host `opencode`.
+
 ## Instruction-tier agents: Windsurf, Cline, Copilot, Kiro, Roo Code, Continue, Gemini CLI
 
 Agents without MCP or hook support still follow the contract through an always-on
@@ -444,9 +526,13 @@ If your runtime can run a shell command before file writes and pass the tool pay
 - stdin (Claude): JSON `{ "tool_name": "Write|Edit|MultiEdit", "tool_input": { "file_path": ..., ... } }`
 - stdin (Grok): JSON `{ "toolName": "write|search_replace|…", "toolInput": { "file_path": ..., ... } }` (also accepts Claude names)
 - stdin (Codex): JSON `{ "tool_name": "apply_patch", "tool_input": { "patch": "*** Begin Patch…" } }`
+- stdin (Antigravity): JSON `{ "toolCall": { "name": "write_to_file|…", "args": { "TargetFile": …, … } } }`
 - exit `0` → allow; exit `2` → block, human-readable violations on stderr
-- Grok payloads also get `{ "decision": "deny", "reason": "…" }` on stdout when blocked
-- plumbing problems (no stdin, non-source files, files outside `--root`) never block
+- Grok: `{ "decision": "deny", "reason": "…" }` on stdout when blocked
+- Antigravity: **stdout `decision` is required** — allow → `{ "decision": "allow" }`; deny →
+  `{ "decision": "deny", "reason": "…" }` (exit 2 still set on deny)
+- plumbing problems (no stdin, non-source files, files outside `--root`) never block; Antigravity
+  still emits `{ "decision": "allow" }` on those fail-open paths
 
 ## ESLint (editor feedback) — bounded parity envelope
 

package/docs/develop.md

@@ -0,0 +1,127 @@
+# Develop with ArkGate
+
+For **developers** integrating ArkGate into a product repo: agents, CI, config, brownfield, and power tools.
+
+If you only want the happy path, start at [use.md](use.md).
+
+---
+
+## Default integration
+
+```bash
+npm install -D arkgate typescript
+npx arkgate start --apply
+npx arkgate-check --doctor
+```
+
+Make the architecture check a **required** merge status (GitHub/GitLab/etc.):
+
+```yaml
+- run: npx arkgate-check --root . --config ark.config.json --strict-merge
+# or: uses: pedroknigge/arkgate@<tag-or-SHA>
+```
+
+`--strict-merge` (or compatibility `--strict`) is the repository-wide hard boundary for every agent host.
+
+---
+
+## Host write path (honesty)
+
+Local write hardness **differs by host**. CI required status is the shared hard merge gate.
+
+| Host | Local write | MCP | Merge |
+|------|-------------|-----|-------|
+| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status |
+| Codex · OpenCode | Best-effort / advisory | Advisory | Required status |
+| Cursor | Advisory only | Advisory | Required status |
+
+Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table in [README](../README.md#host-enforcement-support).
+
+```bash
+# All common hosts (examples)
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates --tools antigravity   # alias: agy
+npx arkgate-check --install-agent-gates --tools opencode
+# Full /ark-* skill pack (optional expert depth)
+npx arkgate-check --install-agent-gates --skills-only --force
+```
+
+Doctor reports what is actually installed and observed (`writePath` / enforcement state). Installed files alone do not imply `hard:true` without runtime evidence where the product requires it.
+
+---
+
+## Contract and placement
+
+| Concern | Doc / tool |
+|---------|------------|
+| Layers, rules, globs | [configuration.md](configuration.md) · `ark.config.json` |
+| Stable package API | [package-surface.md](package-surface.md) |
+| Where new code goes | MCP `ark_place` · skill `/ark-place` |
+| Preflight multi-file change | MCP `ark_prepare_change` · `ark preflight --changes …` |
+| Write snippet preflight | MCP `ark_prepare_write` |
+
+Prefer prepare/preflight before the host commits disk. Mechanical-safe patches only for proven kinds; judgment stays explicit.
+
+---
+
+## Brownfield and Shape
+
+Existing messy trees: [brownfield-adoption.md](brownfield-adoption.md).
+
+Phases in short:
+
+1. **Align** — contract matches reality (not false green)  
+2. **Stabilize** — baseline freezes real debt; ratchet only new violations  
+3. **Shape** — design residual (plan B), one pilot at a time, never silent codemod  
+
+Sensors:
+
+```bash
+npx arkgate-check --plan
+npx arkgate-check --coverage
+npx arkgate-check --doctor --json
+```
+
+Agent reference (tools, skills, dual path): [agent-guide.md](agent-guide.md).
+
+---
+
+## TypeScript boundary
+
+Project TypeScript 5 / 6 / 7: [typescript-support.md](typescript-support.md).  
+Incomplete analysis (`partial` / `unavailable`) cannot satisfy plan or strict merge.
+
+---
+
+## Common power commands
+
+```bash
+npx arkgate start --tools <host> --apply
+npx arkgate-check --doctor --json
+npx arkgate-check --plan --json
+npx arkgate-check --coverage
+npx arkgate-check --baseline
+npx arkgate preflight --changes changes.json --json
+npx arkgate upgrade --json          # managed content preview
+npx arkgate upgrade --apply
+```
+
+---
+
+## Optional experimental runtime
+
+Gates need **no** runtime kernel. `@arkgate/runtime` is experimental, separate package, not the day-zero product. See [package-surface.md](package-surface.md) and [production-hardening.md](production-hardening.md).
+
+---
+
+## Migrate from `ark-runtime-kernel`
+
+Same product, new package name: [migrate-from-ark-runtime-kernel.md](migrate-from-ark-runtime-kernel.md).
+
+---
+
+## Improve the library
+
+If you are changing ArkGate itself (not just adopting it): [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+← [All docs](README.md) · [Use path](use.md)

package/docs/enthusiast/README.md

@@ -5,6 +5,8 @@ developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-
 reference, and explanation. Package: **`arkgate`** (CLI: `arkgate` / `arkgate-check`;
 aliases `ark` / `ark-check` still work).
 
+**Start shorter?** [docs/use.md](../use.md) · **All docs:** [docs/README.md](../README.md)
+
 ## How ArkGate talks to you
 
 **Entry style** — who is driving: *newbie* (`ark start` / `/ark-autopilot`) vs *expert* (individual commands).

package/docs/package-surface.md

@@ -18,7 +18,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 |---------|----------------|-----------------|
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
-| **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Y02 extends `handler-in-persistence` to static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so absence of this advisory is not whole-tree proof above that envelope. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`** (Q02). Does **not** fail the gate by itself. |
+| **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Y02 extends `handler-in-persistence` to static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so **absence of a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`** (Q02). Does **not** fail the gate by itself. |
 | **Post-green path (Q01)** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
 | **Golden pattern (Q03)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
 | **Plan pattern B (P03+)** | `ark-check --plan --json` → `plan.patternBets[]`, `plan.goal.designWeak` | Additive. Each bet: `id`, `smellId`, `pilot`, `evidence`, `successSignal`, `killSwitch`, **`neverMechanicalSafe: true`**, `class: "judgment"`. **Never** auto-applied by loop/autoPatch; not a `remediationKind` mechanical-safe. `goal.met` remains edge honesty only. |
@@ -45,7 +45,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema `1.3` distinguishes `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
 | **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.0` is serializable and deterministic. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, and candidate tree/facts hashes. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
-| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. When/not when, explore Shape dual-plan seed, extraction cards, day-zero origin order). |
+| **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) | **Day zero** is the compact router from `ark start` / `start --apply` + doctor control plane — not the full skill pack. Skill *names* and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve (When/not when, explore Shape dual-plan seed, extraction cards). |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
 | **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 | **Package metadata** | `arkgate/package.json` | Stable resource subpath for tooling that needs the installed manifest. |
@@ -187,5 +187,5 @@ 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) (latest:
-[3.8.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.3.md)).
+[3.9.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.9.0.md)).
 Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](https://github.com/pedroknigge/arkgate/blob/main/CONTRIBUTING.md)).

package/docs/product-voice.md

@@ -0,0 +1,194 @@
+# ArkGate product voice
+
+Canonical English for public product surfaces: README, doctor/CLI human output, compact
+router, skill frontmatter, release notes, and agent-facing first-run copy.
+
+**Who this is for:** anyone writing or reviewing user-visible ArkGate text.  
+**Who this is not for:** internal ADR drafts, ROADMAP engineering notes, or pure code comments.
+
+When this document disagrees with shipped UI strings, **fix the strings** (or update this doc
+deliberately in the same change). Voice is product surface, not marketing decoration.
+
+---
+
+## 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:** machine-readable contract + write gate + CI. Deterministic. Fail-closed.
+  Green must mean something real.
+- **Co-pilot side:** where code belongs, who talks to whom, how; dual plan **A** (edges) +
+  **B** (shape); one pilot at a time; never silent judgment codemod; never weaken the contract.
+- **False done is forbidden:** Enforce ≠ elegant design. `design-weak` / residual must not
+  read as “healthy finished.”
+
+---
+
+## Sentence template
+
+Prefer three beats when a line teaches:
+
+```text
+[plain fact]. [precise term + implication]. [one next action].
+```
+
+Examples:
+
+| Bad | Good |
+|-----|------|
+| Ship it 🚀 your architecture is crushed! | Checked edges are clean. Residual design smells mean the tree is still design-weak. Next: `/ark-explore` shape-focus. |
+| You don’t need to understand anything. | Doctor reports one status light and one primary next action. Run `ark-check --doctor`. |
+| Become an architect in 60 seconds. | Install pins the contract and compact router. Full guided cleanup is `/ark-autopilot` after skills install. |
+
+---
+
+## Lexicon (prefer)
+
+| Term | Use for |
+|------|---------|
+| **contract** | `ark.config.json` layers, rules, include — the machine-readable architecture file |
+| **gate** / **write gate** | Host boundary that blocks or advises on invalid writes |
+| **edges** | Allowed import graph (plan **A** / remediation) |
+| **baseline** | Frozen known debt; does not make a wrong contract honest |
+| **remediation** | Fixing violations against the contract |
+| **pilot** | One extraction / reshape cluster at a time |
+| **shape** | Design residual after edges are clean (plan **B**) |
+| **design-weak** | Edges clean under Enforce, but design smells / pattern residual remain — not “done” |
+| **residual** | Work still open after a green edge check (usually Shape / plan **B**) |
+| **co-pilot** | Guidance that proposes order and pilots without silent codemod |
+| **fail-closed** | Incomplete analysis or unproven enforcement never looks green |
+| **honest coverage** | Governed % and empty scope that cannot false-green |
+| **mechanical-safe** | Deterministic auto-apply class only |
+| **judgment** | Human/agent design work; never silent auto-apply as mechanical-safe |
+| **doctor** | Control plane: status light + next action |
+| **compact router** | Default onboarding agent instructions (not the full skill pack) |
+| **hard write** | Non-bypassable PreToolUse block for listed ops (Claude/Grok when installed + trusted) |
+| **advisory write** | MCP/rules coach only (Cursor/Codex at write time) — not a hard block |
+| **required CI** | Merge hard boundary when the repository makes `arkgate-check` a required status |
+
+## Do (product copy)
+
+| Do | Example |
+|----|---------|
+| Name the status light + plain fact + term + next action | “Enforce · design-weak. Checked edges are honest; design smells remain. Next: one Shape door — explore → dual-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.” |
+| State host write honesty | “Cursor/Codex: advisory write. Required CI is the hard merge boundary.” |
+| Keep Suggest on start → doctor | New-here primary is finish `start`, not a competing recommend/architect curriculum |
+| Qualify edge-clean under design-weak | “None on checked edges … design residual remains. Not healthy finished.” |
+| Prefer fail-closed over fake hard | Incomplete analysis, unobserved hooks, and soft MCP never paint as hard green |
+
+## Avoid
+
+| Avoid | Why |
+|-------|-----|
+| 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 |
+| “auto-refactor your whole app” / magic codemod claims | We never silent-apply plan B |
+| “modes you pick” for Suggest/Adapt/Enforce | Those are **status lights**, not settings |
+| Skill-shopping lists as the default curriculum | Progressive disclosure: one door first |
+| “Healthy / done” while design-weak | False done |
+
+---
+
+## Progressive disclosure (product rule)
+
+1. **One primary path** — newcomer does not skill-shop among thirteen `/ark-*` skills.
+2. **Doctor is the control plane** — one status light, one next action (human-grade + technical).
+3. **Compact router / default install first** — full skill pack is **expert depth**, not onboarding UI.
+4. **Post-green shape** is a first-class single door when edges are clean but residual remains.
+5. **Day-to-day** — place + gate protect; guided organize via `/ark-autopilot` when needed.
+
+```text
+npx arkgate start → start --apply → ark-check --doctor
+                 → (optional) install skill pack → /ark-autopilot
+```
+
+Skills table in docs = **escapes / expert**, not a second onboarding track.
+
+---
+
+## Hero phrases (approved)
+
+- One contract. One gate. One co-pilot.
+- 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 edges are honest.
+- Empty plan A is not “architecture healthy” when design residual remains.
+- One pilot at a time. Pattern bets are never mechanical-safe.
+- Doctor is the control plane: status light + next action.
+
+## Hero phrases (forbidden)
+
+- Become an architect in 60 seconds.
+- You don’t need to understand architecture.
+- We auto-fix everything safely.
+- Ship it 🚀 / crush the spaghetti with vibes.
+
+---
+
+## Doctor / deny microcopy models
+
+### Status light (operating mode)
+
+Each model line follows the sentence template: **plain fact · term · next action**.
+
+| Light | Model line |
+|-------|------------|
+| **Suggest** | Thin or new tree. Contract is not yet the control plane. Next: `ark start` preview, then `--apply`; re-run doctor. |
+| **Adapt** | Contract and tree still disagree, or debt is open. Write path does not fully protect you yet. Next: doctor top action #1. |
+| **Enforce** | Honest coverage and clean checked edges. Keep host write path + required CI. |
+| **Enforce · design-weak** | Checked edges are honest; design smells remain. Green is not elegant design. Next: one Shape door — map (`/ark-explore` shape-focus) → dual-plan B → apply B only with `/ark-autopilot` and OK. |
+
+### Primary next action
+
+- Lead with the **outcome**, then the **skill or command**, then the **constraint** (never mechanical-safe / never skill-shop).
+- When design-weak, rank the single Shape path first; do not list explore / coverage / think as equal first choices.
+
+### Deny / gate failure
+
+```text
+[What failed in plain terms]. [Rule or evidence id]. Next: [one fix path — /ark-fix, prepare-write, or contract edit].
+```
+
+Never: mock the user, imply the gate is optional, or suggest disabling rules to “finish.”
+
+### Healthy finished
+
+Print “Healthy — nothing to do” **only** when there is no design-weak residual and no open top actions.
+Otherwise name the residual.
+
+---
+
+## Compact router model
+
+Keep short. Three jobs only:
+
+1. Point at **doctor** as status.
+2. Day-to-day place / validate / check.
+3. Point at **full skill pack install** as optional expert depth — not a skill catalog dump.
+
+---
+
+## Skill description model
+
+| Skill role | Frontmatter tone |
+|------------|------------------|
+| `/ark-autopilot` | Guided **end-to-end** path (explore → dual plan → apply A; B with OK) |
+| `/ark-explore` | Map / dual-plan **seed** only; primary post-green map half |
+| Others | Specialized escape; name when **not** to use them |
+
+Keep dual-engine rules and **STOP** handoffs. Never claim silent full-tree reshape.
+
+---
+
+## Checklist before shipping copy
+
+- [ ] One next action is obvious.
+- [ ] Status light is not a mode picker.
+- [ ] No false done under design-weak / incomplete analysis.
+- [ ] Technical terms present (contract, gate, edges, pilot) without slang.
+- [ ] Expert skills are labeled expert — not the default curriculum.
+- [ ] Seniors would not be embarrassed to paste the line into a PR.