arkgate 2.3.0 → 2.4.0

package/docs/agent-guide.md

@@ -1,7 +1,11 @@
-# Ark — Agent Integration Guide
+# ArkGate — Agent Integration Guide
 
-**Ark — Architecture Co-pilot for AI TypeScript.** This guide describes how AI agents
-and codegen tools can safely interact with the write gate, MCP tools, and `/ark-*` skills.
+**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.
+
+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:
+see [typescript-support.md](typescript-support.md).
 
 ## Architecture playbook and `ark-check --recommend`
 
@@ -120,7 +124,8 @@ directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`
 Wire write-gate + MCP + `/ark-*` skills with:
 
 ```bash
-npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
+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 |
@@ -424,7 +429,8 @@ not replace your web framework, HTTP clients, or job scheduler.
 ## Write-Path Gate (MCP)
 
 The strongest place to constrain an AI agent is the moment it writes a file, not after.
-`ark-mcp` exposes Ark over MCP (zero dependencies, JSON-RPC over stdio) so a host can gate
+`arkgate-mcp` / `ark-mcp` exposes ArkGate over MCP (JSON-RPC over stdio; gate host needs a
+JS-API TypeScript — nested or project) so a host can gate
 the write path:
 
 ```bash

package/docs/ai-gates.md

@@ -1,32 +1,36 @@
-# Gating AI Agents with Ark
+# Gating AI Agents with ArkGate
 
-**Ark** is the architecture co-pilot for AI TypeScript (write gate · CI · plan/loop).
+**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.
 
-Everything below uses the same `ark.config.json` as `ark-check` (CI) — one contract, enforced everywhere. Generate it once:
+Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
+contract, enforced everywhere. Generate it once:
 
 ```bash
-npx ark-check --init
+npx arkgate-check --init
+# aliases: ark-check, ark init, arkgate start
 ```
 
 For guided setup with prompts, use:
 
 ```bash
-npx ark init
+npx arkgate start
+# or: npx ark init
 ```
 
 For non-interactive defaults, use:
 
 ```bash
-npx ark init --yes
+npx arkgate start --yes
+# or: npx ark init --yes
 ```
 
 You can also generate only the starter gate files for common agent runtimes and CI:
 
 ```bash
-npx ark-check --install-agent-gates
+npx arkgate-check --install-agent-gates
 ```
 
 The command writes templates for `.mcp.json`, Claude hooks, Cursor MCP/rules,

package/docs/brownfield-adoption.md

@@ -61,19 +61,20 @@ violations — the ratchet only moves toward zero.
 
 ## 5. Burn down, in order
 
-`summary.edges` is the burn-down order. Two patterns cover most of it — and Ark tells you
-which is which via the `typeOnly` tag (value = real coupling, fix first; type-only = placement):
-
-- **Type-only inversion** (a lower layer `import type`s a type that lives in an upper layer):
-  move the type down to the layer that owns it and re-export it from the original module for
-  back-compat. Cosmetic at runtime, `tsc`-verifiable, safe to sweep. (Not mechanical if the
-  type extends a persistence/ORM row — that needs a domain-owned type/port — or if the source
-  file mixes types with logic — split first.)
-- **Raw infrastructure access** (a route/handler running SQL or importing the DB directly):
-  relocate the data-access **verbatim** into a repository/adapter method the route calls. Same
-  query bytes = same behavior; do NOT rewrite the query. This edits the data layer — if your
-  repo reserves that to core maintainers, migrate one route as a demonstrated pattern and hand
-  the bulk over; a route with interleaved transactions isn't a pure relocation, so flag it.
+`summary.edges` is the burn-down order. Prefer `ark-check --plan`: it tags each step
+`mechanical-safe` / `judgment` / `deferred` and sets `remediationKind` for auto-safe cases.
+
+- **Type-only inversion** (`typeOnly` — plan: `type-only-import-move`): move the type to the
+  owning layer + re-export for back-compat. Safe to sweep when mechanical-safe.
+- **Pure-type file** (`sourcePureTypeModule` — plan: `pure-type-file-relocate`): whole file is
+  type-surface only — relocate the file (or extract types) to the owning layer.
+- **Value import of pure type module** (`targetTypeOnlyExports` — plan:
+  `import-type-from-pure-type-module`): convert static import to `import type`. Not safe for
+  `require()` / dynamic `import()`.
+- **Raw infrastructure access** (value coupling — always **judgment**): relocate data-access
+  **verbatim** into a repository/adapter. Same query bytes = same behavior; do NOT rewrite the
+  query. If CODEOWNERS reserves the data layer, migrate one route as a pattern and hand bulk
+  work over; interleaved transactions aren't a pure relocation — flag them.
 
 `/ark-fix` resolves each cluster at the root cause; fixing a frozen violation shrinks the
 baseline permanently. Re-freeze lower with `--update-baseline` as you go.

package/docs/demos/03-copilot-autopilot.md

@@ -39,9 +39,11 @@ npx ark-check --plan            # human view (includes Governed: N%)
 npx ark-check --plan --json     # { ok, plan: { goal, counts, steps } }
 ```
 
-Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence` and a
-plain-language `rationale`. `goal.met` is true only when there are no active violations **and**
-governed coverage is meaningful — so a clean plan that checks almost nothing is not "done."
+Each step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence`,
+`rationale`, and often `remediationKind`. Only three kinds are auto-safe: type-only type move,
+pure-type **file** relocate, and `import type` of pure-type modules. `goal.met` is true only when
+there are no active violations **and** governed coverage is meaningful — so a clean plan that
+checks almost nothing is not "done."
 
 ### 3. Carry the plan out — the autopilot
 

package/docs/enthusiast/README.md

@@ -1,10 +1,11 @@
-# Ark — Architecture Co-pilot (enthusiast track)
+# ArkGate — Architecture Co-pilot (enthusiast track)
 
 Plain-language onboarding for builders who use AI agents but are not professional
 developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-to,
-reference, and explanation.
+reference, and explanation. Package: **`arkgate`** (CLI: `arkgate` / `arkgate-check`;
+aliases `ark` / `ark-check` still work).
 
-## How Ark talks to you (2.0)
+## How ArkGate talks to you
 
 **Entry style** — who is driving: *newbie* (`ark start` / `/ark-autopilot`) vs *expert* (individual commands).
 

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

@@ -1,15 +1,17 @@
 # How to install agent gates
 
 ```bash
-npx ark-check --install-agent-gates
-npx ark-check --install-agent-gates --tools claude,cursor,codex,grok
+npx arkgate-check --install-agent-gates
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+# aliases: ark-check …
 ```
 
 Installs:
 
 - Write-gate hook configuration (Claude / Grok PreToolUse; Cursor advisory + MCP)
 - MCP server entry (`.mcp.json`, Cursor/Codex/Grok equivalents)
-- `/ark-*` skills including **`/ark-architect`** and **`/ark-autopilot`**
+- `/ark-*` skills including **`/ark-architect`**, **`/ark-autopilot`**, **`/ark-loop`**
+  (with current `mechanical-safe` remediation kinds)
 
 | Host | Extra paths |
 |------|-------------|
@@ -20,7 +22,7 @@ Installs:
 
 ## Session hint
 
-`ark-mcp --session-context` appends when governed coverage is low:
+`arkgate-mcp --session-context` appends when governed coverage is low:
 
 ```
 New to Ark? Run /ark-architect or: ark-check --recommend
@@ -29,8 +31,14 @@ New to Ark? Run /ark-architect or: ark-check --recommend
 ## Verify gates
 
 ```bash
