arkgate 2.11.0 → 2.13.0

package/dist/{types-BZ17b9i5.d.cts → types-BxBwnBpC.d.cts}

@@ -1,3 +1,5 @@
+import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig } from './configContract-iBLxx5Tz.cjs';
+
 /**
  * Core domain primitives for Ark.
  * These types are the foundation for all governance concepts.
@@ -257,6 +259,7 @@ declare class PolicyEngine<Context = unknown> {
  * A profile turns semantic names such as `Domain.Order.Placed` into governed
  * layer names and dependency rules.
  */
+
 interface ArchitectureLayer {
     name: string;
     prefixes: string[];
@@ -269,19 +272,7 @@ interface ArchitectureLayer {
     description?: string;
     order?: number;
 }
-interface ArchitectureRule {
-    from: string;
-    to: string;
-    allowed: boolean;
-    message?: string;
-    /**
-     * When true with allowed:false: deny only when slice ids differ (same or cross layer).
-     * Requires path resolution at check time (write-gate / CI). Matches domain EdgeRule.
-     */
-    peerIsolation?: boolean;
-    /** Parent folder names that own the slice id as the next path segment. */
-    sliceFolders?: string[];
-}
+type ArchitectureRule = ArkConfigRule;
 interface ArchitectureProfile {
     name: string;
     layers: ArchitectureLayer[];
@@ -297,30 +288,12 @@ interface CreateArchitectureProfileFromArkConfigOptions {
     /** Runtime profile name. Default: config.name or "ark.config.json". */
     name?: string;
 }
-interface ArchitectureLayerConfig {
-    name: string;
-    patterns: string[];
-    /**
-     * Glob(s) carved out of this layer. A file matching any `exclude` glob is not governed by
-     * this layer even when a `patterns` glob matches — so a broad pattern like
-     * `src/**​/domain/**` can opt framework internals (`**​/kernel/**`) out of domain-purity
-     * rules without listing every include. Excluding a file also removes it from this layer's
-     * rule and `forbiddenGlobals` enforcement, since both key off layer classification.
-     */
-    exclude?: string[];
-    intentPrefixes?: string[];
-    description?: string;
-    forbiddenGlobals?: string[];
-    mayImportInfrastructure?: boolean;
-    /** Optional layers do not warn when their patterns match no files. */
-    optional?: boolean;
-}
-interface ArkCheckConfig {
-    name?: string;
-    include: string[];
-    layers: ArchitectureLayerConfig[];
+type ArchitectureLayerConfig = ArkConfigLayer;
+type ArkCheckConfig = Omit<ArkConfig, '$schema' | 'schemaVersion' | 'rules'> & {
+    $schema?: string;
+    schemaVersion?: ArkConfig['schemaVersion'];
     rules?: ArchitectureRule[];
-}
+};
 interface CreateElevenLayerArkConfigOptions {
     /** Source root used in generated file patterns. Default: "src". */
     rootDir?: string;

package/dist/{types-BZ17b9i5.d.ts → types-Wcs_l1_J.d.ts}

@@ -1,3 +1,5 @@
+import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig } from './configContract-iBLxx5Tz.js';
+
 /**
  * Core domain primitives for Ark.
  * These types are the foundation for all governance concepts.
@@ -257,6 +259,7 @@ declare class PolicyEngine<Context = unknown> {
  * A profile turns semantic names such as `Domain.Order.Placed` into governed
  * layer names and dependency rules.
  */
+
 interface ArchitectureLayer {
     name: string;
     prefixes: string[];
@@ -269,19 +272,7 @@ interface ArchitectureLayer {
     description?: string;
     order?: number;
 }
-interface ArchitectureRule {
-    from: string;
-    to: string;
-    allowed: boolean;
-    message?: string;
-    /**
-     * When true with allowed:false: deny only when slice ids differ (same or cross layer).
-     * Requires path resolution at check time (write-gate / CI). Matches domain EdgeRule.
-     */
-    peerIsolation?: boolean;
-    /** Parent folder names that own the slice id as the next path segment. */
-    sliceFolders?: string[];
-}
+type ArchitectureRule = ArkConfigRule;
 interface ArchitectureProfile {
     name: string;
     layers: ArchitectureLayer[];
@@ -297,30 +288,12 @@ interface CreateArchitectureProfileFromArkConfigOptions {
     /** Runtime profile name. Default: config.name or "ark.config.json". */
     name?: string;
 }
-interface ArchitectureLayerConfig {
-    name: string;
-    patterns: string[];
-    /**
-     * Glob(s) carved out of this layer. A file matching any `exclude` glob is not governed by
-     * this layer even when a `patterns` glob matches — so a broad pattern like
-     * `src/**​/domain/**` can opt framework internals (`**​/kernel/**`) out of domain-purity
-     * rules without listing every include. Excluding a file also removes it from this layer's
-     * rule and `forbiddenGlobals` enforcement, since both key off layer classification.
-     */
-    exclude?: string[];
-    intentPrefixes?: string[];
-    description?: string;
-    forbiddenGlobals?: string[];
-    mayImportInfrastructure?: boolean;
-    /** Optional layers do not warn when their patterns match no files. */
-    optional?: boolean;
-}
-interface ArkCheckConfig {
-    name?: string;
-    include: string[];
-    layers: ArchitectureLayerConfig[];
+type ArchitectureLayerConfig = ArkConfigLayer;
+type ArkCheckConfig = Omit<ArkConfig, '$schema' | 'schemaVersion' | 'rules'> & {
+    $schema?: string;
+    schemaVersion?: ArkConfig['schemaVersion'];
     rules?: ArchitectureRule[];
-}
+};
 interface CreateElevenLayerArkConfigOptions {
     /** Source root used in generated file patterns. Default: "src". */
     rootDir?: string;

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:
@@ -49,13 +51,23 @@ MCP `ark_recommend` and the `/ark-architect` skill.
 ### Terminal onboarding (Phase B)
 
 ```bash
-npx ark init --archetype crud-product --yes   # non-interactive: shape → preset → gates → strict check
+npx ark start --yes                             # preferred: shape → contract → **day-zero origin** → gates → 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
 npx ark-check --report beginner.html --beginner # simplified HTML for enthusiasts
 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.
+
+**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.
+
 `ark init --archetype <id>` maps playbook ids to named presets (`hexagonal`, `layered`,
 `feature-sliced`, `monorepo`). With `--yes` and no archetype, Ark auto-selects from
 `--recommend` scoring.
@@ -206,18 +218,21 @@ 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:
 
@@ -234,8 +249,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` when evaluating the experimental kernel (root `arkgate` still re-exports
+for compatibility). Package surface policy: [package-surface.md](package-surface.md).
 
 Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
 
@@ -344,11 +359,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:
 
@@ -451,8 +472,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
@@ -613,8 +635,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,13 @@
 # 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. 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
@@ -40,8 +41,8 @@ you pass `--force`, so review and commit only the templates that match your proj
 
 **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`
@@ -223,7 +224,8 @@ 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
 
@@ -251,8 +253,9 @@ 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.
+Same model as Cursor for enforcement: advisory MCP for discovery/validation and `ark-check` as
+the hard CI check. It becomes a merge block only when the status is required. Register the MCP
+server as soon as the repo is adopted.
 
 ### Multi-project Codex (home config last-wins)
 
@@ -272,11 +275,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 +327,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,7 +353,7 @@ 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
 
@@ -387,14 +395,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 +421,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,6 +129,9 @@ 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';

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,8 +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. |
-| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve. |
+| **`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. |
+| **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,20 +26,23 @@ 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`** (preferred) | Experimental event bus, intents, policies, sagas, outbox, projections, and strict helpers. 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 experimental runtime kernel for **compatibility**. Prefer `arkgate/runtime` when evaluating it. Root may be thinned in a future **major**. |
+| **NestJS adapter** | `arkgate/nestjs` | Experimental optional peer `@nestjs/common`; wires a kernel into Nest DI. |
 
 ---
 
 ## Recommended imports
 
 ```ts
-// Preferred — opt-in runtime kernel
+// Preferred path when evaluating the experimental runtime kernel
 import {
   createStrictArkKernel,
   createStrictArkKernelFromConfig,
@@ -51,7 +55,8 @@ import { createStrictArkKernel } from 'arkgate';
 import { ArkModule, InjectArk } from 'arkgate/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.
 
 ---
 
@@ -73,3 +78,10 @@ See [production-hardening.md](./production-hardening.md) for runtime operational
 | 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) |
+
+---
+
+## Release notes (maintainers)
+
+Ship notes for a version live under [releases/](./releases/) (e.g. [2.12.0.md](./releases/2.12.0.md)).
+Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](../CONTRIBUTING.md)).