arkgate 2.12.0 → 3.0.0

package/docs/agent-guide.md

@@ -1,7 +1,9 @@
 # ArkGate — Agent Integration Guide
 
 **ArkGate** (`arkgate`) — architecture co-pilot for AI TypeScript. This guide describes how AI
-agents and codegen tools safely interact with the write gate, MCP tools, and `/ark-*` skills.
+agents and codegen tools safely interact with write hooks, advisory MCP tools, CI, and `/ark-*`
+skills. Guarantees differ by host; start with the
+[canonical host support matrix](../README.md#host-enforcement-support).
 
 CLI names: prefer **`arkgate` / `arkgate-check` / `arkgate-mcp`**; aliases `ark` / `ark-check` /
 `ark-mcp` still work for one major. TypeScript **5.x / 6.x / 7.x** as the project compiler:
@@ -23,10 +25,13 @@ Each of the twelve archetypes (`crud-product`, `api-backend`, `frontend-surface`
 - plain-language analogy and anti-patterns,
 - optional book references for depth only.
 
-Scoring is **deterministic**: repo shape signals (workspaces, UI dirs, API surface,
-persistence, jobs, workflows, CLI `bin`, source-file count, …) are matched against the
-playbook. Framework packages may appear as secondary `toolHints` in JSON output — never as
-the primary archetype id.
+Scoring is **deterministic** and source/graph-first. Ark discovers package units and roots from
+workspace manifests, `tsconfig`/`jsconfig` references, package exports and entrypoints, plus
+conventional `src`/`source` directories. Runtime and peer dependencies contribute framework
+signals; dev-only dependencies are reported but do not determine the application shape. Docs,
+examples, and test packages are reported separately and excluded from root-product inference.
+Framework packages may appear as secondary `toolHints` in JSON output — never as the primary
+archetype id.
 
 All playbook labels, analogies, anti-patterns, and `--recommend` prose are **English**
 (`locale: "en"` in the playbook). Agents should present them as-is unless a future locale
@@ -41,7 +46,10 @@ npx ark-check --recommend --json
 
 `--recommend` does not require `ark.config.json`. It exits `0` and prints a progressive
 adoption plan: archetype id, preset, `confidence`, `runnerUp`, `why` (shape signals),
+structured positive/negative `evidence`, discovered `signals.packageUnits`,
 `adoptInOrder.phase1`, `firstCommand` (`ark init --archetype …`), and `checkCommand`.
+When the top two shapes are close or projected governed coverage is below 90%, JSON sets
+`requiresConfirmation: true` and explains why in `confirmationReasons`.
 
 Human output highlights phase-1 layers and the analogy; JSON is the stable contract for
 MCP `ark_recommend` and the `/ark-architect` skill.
@@ -49,7 +57,7 @@ MCP `ark_recommend` and the `/ark-architect` skill.
 ### Terminal onboarding (Phase B)
 
 ```bash
-npx ark start --yes                             # preferred: shape → contract → **day-zero origin** → gates → plan
+npx ark start --yes                             # preferred: shape → compact contract → active host → CI → plan
 npx ark init --archetype crud-product --yes   # non-interactive: shape → preset → origin → gates
 npx ark init                                    # TTY wizard: pick application shape (1–8), not a framework
 npx ark-check --doctor                          # includes "New here?" when coverage is low or config is fresh
@@ -57,14 +65,20 @@ npx ark-check --report beginner.html --beginner # simplified HTML for enthusiast
 npx ark-check --watch                           # debounced re-check when governed files change
 ```
 
-**Day-zero origin (2.12+):** as soon as `ark.config.json` exists, `ark start` / `ark init`
-freeze `.ark/reports/origin.*` **before** writing agent docs, skills, or CI templates.
-Later `--report` shows evolution vs that snapshot. Do not `--reset-origin` unless the user
-explicitly wants a new baseline.
+**Day-zero origin (2.12+):** `ark init` freezes `.ark/reports/origin.*` before writing agent
+docs or CI templates. Compact `ark start` keeps first-run setup under five project files and
+25 KB;
+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.
 
-**Default agent co-pilot:** `/ark-autopilot` (explore-first, dual plan A remediation + B
-pattern bets). Recon without applying: `/ark-explore`. Never treat empty `--plan` as
-“architecture healthy” without the explore pass.
+To remove a compact host integration, preview `ark start --remove-host <host>` and add `--apply`
+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`.
+
+**Full-skill agent co-pilot:** after explicitly installing the `/ark-*` pack, use
+`/ark-autopilot` (explore-first, dual plan A remediation + B pattern bets). Recon without
+applying: `/ark-explore`. The default compact router uses MCP/CLI directly. Never treat empty
+`--plan` as “architecture healthy” without the explore pass.
 
 `ark init --archetype <id>` maps playbook ids to named presets (`hexagonal`, `layered`,
 `feature-sliced`, `monorepo`). With `--yes` and no archetype, Ark auto-selects from
@@ -209,32 +223,35 @@ directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`
 
 ## Supported agent hosts
 
-Wire write-gate + MCP + `/ark-*` skills with:
+Wire write-gate + MCP + the full `/ark-*` skill set with:
 
 ```bash
 npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 # alias: npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
 ```
 
-| Host | Write gate | MCP | Skills path |
-|------|------------|-----|-------------|
-| Claude Code | PreToolUse hook | `.mcp.json` / `claude mcp add` | `.claude/skills/<name>/SKILL.md` |
-| Cursor | Advisory (rules + MCP) | `.cursor/mcp.json` | `.cursor/commands/` |
-| OpenAI Codex | MCP + CI | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`) | `$CODEX_HOME/prompts` (`--codex-home`) |
-| **Grok Build** | PreToolUse hook (`.grok/hooks/`) | `.grok/config.toml` + `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
+| Host | Installed paths | Skills path |
+|------|-----------------|-------------|
+| Claude Code | `.claude/settings.json` hook + `.mcp.json` / `claude mcp add` | `.claude/skills/<name>/SKILL.md` |
+| Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` |
+| OpenAI Codex | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`; doctor defers non-temp home gaps when session host ≠ Codex — see [ai-gates.md](ai-gates.md)) | `$CODEX_HOME/prompts` (`--codex-home`; fix when using Codex) |
+| **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
 
-Full copy-paste setups: [ai-gates.md](ai-gates.md). Skill inventory: main [README](../README.md#agent-skills-ark-).
+This is a path reference, not a guarantee table. Full copy-paste setups:
+[ai-gates.md](ai-gates.md). Skill inventory: main [README](../README.md#agent-skills-ark-).
 
-## Contract Discovery
+## Experimental runtime: contract discovery
 
-Prefer `createStrictArkKernel()` for strict projects. It wires the registry, graph,
+The runtime kernel is currently **experimental** and is not required for static gate adoption or
+presented as production-ready. If you are evaluating it, prefer `createStrictArkKernel()`. It
+wires the registry, graph,
 policies, event bus, audit trail, event contracts, outbox, observability,
 projections, metadata, workflow engine, and 11-layer architecture profile:
 
 ```ts
 import {
   createStrictArkKernel,
-} from 'arkgate/runtime';
+} from '@arkgate/runtime';
 
 const ark = createStrictArkKernel();
 // ... define intents, event contracts, metadata, projections, and workflows through ark.*
@@ -244,8 +261,8 @@ const contract = ark.manifest().toJSON();
 // contract.observability, projections
 ```
 
-Prefer `arkgate/runtime` for the optional kernel (root `arkgate` still re-exports for
-compat). Package surface policy: [package-surface.md](package-surface.md).
+Use `@arkgate/runtime` only when evaluating the experimental kernel. The stable `arkgate` gate
+package contains no runtime implementation. Package surface policy: [package-surface.md](package-surface.md).
 
 Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
 
@@ -354,11 +371,17 @@ if (!result.valid) {
 }
 ```
 
-Passing the `typescript` module enables built-in AST checks for raw publish calls, missing
-`metadata.source`, and source-layer mismatches. `ark-mcp` enables these checks
-automatically when TypeScript is available.
+Passing the `typescript` module enables built-in AST/symbol checks for dependencies, forbidden
+ambient globals, raw publish calls, missing `metadata.source`, and source-layer mismatches.
+`ark-mcp` enables these checks automatically when TypeScript is available. The exact supported
+syntax and unresolved-dynamic policy are documented in
+[Scanner soundness envelope](ai-gates.md#scanner-soundness-envelope).
 
-Violation codes (from `createAICodeGate`): `RAW_EVENT_PUBLISH`, `PUBLISH_MISSING_SOURCE`, `PUBLISH_SOURCE_LAYER_MISMATCH`, `FORBIDDEN_PATTERN`, `FORBIDDEN_SUBSTRING`, `FORBIDDEN_IMPORT`, `POLICY_VIOLATION`, `UNKNOWN_INTENT`, `LAYER_REFERENCE_VIOLATION`, `EXTENSION_ERROR`, `AST_ANALYZER_ERROR`.
+Relevant violation codes include `LAYER_IMPORT_VIOLATION`, `FORBIDDEN_GLOBAL`,
+`DYNAMIC_IMPORT_NOT_ALLOWLISTED`, `DYNAMIC_REQUIRE_NOT_ALLOWLISTED`, `RAW_EVENT_PUBLISH`,
+`PUBLISH_MISSING_SOURCE`, `PUBLISH_SOURCE_LAYER_MISMATCH`, `FORBIDDEN_PATTERN`,
+`FORBIDDEN_SUBSTRING`, `FORBIDDEN_IMPORT`, `POLICY_VIOLATION`, `UNKNOWN_INTENT`,
+`LAYER_REFERENCE_VIOLATION`, `EXTENSION_ERROR`, and `AST_ANALYZER_ERROR`.
 
 Use `ark-check` in CI for repository-level checks that need real file paths:
 
@@ -461,8 +484,9 @@ Example config:
 ```
 
 `ark-check` resolves imports through the TypeScript module resolver against your
-`tsconfig.json` — relative, path-alias (e.g. `@infra/db`), package imports, dynamic
-`import()`, and `require()` — plus string intent references. It also flags raw
+`tsconfig.json` — relative, path-alias (e.g. `@infra/db`), package/workspace imports,
+TypeScript `import = require()`, dynamic `import()`, and `require()` — plus string intent
+references. It also flags raw
 `publish()` calls, publish calls without `metadata.source`, and source intent literals
 whose resolved layer differs from the publishing file layer. Pass `--tsconfig <path>` to force one config
 for every file; otherwise each source file uses the nearest `tsconfig.json` above it (like
@@ -623,8 +647,8 @@ Register the server itself in `.mcp.json` so the agent can read `ark://manifest`
 }
 ```
 
-This makes the manifest + AI gate an enforced checkpoint rather than a library the agent
-must remember to call.
+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
 

package/docs/ai-gates.md

@@ -1,12 +1,14 @@
 # Gating AI Agents with ArkGate
 
 **ArkGate** (`arkgate`) is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
-The write-path gate is what makes it different from every other architecture linter:
-generated code is validated against your architecture **before it lands on disk**, not
-after the PR is red.
+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.
 
 Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
-contract, enforced everywhere. Generate it once:
+contract shared by every surface. Generate it once:
 
 ```bash
 npx arkgate-check --init
@@ -20,6 +22,11 @@ npx arkgate start
 # or: npx ark init
 ```
 
+`ark start` asks for the active agent on a TTY (or detects it otherwise) and applies a compact
+router setup: at most five project files and no `package.json` change unless you pass `--install`.
+Use `--tools <host>` to select the host explicitly. The broader command below remains the explicit
+way to install the full per-host `/ark-*` skill inventory.
+
 For non-interactive defaults, use:
 
 ```bash
@@ -34,14 +41,14 @@ npx arkgate-check --install-agent-gates
 ```
 
 The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,
-GitHub Actions, `AGENTS.md`, a Codex TOML snippet under `docs/`, and (when
+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
 you pass `--force`, so review and commit only the templates that match your project.
 
 **Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
 (`mode`: `repair` | `reject-only` | `mcp-only` | `none`, plus `prepareWrite` /
-`autoPatch` flags) so leads can see whether the write path is repair-capable or
-still reject-only.
+`autoPatch` flags), the supported profile for the active host, and the evidence actually found.
+Supported capability and installed guarantee are deliberately separate.
 
 If your project uses Codex or Grok, treat MCP registration as part of the default
 setup, not an optional extra. Ark works best when the agent can read `ark://manifest`
@@ -88,7 +95,7 @@ When no mechanical-safe patch applies, `autoPatch` is `null` (host still re-reas
 `ark_prepare_write` / judgment). Grok deny JSON also includes `autoPatch` + `"repair": true`
 when repair mode is on.
 
-`--install-agent-gates` writes Claude/Grok PreToolUse commands with `--hook-repair` enabled.
+`--install-agent-gates` writes Claude/Grok/Codex PreToolUse commands with `--hook-repair` enabled.
 Reject-only installs: drop `--hook-repair` (or unset `ARK_HOOK_REPAIR`).
 
 Add to your project's `.claude/settings.json`:
@@ -223,12 +230,30 @@ path. If it reports violations, fix them before writing. The architecture
 contract is available as the `ark://manifest` resource.
 ```
 
-Your hard backstop in Cursor is CI: `ark-check` fails the PR on anything that slips through.
+Your repository backstop in Cursor is CI: `ark-check` fails its check on anything that slips
+through. It blocks the merge only when that status is required by repository policy.
 
 ## OpenAI Codex CLI
 
 Recommended for Ark projects.
 
+Codex 0.123+ dispatches `PreToolUse` for the native `apply_patch` handler. Ark installs
+`.codex/hooks.json` with `ApplyPatch|apply_patch|Write|Edit|MultiEdit` aliases and reconstructs
+every added or updated file in a multi-file patch before allowing it. The hook root uses
+`${CODEX_PROJECT_DIR:-${PWD:-.}}`; it must not use Claude-only `CLAUDE_PROJECT_DIR`.
+
+This hook is best-effort in Codex Code Mode: some hosts execute deferred nested `apply_patch`
+calls without dispatching the project `PreToolUse` event. ArkGate therefore does not treat the
+presence of `.codex/hooks.json` as a universal hard-write guarantee; MCP remains advisory and the
+required CI status is the hard repository boundary.
+
+```bash
+npx ark-check --install-agent-gates --tools codex
+```
+
+The generated hook includes `--hook-repair`, so a rejected patch carries the same structured
+repair envelope as Claude and Grok. Codex still needs hook trust enabled for the project.
+
 Unlike Claude/Cursor (project-local MCP files), **Codex loads MCP servers only from
 `$CODEX_HOME/config.toml`** (default `~/.codex/config.toml`) — a **global** home file.
 Hand-editing with relative `--root .` is wrong: Codex does not use the project as cwd, so
@@ -251,8 +276,8 @@ args = ["arkgate-mcp", "--root", "/absolute/path/to/project", "--config", "/abso
 Then **restart Codex** — it does not hot-load MCP servers. Expect resource `ark://manifest`
 and tools `validate_code`, `ark_check`, `ark_coverage`, `ark_place`.
 
-Same model as Cursor for enforcement: MCP for discovery/validation, `ark-check` in CI as
-the hard gate. Register the MCP server as soon as the repo is adopted.
+Codex uses the best-effort local patch hook plus advisory MCP for discovery/validation and
+`ark-check` as the hard merge backstop. Register all three as soon as the repo is adopted.
 
 ### Multi-project Codex (home config last-wins)
 
@@ -272,11 +297,15 @@ primary A. It writes a **scoped secondary** table:
 |------|---------|
 | Add B without moving primary | `ark-check --install-agent-gates --tools codex` (no `--force`) |
 | Make B the primary binding | `ark-check --install-agent-gates --tools codex --force` |
-| Doctor: primary points at another permanent project | gap id `codex-home-multi-project` (warn if no secondary yet; info if scoped table already present) |
+| Doctor: primary points at another permanent project | gap id `codex-home-multi-project` (warn if no secondary yet and session host is unknown/Codex; **info + `deferred`** when the session host is known and not Codex — e.g. Grok/Claude/Cursor; info if a scoped secondary is already present) |
+| When using Codex: refresh home skills/MCP | `ark-check --install-agent-gates --skills-only --codex-home --force` |
 
 `ark-check --doctor` surfaces the multi-project state so you are not left thinking B owns
-`ark://manifest` when only a secondary table exists. Temp/upgrade primary roots are still
-rewritten fail-closed (not multi-project).
+`ark://manifest` when only a secondary table exists. **Deferred (fix when using Codex):**
+non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/prompts`) 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).
 
 ## Grok Build (xAI)
 
@@ -320,7 +349,8 @@ command = "npx"
 args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
 ```
 
-Then restart Grok or refresh via `/mcps`. Pair with CI `ark-check` as the hard merge gate.
+Then restart Grok or refresh via `/mcps`. Pair with CI `ark-check`; require that status if it
+must block merges.
 
 ## Instruction-tier agents: Windsurf, Cline, Copilot, Kiro, Roo Code, Continue, Gemini CLI
 
@@ -345,14 +375,15 @@ npx ark-check --install-agent-gates --tools windsurf,cline,copilot,kiro,roo,cont
 
 All of them derive from the same contract as `AGENTS.md` and the Cursor rule, so the
 steps cannot drift. These are advisory (the agent reads rules; nothing blocks the
-write) — keep `ark-check` in CI as the hard gate.
+write). Keep `ark-check` in CI and require its status when it must block merges.
 
 ## Any other agent runtime with shell hooks
 
-If your runtime can run a shell command before file writes and pass the tool payload on stdin (Claude Code or Grok PreToolUse contracts), `ark-mcp --hook` works as-is. The contract:
+If your runtime can run a shell command before file writes and pass the tool payload on stdin, `ark-mcp --hook` works as-is. The contract:
 
 - 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…" } }`
 - 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
@@ -387,14 +418,16 @@ Prefer keeping editor + CI on the same `ark.config.json` — do not maintain a p
 
 ## CI backstop
 
-Whatever the agent side does, gate the merge:
+Whatever the agent side does, run the merge profile in CI:
 
 ```yaml
-- run: npx ark-check --root . --config ark.config.json --strict
+- run: npx ark-check --root . --config ark.config.json --strict-merge
 ```
 
-The `--strict` profile also requires the generated CI/write gates and fails on safety
-diagnostics. Configure reviewed exceptions explicitly:
+`--strict-merge` requires strict config plus the shared gate files (`AGENTS.md`, MCP config,
+and CI workflow) and fails on safety diagnostics. `--strict` is a compatibility alias. Neither
+profile requires an editor hook; add `--require-write-hook claude|grok` only when CI must verify
+that host-specific local boundary too. Configure reviewed exceptions explicitly:
 
 ```json
 {
@@ -411,6 +444,31 @@ diagnostics. Configure reviewed exceptions explicitly:
 `ark-check --doctor --json` reports counts under `doctor.safety`. An `any` cast is
 reported as lost static assurance; it does not imply that a runtime schema was bypassed.
 
+### Scanner soundness envelope
+
+ArkGate uses the TypeScript compiler API for the governed source files. The repository scanner
+and `createAICodeGate({ typescript })` recognize these dependency forms:
+
+- `import ... from 'literal'`, side-effect imports, and `export ... from 'literal'`;
+- TypeScript `import x = require('literal')` external-module references;
+- direct `import('literal')` and direct `require('literal')` calls; and
+- relative, tsconfig path-alias, package, and installed workspace-package targets that resolve
+  to source inside the project root. Third-party or escaped targets are deliberately not governed.
+
+Direct `import(expr)` emits `DYNAMIC_IMPORT_NOT_ALLOWLISTED`; direct `require(expr)` emits
+`DYNAMIC_REQUIRE_NOT_ALLOWLISTED`. They are warnings in the default reporting profile and fail
+`--strict-config` / `--strict-merge`. The existing `dynamicImportAllowlist` name is retained for
+compatibility and is the reviewed file-level exception for both forms. Aliased loaders (for
+example `const load = require; load(expr)`) and runtime-computed module maps are not resolved.
+
+Forbidden globals use single-file TypeScript binding: parameters, variables, functions, classes,
+and imports declared in the file shadow ambient names. Bare ambient value references are reported
+even when assigned to an alias, and static dotted access through `globalThis` is normalized (for
+example `globalThis.Date.now()`). This is not whole-program data-flow analysis: computed property
+names, aliases of dotted members, and cross-file symbol provenance are outside the current
+envelope. When callers omit the `typescript` option, AICodeGate retains its conservative literal
+fallback and does not claim symbol-aware parity; the shipped `ark-mcp` path supplies TypeScript.
+
 Adopting Ark on an existing codebase with violations? Freeze them once and ratchet down:
 
 ```bash

package/docs/configuration.md

@@ -0,0 +1,97 @@
+# Versioned `ark.config.json`
+
+ArkGate treats `ark.config.json` as a versioned product contract, not an untyped settings bag.
+The CLI, MCP server, and ESLint plugin all use the same parser, migration, defaults, and validator.
+
+## Start a config
+
+`arkgate start`, `arkgate init`, and every preset emit the current metadata:
+
+```json
+{
+  "$schema": "https://unpkg.com/arkgate@2/schemas/ark.config.schema.json",
+  "schemaVersion": "1.0",
+  "include": ["src"],
+  "layers": [],
+  "rules": []
+}
+```
+
+`$schema` is for editor completion. `schemaVersion` controls ArkGate's runtime contract and is
+independent from the npm package version.
+
+For offline editor completion, point `$schema` at the installed file instead:
+
+```json
+{
+  "$schema": "./node_modules/arkgate/schemas/ark.config.schema.json",
+  "schemaVersion": "1.0"
+}
+```
+
+The same schema is exported through the stable package subpaths `arkgate/schema` and
+`arkgate/schema/ark.config.schema.json`. Node tooling can locate it with
+`require.resolve('arkgate/schema')`.
+
+## Compatibility and migration
+
+Configs without `schemaVersion` are the legacy shape shipped through ArkGate 1.x and early 2.x.
+The loader deterministically projects them to schema `1.0` in memory by adding contract metadata
+and the established defaults. It never rewrites the user's file during a check. Newly generated
+configs always contain the metadata, and unsupported future versions fail at
+`$.schemaVersion` instead of being guessed.
+
+Current defaults are:
+
+| Field | Default |
+|---|---|
+| `include` | `["src"]` |
+| `layers` | `[]` |
+| `rules` | ArkGate's strict 11-layer deny matrix |
+| `exclude` | `[]` |
+| `excludeGenerated` | `true` |
+| `cyclePolicy` | `"strict"` |
+| `dynamicImportAllowlist` | `[]` |
+| safety thresholds | zero; opt-ins disabled |
+
+JSON Schema `default` values document the effective behavior. Optional defaults are not written
+back to disk.
+
+## Unknown and invalid fields
+
+Unknown fields fail closed at every object level. Diagnostics name the exact JSON path:
+
+```text
+Invalid ArkGate config (/repo/ark.config.json):
+- $.layers[0].forbiddenGlobal: unknown field
+```
+
+The same input cannot pass CI while being silently ignored by MCP or ESLint. Invalid JSON, wrong
+types, empty required strings, duplicate string-array entries, negative safety thresholds, and
+unsupported schema versions also fail before scanning begins.
+
+## Supported fields
+
+Top-level fields:
+
+- `$schema`, `schemaVersion`, `name`
+- `include`, `exclude`, `excludeGenerated`, `frameworkOverlay`
+- `layers`, `rules`, `cyclePolicy`
+- `dynamicImportAllowlist`, `safety`
+
+Layer fields:
+
+- `name`, `patterns`, `exclude`, `description`
+- `intentPrefixes`, `forbiddenGlobals`, `mayImportInfrastructure`, `optional`
+
+Rule fields:
+
+- `from`, `to`, `allowed`, `message`, `peerIsolation`, `sliceFolders`
+
+Safety fields:
+
+- `maxTsSuppressions`, `maxAnyCasts`
+- `allowInMemory`, `allowDisabledPeerIsolation`
+
+The packaged JSON Schema is authoritative for types, constraints, defaults, and the unknown-key
+policy.

package/docs/enthusiast/README.md

@@ -15,7 +15,7 @@ aliases `ark` / `ark-check` still work).
 |------|---------|
 | **Suggest** | Propose an application shape and install a starter contract. |
 | **Adapt** | Match the contract to your real layout / raise governed coverage. |
-| **Enforce** | The contract actually governs your code; gates hold the line. |
+| **Enforce** | The contract covers the real code and checked edges are clean; host/CI guarantees remain separate. |
 
 `ark start` and `ark-check --plan` will not claim "everything is guarded" while governed coverage is near zero. On Nest/Next/express starters, init also merges **framework filename conventions** into the layer globs so day-one coverage is real.
 
@@ -27,7 +27,7 @@ aliases `ark` / `ark-check` still work).
 | **How-to** | [Pick your application shape](how-to-pick-shape.md) | Run `--recommend` / `ark_recommend` and read the plan |
 | **How-to** | [Use a gallery starter](how-to-gallery-starter.md) | Copy a phase-1 scaffold that matches your archetype |
 | **How-to** | [Apply an enthusiast policy pack](how-to-policy-pack.md) | Write `ark.config.json` from a named preset |