-npx ark-check --doctor
-npx ark-check --require-gates
+npx arkgate-check --doctor
+npx arkgate-check --require-gates
+```
+
+After upgrading the package, refresh skills so agents see the latest plan kinds:
+
+```bash
+npx arkgate-check --install-agent-gates --skills-only --force
 ```
 
 Full copy-paste setups: [docs/ai-gates.md](../ai-gates.md).

package/docs/enthusiast/reference-commands.md

@@ -1,9 +1,13 @@
 # Reference: commands and artifacts
 
+Product: **ArkGate** (`arkgate`). Prefer `arkgate` / `arkgate-check` / `arkgate-mcp`; aliases
+`ark` / `ark-check` / `ark-mcp` work for one major. TypeScript 5–7: [typescript-support.md](../typescript-support.md).
+
 ## Recommendation
 
 ```bash
-ark-check --recommend [--json] [--write-plan]
+arkgate-check --recommend [--json] [--write-plan]
+# alias: ark-check …
 ```
 
 MCP: `ark_recommend` — same JSON body.
@@ -33,18 +37,29 @@ Pack metadata: `templates/policy-packs/enthusiast-*.json`.
 ## Init and verify
 
 ```bash
-ark init --archetype <id> --yes
-ark-check --doctor [--json]
-ark-check --coverage [--json]
-ark-check --strict-config
-ark-check --report out.html --beginner
-ark-check --watch
+arkgate start --yes                    # guided setup + plan
+ark init --archetype <id> --yes        # alias path
+arkgate-check --doctor [--json]
+arkgate-check --coverage [--json]
+arkgate-check --plan [--json]          # mechanical-safe vs judgment vs deferred
+arkgate-check --strict-config
+arkgate-check --report out.html --beginner
+arkgate-check --watch
 ```
 
+## Plan classes (`--plan --json`)
+
+| `class` | Agent may auto-apply? | Examples (`remediationKind`) |
+|---------|----------------------|------------------------------|
+| `mechanical-safe` | Yes (validate + rollback) | `type-only-import-move`, `pure-type-file-relocate`, `import-type-from-pure-type-module` |
+| `judgment` | No — propose | value imports, ports, infra relocate, cycles |
+| `deferred` | No | unclear shape |
+
 ## Violation JSON (enthusiast fields)
 
 When present on violations:
 
 - `fixClass` — e.g. `port-inversion`, `file-move`
 - `effort` — `small` | `medium`
-- `enthusiastHint` — plain English fix guidance
+- `enthusiastHint` — plain English fix guidance
+- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`

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

@@ -42,6 +42,24 @@ npx arkgate upgrade
 
 (`ark upgrade` works too — both install `arkgate@latest` and refresh gates.)
 
+### TypeScript 7
+
+If the project uses **TypeScript 7** as `tsc`, the gate still works: ArkGate embeds a JS-API
+TypeScript host and falls back when `require('typescript')` is version-only. See
+[typescript-support.md](typescript-support.md). Optional dual-install (TS 6 for tools + TS 7
+CLI) is documented there.
+
+### MCP args (avoid double binary)
+
+`.mcp.json` / `.cursor/mcp.json` must look like:
+
+```json
+"args": ["arkgate-mcp", "--root", ".", "--config", "ark.config.json"]
+```
+
+**Not** `["ark-mcp", "arkgate-mcp", …]` — that breaks MCP stdio. Fixed by
+`npx arkgate-check --install-agent-gates --migrate-commands` (ArkGate ≥ 2.4.0).
+
 ---
 
 ## What to change in your repo

package/docs/typescript-support.md

@@ -0,0 +1,142 @@
+# TypeScript support (5.x · 6.x · 7.x)
+
+ArkGate’s architecture gate (`arkgate-check` / `ark-mcp`) needs a **JavaScript API**
+TypeScript package that exposes:
+
+- `ts.sys` (at least `fileExists`)
+- `createSourceFile` (AST)
+- `resolveModuleName` (module graph)
+
+It does **not** require the Go-native `tsc` binary for the gate. Type-checking
+semantics of your app still come from **your** project `typescript` + `tsconfig`.
+
+## Supported versions
+
+| Range | Status |
+|-------|--------|
+| **TypeScript 5.x** | Fully supported (primary CI) |
+| **TypeScript 6.x** | Supported (bridge release before 7) |
+| **TypeScript 7.x** | Supported as **project** compiler; gate loads project TS when API-compatible, otherwise **falls back** to a JS-API TypeScript |
+
+Optional peer (documentational):
+
+```json
+"peerDependencies": {
+  "typescript": ">=5.0.0 <8"
+}
+```
+
+ArkGate does not hard-require `typescript` as a runtime dependency of the package
+itself; the CLI resolves it from the **project** first, then from the environment.
+
+## How loading works
+
+1. Prefer `require('typescript')` from the **project** root (when it has `sys` + AST + resolve).  
+2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.  
+3. If nothing usable is found:  
+   - `--plan` still prints **coverage honesty** (no import graph)  
+   - full check exits non-zero with an install hint  
+
+Debug which TypeScript was used:
+
+```bash
+ARK_DEBUG_TS=1 npx arkgate-check --plan
+# → [ark-check] TypeScript 5.9.x via arkgate (fallback)
+```
+
+## TypeScript 7 notes
+
+TypeScript 7 is the **native (Go) compiler** generation. Important for tools like ArkGate:
+
+- **`require('typescript')` on 7.0.x** exports only `{ version, versionMajorMinor }` — not `sys`, `createSourceFile`, or `resolveModuleName`.  
+- Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.  
+- Stable **programmatic JS API** maturity continues over the 7.x line (Microsoft: full story into **7.1+**).  
+- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the write/CI gate keeps working while you try TS 7 as the project compiler.  
+- Your **tsconfig** must follow TS 6/7 defaults (see below) or `tsc` / resolve can fail independently of ArkGate.
+
+### tsconfig defaults that surprise teams (TS 6 → 7)
+
+Adopt these before or when moving to TS 7:
+
+| Option | TS7 direction |
+|--------|----------------|
+| `strict` | default `true` |
+| `module` | often `esnext` |
+| `moduleResolution` | `nodenext` or `bundler` (not `node` / `node10`) |
+| `baseUrl` | removed — put paths relative to project root |
+| `types` | default `[]` — list globals explicitly, e.g. `["node"]` |
+| `rootDir` | default `./` — set `"./src"` when sources live under `src` |
+| `target: es5` | unsupported |
+| `esModuleInterop: false` | unsupported |
+
+Example consumer-friendly skeleton (also used in `tests/fixtures/ts-consumer`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "rootDir": "./src",
+    "types": ["node"],
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}
+```
+
+## Side-by-side TypeScript 6 + 7 (tooling)
+
+If you need **tsc 7** for builds and a **JS API 6** for tools that still expect classic exports:
+
+```json
+{
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.0",
+    "typescript-7": "npm:typescript@^7.0.0"
+  }
+}
+```
+
+- `npx tsc6` — TypeScript 6 CLI (from the alias package)  
+- `npx typescript-7` / install path — TypeScript 7 CLI as needed  
+
+ArkGate will prefer the project’s `typescript` package; keep that entry **API-compatible** (5/6, or 7 once `sys` is present). See Microsoft’s TS 7 RC blog for dual-install details.
+
+## CI matrix (this repo)
+
+GitHub Actions job `ts-compat` installs TypeScript **5.9.x**, **6.0.x**, and **7.0.x** into a temp copy of `tests/fixtures/ts-consumer` and runs:
+
+```bash
+node bin/ark-check.mjs --root <fixture> --plan --json --no-cache
+```
+
+Locally:
+
+```bash
+node scripts/ts-compat-matrix.mjs 5.9.3
+node scripts/ts-compat-matrix.mjs 6.0.3
+node scripts/ts-compat-matrix.mjs 7.0.2
+```
+
+## What “compatible” means for ArkGate
+
+| Goal | Status |
+|------|--------|
+| Gate does not crash on project TS 7 | Yes (fallback if API incomplete) |
+| Plan/check work with project TS 5/6 | Yes |
+| Plan/check work when project has TS 7 + usable `sys` | Yes (uses project) |
+| Gate uses native Go typechecker API exclusively | Not required; future if 7.1+ exposes a stable Node API we adopt |
+| User tsconfigs with removed options still “just work” | User must migrate tsconfig (TS6/7); Ark reports resolve/parse failures clearly |
+
+## Future (7.1+ programmatic API)
+
+When Microsoft ships a stable Node API for native TypeScript 7.1+:
+
+1. Extend `usableTypescript` for the new export shape.  
+2. Keep the multi-version matrix green.  
+3. Optionally prefer project TS 7 for resolution without fallback.
+
+Until then, **fallback + matrix** is the compatibility story so teams can try TS 7 today without breaking the architecture gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -41,10 +41,12 @@
     "docs/demos",
     "docs/ai-gates.md",
     "docs/migrate-from-ark-runtime-kernel.md",
+    "docs/typescript-support.md",
     "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
     "docs/production-hardening.md",
+    "tests/fixtures/ts-consumer",
     "templates",
     "server.json",
     "README.md",
@@ -60,18 +62,26 @@
     "typecheck": "tsc --noEmit",
     "security:audit": "npm audit --omit=dev --audit-level=high",
     "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
+    "test:ts-compat": "node scripts/ts-compat-matrix.mjs 5.9.3 && node scripts/ts-compat-matrix.mjs 6.0.3 && node scripts/ts-compat-matrix.mjs 7.0.2",
     "eval:agent": "node eval/run.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
     "clean": "rm -rf dist",
     "release:npm": "node scripts/release-npm.mjs",
     "prepack": "npm run build"
   },
+  "dependencies": {
+    "typescript": "^5.9.3"
+  },
   "peerDependencies": {
-    "@nestjs/common": ">=9"
+    "@nestjs/common": ">=9",
+    "typescript": ">=5.0.0 <8"
   },
   "peerDependenciesMeta": {
     "@nestjs/common": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "overrides": {
@@ -89,7 +99,6 @@
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",
-    "typescript": "^5.5.3",
     "vitest": "^3.2.6"
   },
   "engines": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.3.0",
+      "version": "2.4.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-autopilot.md

@@ -55,12 +55,14 @@ Never tell a user "your architecture is guarded" while `--plan` reports `goal.me
 
 3. **Show the plan.** Run `ark-check --plan` and explain it in outcome terms: how many fixes are
    _safe to auto-apply_ vs _need your decision_ vs _deferred_, and what the goal is (a clean,
-   enforced architecture). Confirm before changing anything.
+   enforced architecture). Safe auto steps are only the three `mechanical-safe` kinds:
+   type-only type move, pure-type **file** relocate, and converting static imports of pure-type
+   modules to `import type` (see `/ark-loop`). Confirm before changing anything.
 
 4. **Drive the loop.** Hand off to **`/ark-loop`**: in a discardable git worktree, auto-apply