-| **How-to** | [Install agent gates](how-to-agent-gates.md) | Wire the write gate and `/ark-*` skills |
+| **How-to** | [Install agent gates](how-to-agent-gates.md) | Wire the host-appropriate write path and `/ark-*` skills |
 | **Reference** | [Archetypes and presets](reference-archetypes.md) | Look up playbook ids, presets, and phase-1 layers |
 | **Reference** | [Commands and artifacts](reference-commands.md) | `--recommend`, `--write-plan`, `ark-adoption-plan.json`, fix-class JSON |
 | **Explanation** | [Why application shape matters](explanation-application-shape.md) | Understand shapes vs frameworks and progressive phases |
@@ -60,4 +60,4 @@ Deep teaching example (runnable API + break exercises): [hexagonal-order-api](..
 
 - [Agent integration guide](../agent-guide.md)
 - [Public demos](../demos/)
-- [Examples index](../../examples/README.md)
+- [Examples index](../../examples/README.md)

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

@@ -8,7 +8,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 
 Installs:
 
-- Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
+- Write-path configuration (Claude/Grok hard PreToolUse; Cursor/Codex advisory MCP)
   — PreToolUse uses **`--hook-repair`** (W4): on deny, stderr may include
   `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` for hosts that re-inject a patch.
   Still exit 2 / hard block; never silent write. Drop `--hook-repair` for
@@ -24,6 +24,9 @@ Installs:
 | Codex | `docs/ark-codex-config.toml` + home MCP/prompts |
 | **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
 
+See the [canonical host support matrix](../../README.md#host-enforcement-support) for the exact
+local, MCP, CI, and repair guarantees. The table above only lists installed paths.
+
 ## Session hint
 
 `arkgate-mcp --session-context` appends when governed coverage is low:
@@ -39,7 +42,8 @@ npx arkgate-check --doctor
 npx arkgate-check --require-gates
 ```
 
-Doctor JSON (`--doctor --json`) includes **`writePath`**: whether PreToolUse is
+Doctor JSON (`--doctor --json`) includes **`writePath`**: the active host's supported profile,
+installed evidence, and whether PreToolUse is
 `repair` (machine-readable autoPatch on deny), `reject-only`, `mcp-only`, or
 `none` — plus `prepareWrite` / `autoPatch` booleans for leads.
 
@@ -49,4 +53,4 @@ After upgrading the package, refresh skills so agents see the latest plan kinds:
 npx arkgate-check --install-agent-gates --skills-only --force
 ```
 
-Full copy-paste setups: [docs/ai-gates.md](../ai-gates.md).
+Full copy-paste setups: [docs/ai-gates.md](../ai-gates.md).

package/docs/migrate-from-ark-runtime-kernel.md

@@ -129,13 +129,15 @@ Or edit `.grok/config.toml` → `args` use `arkgate-mcp`.
 
 ### TypeScript imports (runtime / Nest / ESLint only)
 
+The runtime and Nest surfaces are currently **experimental**; migrating the package name does not
+require adopting them. Static CLI/MCP enforcement remains the supported product path.
+
 ```diff
 - import { createStrictArkKernelFromConfig } from 'ark-runtime-kernel';
-+ import { createStrictArkKernelFromConfig } from 'arkgate/runtime';
-  // root `arkgate` still re-exports kernel symbols this major (compat)
++ import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
 
 - import { ArkModule } from 'ark-runtime-kernel/nestjs';
-+ import { ArkModule } from 'arkgate/nestjs';
++ import { ArkModule } from '@arkgate/runtime/nestjs';
 
 - import ark from 'ark-runtime-kernel/eslint';
 + import ark from 'arkgate/eslint';

package/docs/package-surface.md

@@ -3,10 +3,10 @@
 **Product wedge:** write gate · CI gate · co-pilot (plan / loop / skills).  
 **Not the wedge:** the optional in-process runtime kernel.
 
-**Public product site:** [arkgate.online](https://www.arkgate.online/) (promise + only flow).  
+**Public product site:** [arkgate.online](https://www.arkgate.online/) (promise + only flow).
 In-repo `docs/` remains the package/agent reference. Source: GitHub; distribution: npm.
 
-This document is the consumer contract for **what is stable** vs **what is opt-in**.
+This document is the consumer contract for **what is stable** vs **what is experimental**.
 
 ---
 
@@ -16,7 +16,9 @@ This document is the consumer contract for **what is stable** vs **what is opt-i
 |---------|----------------|-----------------|
 | **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. |
 | **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. |
+| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Versioned JSON Schema; committed v1 compatibility fixture protects rule, severity, location, and evidence fields. |
+| **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. explore dual-plan seed, day-zero origin order). |
 | **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. |
@@ -25,33 +27,31 @@ Gates need **no application code imports**. Most projects only use the CLI + MCP
 
 ---
 
-## Opt-in surfaces
+## Experimental opt-in surfaces
+
+These APIs are shipped for evaluation and compatibility, but they are **not production-ready
+product claims**. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **Runtime kernel** | **`arkgate/runtime`** (preferred) | Event bus, intents, policies, sagas, outbox, projections, `createArkKernel` / strict helpers. Optional. Not required for architecture enforcement. Built-in stores are **InMemory reference only** (not production durability) — see [production-hardening.md](./production-hardening.md). |
-| **Root package barrel** | `arkgate` | Still re-exports the runtime kernel for **compatibility**. Prefer `arkgate/runtime` for new code. Root may be thinned in a future **major**. |
-| **NestJS adapter** | `arkgate/nestjs` | Optional peer `@nestjs/common`. Wires a kernel into Nest DI. |
+| **Runtime kernel** | **`@arkgate/runtime`** | Separate 0.x package, published under the `experimental` tag. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Built-in stores are **InMemory reference only**. |
+| **Runtime migration shim** | `arkgate/runtime` | Deprecated forwarder to `@arkgate/runtime`; contains no implementation and is removed in ArkGate 4. |
+| **NestJS adapter** | `@arkgate/runtime/nestjs` | Experimental optional peer `@nestjs/common`; the deprecated `arkgate/nestjs` path forwards here. |
 
 ---
 
 ## Recommended imports
 
 ```ts
-// Preferred — opt-in runtime kernel
-import {
-  createStrictArkKernel,
-  createStrictArkKernelFromConfig,
-} from 'arkgate/runtime';
-
-// Still works this major (compat; not preferred for new code)
-import { createStrictArkKernel } from 'arkgate';
+// Preferred path when evaluating the experimental runtime kernel
+import { createStrictArkKernel, createStrictArkKernelFromConfig } from '@arkgate/runtime';
 
 // Nest adapter
-import { ArkModule, InjectArk } from 'arkgate/nestjs';
+import { ArkModule, InjectArk } from '@arkgate/runtime/nestjs';
 ```
 
-See [production-hardening.md](./production-hardening.md) for runtime operational guidance.
+See [production-hardening.md](./production-hardening.md) for requirements an eventual
+production deployment would need to satisfy; it is not a readiness certification.
 
 ---
 
@@ -71,8 +71,8 @@ See [production-hardening.md](./production-hardening.md) for runtime operational
 | Break CLI JSON field, MCP tool rename, or required `ark.config` field | **major** |
 | New optional config field, new CLI flag, additive JSON | **minor** |
 | Bugfix with no contract change | **patch** |
-| Prefer `arkgate/runtime` over root (docs only; root still exports) | **patch/minor** |
-| Remove root kernel re-exports | **major** (with migration notes) |
+| Additive experimental runtime API | `@arkgate/runtime` prerelease/minor |
+| Remove deprecated `arkgate/runtime` forwarding shim | ArkGate **4.0** |
 
 ---