-   the `mechanical-safe` steps one at a time (validate with `ark-check`, roll back regressions),
-   and PROPOSE each `judgment` step in plain language for a yes/no. Loop until the plan's
-   `goal.met` is true or a round makes no progress.
+   the `mechanical-safe` steps one at a time (match each `remediationKind`; validate with
+   `ark-check`, roll back regressions), and PROPOSE each `judgment` step in plain language for
+   a yes/no. Loop until the plan's `goal.met` is true or a round makes no progress.
 
 5. **Confirm it stays clean.** Verify the gates are installed and active so the architecture is
    enforced from now on (in CI, and at write time if the MCP hook is wired) — the

package/templates/skills/ark-explain.md

@@ -36,16 +36,21 @@ Your job is to **teach with this repo's real data** and leave a shareable visual
    ```bash
    npx ark-check --coverage
    npx ark-check --doctor
+   npx ark-check --plan
    ```
 
-   so your spoken explanation matches the report's governed% and operating mode
-   (SUGGEST / ADAPT / ENFORCE).
+   so your spoken explanation matches the report's governed%, operating mode
+   (SUGGEST / ADAPT / ENFORCE), and the plan's safe-to-auto vs decision counts.
 
 The HTML report is the visual twin of this skill: architecture map, files per layer,
 dependency direction, matrix, violations, enforcement points, Ark fitness score, and a
 **Senior diagnostics** block (coupling fan-in/out, deny density, purity surface, pattern
 forensics, baseline taxonomy) for tech leads.
 
+When explaining the **plan**, name the three `mechanical-safe` remediation kinds only
+(type-only move, pure-type file relocate, `import type` of pure-type modules) — everything
+else is judgment/deferred and must not be auto-applied.
+
 ## Spoken / written explanation
 
 1. **Load the real contract**: `ark.config.json`, `ark://manifest` if available, `AGENTS.md`.

package/templates/skills/ark-fix.md

@@ -47,18 +47,22 @@ paste output you can generate yourself.
   with the impure implementation outside the domain, and pass it in.
 - **Intent prefix mismatch**: rename the intent to the layer's declared prefix,
   or move the handler to the layer that owns that prefix.
-- **Type-only inversion** (a lower layer `import type`s something from an upper layer,
-  e.g. a domain module importing a type that happens to live in a UI hook): move the
-  TYPE down to the layer that owns it (e.g. `src/lib/<domain>/types.ts`), and re-export
-  it from the original module for back-compat (`export type { X } from "@/lib/<domain>/types"`)
-  so no consumer breaks. This is the highest-volume, safest adoption fix — verify with
-  `tsc --noEmit`. It often also breaks a circular dependency that ran through the hook.
-  Two cases where the move is NOT mechanical — stop and flag instead of forcing it:
-  (a) the type extends a persistence/ORM row (e.g. a Drizzle schema type) — moving it to a
-  domain layer would couple domain→Persistence (the write gate will block it), so it needs a
-  domain-owned type or port, not a move; (b) the source file mixes the type with runtime
-  logic (stubs, helpers, mock builders) — split the types into their own module first, then
-  move.
+- **Type-only inversion** (`typeOnly: true` on a `LAYER_IMPORT_VIOLATION` — plan class
+  `mechanical-safe`, `remediationKind: type-only-import-move`): a lower layer `import type`s
+  something from an upper layer (e.g. domain importing a type that lives in a UI hook). Move the
+  TYPE down to the layer that owns it and re-export for back-compat
+  (`export type { X } from "@/lib/<domain>/types"`). Highest-volume safe fix — verify with the
+  gate (and `tsc --noEmit` if present). Not mechanical if: (a) the type extends a persistence/ORM
+  row — needs a domain-owned type/port; (b) the source mixes types with runtime logic — split
+  first, then move (or use pure-type file relocate when the *whole file* is type-only).
+- **Pure-type file relocate** (`sourcePureTypeModule` + type-only edge —
+  `remediationKind: pure-type-file-relocate`): the entire source file is type-surface only (no
+  runtime statements). Relocate the **file** to the owning layer (or extract the type module
+  there). Behavior-preserving; do not invent runtime ports.
+- **Value-syntax import of a pure type-only module** (`targetTypeOnlyExports` —
+  `remediationKind: import-type-from-pure-type-module`): convert static `import { T } from …`
+  to `import type { T } from …`. Never auto-apply for `require()` / dynamic `import()` (those stay
+  judgment — they still execute the module).
 - **Raw infrastructure access in an orchestration/UI layer** (a route/handler or component
   that runs SQL or imports the DB client directly — e.g. `sqlClient\`SELECT …\`` or
   `import { db } from "@/lib/db"` inside `src/app/**`): this is the value-import counterpart

package/templates/skills/ark-loop.md

@@ -21,15 +21,25 @@ If Ark isn't set up yet, run `ark start` (or `ark-check --recommend` then `ark i
 1. **Read the plan.** Run `ark-check --plan --json` (add `--baseline .ark-baseline.json` if the
    repo uses a baseline). It returns `goal` (with `met`, `activeViolations`, `autoApplicable`,
    `needsDecision`, `deferred`) and `steps[]`, each tagged `class` (`mechanical-safe` /
-   `judgment` / `deferred`) with a `confidence` and a plain-language `rationale`. If
-   `goal.met` is already true, report "nothing to do" and stop.
+   `judgment` / `deferred`) with a `confidence`, plain-language `rationale`, and often
+   `remediationKind`. If `goal.met` is already true, report "nothing to do" and stop.
+
+   **`mechanical-safe` kinds you may auto-apply** (zero false-safe — never invent others):
+
+   | `remediationKind` | What to do |
+   |-------------------|------------|
+   | `type-only-import-move` | Edge is already `import type` / type-only: move the **type** to the owning layer + re-export for back-compat |
+   | `pure-type-file-relocate` | Whole **source file** is pure type-surface (`sourcePureTypeModule`) + type-only edge: relocate the file (or extract types) to the owning layer |
+   | `import-type-from-pure-type-module` | Static value-syntax import of a pure type-only **target** module (`targetTypeOnlyExports`): convert to `import type` (and place type if needed) |
+
+   Still **judgment** (never auto): value imports, `require()` / dynamic `import()`, mixed modules with side effects, forbidden globals, cycles, verbatim infra relocation.
 
 2. **Work in a discardable git worktree.** Create one (`git worktree add`) so the entire run is
    reversible and never disturbs the user's working tree. Do all edits there. Nothing is
    permanent until the user reviews the final diff.
 
-3. **Apply the `mechanical-safe` steps, one at a time, validated.** For each such step
-   (e.g. a type-only import moved to the layer that owns it + a re-export for back-compat):
+3. **Apply the `mechanical-safe` steps, one at a time, validated.** Match the step's
+   `remediationKind` (table above) — do not expand the edit into a broader refactor:
    - Record the current active-violation count from the plan.
    - Make the edit at the SOURCE (fix the placement; don't add an `ark-*-disable` or edit the
      baseline/config to hide it).

package/templates/skills/ark-upgrade.md

@@ -18,6 +18,26 @@ npx arkgate-check --install-agent-gates --force
 
 Guide: `docs/migrate-from-ark-runtime-kernel.md` in the package (or on GitHub).
 
+**TypeScript 7 projects:** ArkGate falls back to a nested JS-API TypeScript when the
+project's `typescript` main export is version-only (TS 7.0). After upgrade, point users at
+`docs/typescript-support.md` if the gate or `ARK_DEBUG_TS=1` mentions fallback. Dual install
+(TS6 JS API + TS7 CLI) is optional for tooling that still needs classic `tsc` APIs.
+
+**MCP double-bin check (identity cutover):** after upgrade, open `.mcp.json` and
+`.cursor/mcp.json`. `args` must contain **exactly one** of `arkgate-mcp` / `ark-mcp`
+(prefer `arkgate-mcp`), never both. If both appear, run:
+
+```
+npx arkgate-check --install-agent-gates --migrate-commands
+```
+
+`ark upgrade` already runs migrate-commands; re-run it if an older 2.x left dual names.
+
+**Adoption completeness:** run `npx arkgate-check --doctor` (or `--doctor --json`) and
+read the **Adoption** section — host gaps, Codex home temp paths, optional-but-populated
+core layers, missing origin snapshot, baseline policy. Fix commands are printed per gap.
+HTML reports include the same Adoption card (separate from the 0–100 fitness score).
+
 ## Fast path
 
 One command does the whole flow — update the package, refresh gates + `/ark-*` skills
@@ -30,7 +50,12 @@ arkgate upgrade
 
 Use it when the user just wants the update done. Run the detailed steps below instead when
 you need to inspect the changelog first, handle a pnpm cooling-off window, or the one-liner
-reports a problem to triage.
+reports a problem to triage. Always refresh skills so agents pick up new `mechanical-safe`
+kinds and TS guidance:
+
+```
+npx arkgate-check --install-agent-gates --skills-only --force
+```
 
 ## Steps