arkgate 4.7.0 → 4.7.2

package/CHANGELOG.md

@@ -5,6 +5,58 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.7.2 — 2026-08-25
+
+**Patch** over **4.7.1**. Public copy uses ordinary software words: if the AI writes an
+illegal import, the write is rejected; the same check fails the pull request. Not an API Gateway.
+Not a folder linter. If the check is not required on the PR, the rules file is
+just documentation. **No required config migration.** Does not close Z09 / K01.
+
+**Status: prepared** (see `docs/releases/4.7.2.md`). npm `latest` remains **4.7.1** until
+this patch is published.
+
+### Changed
+
+- **First-contact wording (common language):** README, use/develop/docs hub/enthusiast,
+  agent-guide, ai-gates, package-surface openings, compact agent router, skill picker
+  `description` frontmatter, first-run CLI help, compact doctor strings, Action and MCP
+  descriptions, npm `description`, and the live product site lead with the deny. How:
+  one rules file, one check, one next step. Authority:
+  [product voice](docs/product-voice.md). ADR 0001 product title unchanged. Historical
+  4.6.2 three-beat line stays in that release note.
+
+## 4.7.1 — 2026-08-25
+
+**Patch** over **4.7.0**. One project skill catalog, visible package version in the
+skill picker, no home duplicates, ArkRun routed through existing skill names.
+**No required config migration.** Does not close Z09 / K01.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.7.1.md`).
+
+### Added
+
+- **Visible skill version (picker):** install stamps `description` with
+  `arkgate@<version>. ` so Codex/Claude/Cursor/Grok show the package pin without
+  opening the file. `arkVersion:` in YAML stays for doctor. Same-body stamp drift
+  refreshes without `--force` (`stamp-refresh`).
+- **`--prune-home-duplicates`:** removes frozen `/ark-*` copies from
+  `$CODEX_HOME/skills`, `~/.claude/skills`, and `~/.grok/skills` when the project
+  already has `.agents/skills`. Never deletes non-Ark skills.
+
+### Changed
+
+- **One project catalog:** `.agents/skills/<name>/SKILL.md` is the byte source.
+  Claude / Grok / OpenCode get relative adapter links. Cursor/Codex/Antigravity
+  already read `.agents/skills` — no second copy. `.cursor/commands/ark-*.md` is
+  no longer written (Cursor listed commands + skills as two copies).
+- **`--codex-home` / `--agent-homes`:** skip home skill write (and home MCP bind)
+  when the project catalog or `.codex/config.toml` already exists. Codex lists
+  user+repo; a home copy is why `/ark-*` appeared twice and stayed old.
+- **Doctor:** when home `ark-*` and project `.agents/skills` both exist, next
+  action is prune, not `--codex-home --force`.
+- **`/ark-contract`:** routes ArkRun extra edits (first extra `/ark-adopt`,
+  companion `/ark-runtime`, new files `/ark-place`). No new skill names.
+
 ## 4.7.0 — 2026-08-25
 
 **Minor** over **4.6.7**. Ships **ArkRun**: an opt-in extra on schema `1.2` for kernel
@@ -12,8 +64,7 @@ usage and complete declarations, plus companion `@arkgate/runtime` DX. Absence i
 silent (Layers / ArkRules verdicts unchanged). In-memory stores remain
 reference-only. **No required config migration.** Does not close Z09 / K01.
 
-**Status: prepared** (see `docs/releases/4.7.0.md`). npm `latest` remains **4.6.7**
-until publish.
+**Status: published** (on npm `latest`; see `docs/releases/4.7.0.md`).
 
 ### Added
 

package/README.md

@@ -2,10 +2,12 @@
 
 # ArkGate — Architecture Co-pilot for AI TypeScript
 
-**One architecture config. One check. One coach.**
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
 
-Your AI writes most of the code. ArkGate keeps that work inside an architecture you can trust —
-and makes sure a “green” check means something real.
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules
+file is just documentation.
+
+**One rules file. One check. One next step.**
 
 [![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
 [![CI](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)
@@ -16,11 +18,12 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.7.0** is prepared on this tree. **4.6.7** remains npm `latest` until publish.
+> **ArkGate 4.7.2** is prepared. npm `latest` remains **4.7.1** until this patch is published.
+> If the AI writes an illegal import, the write is rejected. Optional **ArkRun** extra on schema `1.2`.
 > A tree is **adopted** only with a required GitHub status running `arkgate-check --strict-merge`,
 > or `.ark/adoption-stance.json` `stance: "advisory-only"`. Doctor is compact (`--doctor --all`
-> for Details). [4.7.0 notes](docs/releases/4.7.0.md) · [4.6.7](docs/releases/4.6.7.md) ·
-> [4.6.6](docs/releases/4.6.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> for Details). [4.7.2 notes](docs/releases/4.7.2.md) · [4.7.1](docs/releases/4.7.1.md) ·
+> [4.7.0](docs/releases/4.7.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -41,21 +44,20 @@ Full map: **[docs/README.md](docs/README.md)**
 ```bash
 npm install -D arkgate typescript
 npx arkgate start                 # preview files + commands
-npx arkgate start --apply         # compact contract + host router + CI plan
-npx arkgate-check --doctor        # control plane: status light + primary next action
-npx arkgate-check --doctor --all  # encyclopedia (Details)
+npx arkgate start --apply         # compact config + host router + CI plan
+npx arkgate-check --doctor        # what's wrong, what to do first
+npx arkgate-check --doctor --all  # full details
 ```
 
-That is the product. Doctor is the control plane — when stuck, do **primary next action #1**.
-JSON still carries improvement compass and coach (**not a score**). Compact human output does not.
+That is the product. Stuck? Run `--doctor` and do action **#1**.
 
 ```text
-start → doctor (+ compass) → /ark-adopt (session 0) → day-to-day /ark-place
-                         ↘ /ark-explore then /ark-autopilot when leftover design remains
+start → doctor → new files in the right folder
+              ↘ leftover mess: map, then one small refactor
 ```
 
-Teams: keep the constitution out of product PRs. Local gate
-`ark-check --changed --base origin/dev`. Steward law PRs use `--contract-session`.
+Keep the rules file out of product PRs. Local check:
+`ark-check --changed --base origin/dev`. Changing the rules themselves uses `--contract-session`.
 
 Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts.
 
@@ -65,11 +67,13 @@ Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No instal
 
 ## What it is
 
-A machine-readable architecture file (`ark.config.json`) plus enforcement:
+Import rules for TypeScript, enforced twice: the editor hook rejects the write, and a
+**required** CI check rejects the pull request. `ark.config.json` is the rules file those
+checks read.
 
 | When | Tool |
 |------|------|
-| **While the AI writes** | Pre-write block on supported hosts; warning only elsewhere |
+| **While the AI writes** | The write is rejected on supported hosts; warning only elsewhere |
 | **Before merge** | `arkgate-check` as a **required** CI status |
 
 ### Two planes (4.0)
@@ -83,7 +87,9 @@ A machine-readable architecture file (`ark.config.json`) plus enforcement:
 Absence of ArkRules or ArkRun changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
 Details: [configuration](docs/configuration.md) · [use path](docs/use.md).
 
-**Not** a web framework, ORM, or job runner. Optional **ArkRun** extra and companion kernel (`@arkgate/runtime`) are separate and not required for the gate. In-memory stores are not production durability.
+**Not** an API Gateway, a folder linter, a web framework, ORM, or job runner. Optional
+**ArkRules** and **ArkRun** extras are off unless you turn them on. In-memory stores are
+not production durability.
 
 **Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
 
@@ -91,8 +97,9 @@ Details: [configuration](docs/configuration.md) · [use path](docs/use.md).
 
 ArkGate is overkill for small trees with **no AI agents** and **no multi-layer boundaries**, for
 single-developer hobby CRUDs under no integration pressure, and for teams that will not maintain
-`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. In those
-cases stay with a boundary linter alone (see [Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).
+`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. Without that
+status the rules file is just documentation — stay with a boundary linter alone (see
+[Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).
 Anyone path: [docs/use.md — When not to adopt](docs/use.md#when-not-to-adopt). Limits of a green
 check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-is--isnt).
 
@@ -227,8 +234,10 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current tree (4.7.0 prepared) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.6.7 on npm `latest`) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
+| Current tree (4.7.2 prepared) | [docs/releases/4.7.2.md](docs/releases/4.7.2.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.7.1 on npm `latest`) | [docs/releases/4.7.1.md](docs/releases/4.7.1.md) |
+| Prior published (4.7.0) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) |
+| Prior published (4.6.7) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
 | Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |
 | Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
 | Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |
@@ -266,4 +275,4 @@ Full guide: [CONTRIBUTING.md](CONTRIBUTING.md) · queue: [ROADMAP.md](ROADMAP.md
 **MCP:** [`io.github.pedroknigge/arkgate`](https://registry.modelcontextprotocol.io/)  
 Node ≥ 18 · **MIT**
 
-**Ark doesn’t invent your product. It keeps AI-generated TypeScript inside an architecture you can trust — and tells you when it isn’t really enforcing anything yet.**
+**Ark doesn’t invent your product. It rejects the illegal write — and tells you when it isn’t really enforcing anything yet.**

package/bin/lib/agent-projection.mjs

@@ -148,7 +148,7 @@ export function buildAgentProjectionBody(facts) {
         '',
     ];
     if (profile === 'compact') {
-        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action. Prefer the project-local CLI; do not wait on MCP “still connecting”.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Identity handshake is optional when the CLI already resolved the project root. Call `ark_identity` only when using MCP evidence.', '4. Read architecture config with `ark_manifest` (same expectation) or the local `ark.config.json`. `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — what is wrong and what to do first. Prefer the project-local CLI; do not wait on MCP “still connecting”.', '2. Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Identity handshake is optional when the CLI already resolved the project root. Call `ark_identity` only when using MCP evidence.', '4. Read the rules file with `ark_manifest` (same expectation) or the local `ark.config.json`. `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix the import, do not weaken the rules file.', '6. Single door: illegal imports → fix; leftover design work → map then one small refactor with user OK.', '', '### Layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
         lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: local `ark.config.json` / CLI, or `ark_manifest` after a matched `ark_identity` handshake. Identity is optional when CLI already resolved the root.', '- Host docs: the same projection schema is merged into `AGENTS.md` and `CLAUDE.md` (`ark agents-md --write`).', '');

package/bin/lib/agent-skills-package.mjs

@@ -234,6 +234,35 @@ export function validateAgentSkillsPackage(entries) {
         presentCount: names.length,
     };
 }
+/**
+ * Visible package stamp at the start of Agent Skills `description`.
+ * Hosts show `description` in the picker; `arkVersion:` in YAML is invisible there.
+ * Example: `arkgate@4.7.1. Session 0 — mark the Ark path.`
+ */
+export const ARK_SKILL_DESCRIPTION_VERSION_PATTERN = /^arkgate@(\S+)\.\s/;
+/** Prefix written at install time (`arkgate@<version>. `). */
+export function skillDescriptionVersionPrefix(version) {
+    const v = String(version ?? '').trim();
+    return v ? `arkgate@${v}. ` : '';
+}
+/** Drop a leading `arkgate@<version>. ` stamp; other text is unchanged. */
+export function stripSkillDescriptionVersion(description) {
+    return String(description ?? '').replace(ARK_SKILL_DESCRIPTION_VERSION_PATTERN, '');
+}
+/** Version inside a stamped description, or null when the prefix is absent. */
+export function parseSkillDescriptionVersion(description) {
+    const match = String(description ?? '').match(ARK_SKILL_DESCRIPTION_VERSION_PATTERN);
+    return match?.[1] ?? null;
+}
+/**
+ * Idempotent: replace an existing `arkgate@…` prefix or add one.
+ * Empty `version` strips the prefix (authoring templates stay unversioned).
+ */
+export function stampSkillDescription(description, version) {
+    const rest = stripSkillDescriptionVersion(description);
+    const v = typeof version === 'string' ? version.trim() : '';
+    return v ? `${skillDescriptionVersionPrefix(v)}${rest}` : rest;
+}
 /**
  * Normalize skill file content for identity compare (LF newlines, strip BOM).
  * Does not strip or rewrite frontmatter — Agent Skills export is 1:1 with flat templates.

package/bin/lib/check-args.mjs

@@ -124,6 +124,7 @@ export function parseArgs(argv) {
     else if (arg === '--watch') args.watch = true;
     else if (arg === '--beginner') args.beginner = true;
     else if (arg === '--codex-home') args.codexHome = true;
+    else if (arg === '--prune-home-duplicates') args.pruneHomeDuplicates = true;
     else if (arg === '--claude-home') args.claudeHome = true;
     else if (arg === '--grok-home') args.grokHome = true;
     else if (arg === '--agent-homes') {

package/bin/lib/ci-and-commands.mjs

@@ -314,7 +314,7 @@ ${placementTable}`;
 ${projectionBlock}
 ## Default agent flow (if unsure, do only this)
 
-1. Status anytime: \`${doctorCmd}\` — **control plane** (one status light, one next action; not a mode picker).
+1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first (not a mode picker).
 2. If \`ark.config.json\` is missing: run \`${startCmd}\` once (preview), then \`${startCmd} --apply\`.
 3. Guided end-to-end work (“make architecture sound”): **\`/ark-autopilot\`** — explore → dual plan A (edges) + B (shape) → write mechanical-safe and judgment; one Shape refactor. Day-zero origin is frozen by \`ark start\`/\`ark init\` (or adopt if missing) **before** agent docs.
 4. After ordinary feature edits: run \`${checkCmd}\` (teams: \`ark-check --changed --base origin/dev\`). On violations → **\`/ark-autopilot\`** (or \`/ark-place\` for new files). **Do not edit** \`ark.config.json\` / \`.ark-baseline.json\` in a product PR — that is a steward \`--contract-session\`. If doctor shows **Stewards (advisory)**, ask who owns the law — do not invent \`stewards[]\`. Leftover names \`/ark-fix\` / \`/ark-loop\` / \`/ark-contract\` are shortcuts to those doors.
@@ -405,10 +405,10 @@ ${projectionBlock}
 
 **Primary path (do this):**
 
-1. Status anytime: \`${doctorCmd}\` — one status light, one primary next action (control plane).
+1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first.
 2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
 3. CLI-first: if the local CLI already resolved this project root, do not wait on MCP “still connecting”. Identity handshake is optional in that case. When you do trust MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means this is not proven to be the right project: restart the host and use the local CLI meanwhile.
-4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a gate deny, fix the architecture — do not weaken \`ark.config.json\`.
+4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a deny, fix the illegal import — do not weaken \`ark.config.json\`.
 5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`. The host-readable projection is AGENTS.md and CLAUDE.md (same schema).
 
 **Single door when residual remains:**

package/bin/lib/doctor-next-actions.mjs

@@ -73,7 +73,11 @@ export function collectDoctorNextActions(ctx) {
   } else if (remStale > 0) {
     actions.push('refresh stale /ark-* skills (--install-agent-gates --skills-only --force) — gates are installed, catalog is stale');
   }
-  if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.preferProject !== true) {
+  if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.duplicateHome) {
+    actions.push(
+      'remove duplicate Codex home /ark-* skills (project .agents/skills is enough): --install-agent-gates --skills-only --prune-home-duplicates'
+    );
+  } else if (ctx.codexHomeGap && ctx.codexConcernActive && ctx.codexHomeGap.preferProject !== true) {
     actions.push(
       ctx.codexHomeGap.catalogMetadataInvalid
         ? 'repair invalid Codex home catalog metadata after verifying the newest installed version'

package/bin/lib/enforcement-honesty.mjs

@@ -432,7 +432,7 @@ export function buildProductHonesty(input = {}) {
         message:
           operatingMode === 'adapt'
             ? 'Operating mode is ADAPT — not finished until whole-tree green, zero blocking, and zero design smells (contract and tree still disagree).'
-            : 'Operating mode is SUGGEST — not finished until whole-tree green, zero blocking, and zero design smells (contract is not yet the control plane).',
+            : 'Operating mode is SUGGEST — not finished until whole-tree green, zero blocking, and zero design smells (the rules file is not yet binding).',
       });
     }
   }

package/bin/lib/first-run-help.mjs

@@ -3,11 +3,11 @@
  */
 
 export function setupUsage() {
-  return `arkgate (alias ark) — One architecture config. One check. One coach.
+  return `arkgate (alias ark) — Illegal import: write rejected. Same check fails the PR.
 
   arkgate start              preview (no writes)
   arkgate start --apply      write host + CI setup
-  arkgate-check --doctor     where you are + one next action
+  arkgate-check --doctor     what's wrong, what to do first
 
 Stuck? Run doctor. Do #1.
 `;
@@ -27,7 +27,7 @@ Every flag: arkgate --help --all
 }
 
 export function setupUsageAll() {
-  return `arkgate (alias ark) — One architecture config. One check. One coach.
+  return `arkgate (alias ark) — Illegal import: write rejected. Same check fails the PR.
 
 Usage:
   arkgate start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
@@ -200,8 +200,8 @@ export function checkUsageAll() {
     'windsurf, cline, copilot, kiro, roo, continue, gemini',
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',
-    'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
-    '.agents/skills/ (Codex REPO catalog), .grok/skills/, .windsurf/workflows/,',
+    'detected tool\'s command location (.agents/skills/ canonical catalog;',
+    '.claude/skills/ and .grok/skills/ adapters; .windsurf/workflows/,',
     '.clinerules/workflows/, .github/prompts/).',
     'Kiro, Roo, Continue, and Gemini have no command mechanism and receive only their',
     'rule file. Existing files are never overwritten without --force, so re-running',

package/bin/lib/install-migrate.mjs

@@ -68,8 +68,11 @@ import {
   detectSkillGaps,
   arkPackageVersion,
   verifyHostSkillCatalog,
+  canonicalSkillPath,
+  usesCanonicalSkillCatalog,
 } from './skill-install.mjs';
-import { installRepoSkillFile, installSkillCatalog, skillInstallLine, skillInstallNote } from './skill-write.mjs';
+import { applySkillCatalogFollowup } from './skill-catalog-apply.mjs';
+import { installRepoSkillFile, skillInstallNote } from './skill-write.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import {
   stripMcpServerArgs,
@@ -80,7 +83,6 @@ import {
   RUNNER_BEFORE_ARK,
 } from './mcp-adoption.mjs';
 import { inspectCodexInstallActivation, printCodexActivationHandoff, reportPartialInstall } from './install-activation.mjs';
-import { installRequestedAgentHomes } from './agent-homes.mjs';
 import {
   hasHardWriteHook,
   validateHardWriteRequest,
@@ -235,9 +237,18 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
   const skills = skillTemplates().map(([name, content]) => [name, stampSkill(content, version)]);
   const skillPaths = new Set();
   if (!compact) {
-    for (const tool of selectedTools) {
+    const skillTools = [...selectedTools].filter((tool) => SKILL_TOOL_TARGETS[tool]);
+    const writeCanonical = skillTools.some((tool) => usesCanonicalSkillCatalog(tool));
+    if (writeCanonical) {
+      for (const [name, content] of skills) {
+        const relativePath = canonicalSkillPath(name);
+        skillPaths.add(relativePath);
+        add(relativePath, content, 'skill');
+      }
+    }
+    for (const tool of skillTools) {
+      if (usesCanonicalSkillCatalog(tool)) continue;
       const target = SKILL_TOOL_TARGETS[tool];
-      if (!target) continue;
       for (const [name, content] of skills) {
         const relativePath = target(name);
         skillPaths.add(relativePath);
@@ -613,60 +624,12 @@ export function runInstallAgentGates(args) {
     console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`);
   }
 
-  // --codex-home writes SKILL.md skills to $CODEX_HOME/skills/<name>/SKILL.md.
-  // Codex's real catalog loads skill directories (not flat $CODEX_HOME/prompts).
-  // Repo installs already write `.agents/skills/<name>/SKILL.md` when `codex` is
-  // selected; home install is for multi-project / non-repo-local refresh.
-  const homeResults = [];
-  if (args.codexHome) {
-    const dir = codexSkillsDir();
-    console.log('');
-    console.log(
-      `Codex home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${dir}/<name>/SKILL.md):`
-    );
-    console.log(
-      '  Compatibility: monotonic downgrade protection requires every shared-catalog writer ' +
-        'to use ArkGate 4.2.0+; pre-4.2 --codex-home ignores this catalog. Upgrade legacy repos first.'
-    );
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-    } catch (error) {
-      console.error(`  FAILED to create ${dir} (${error.message})`);
-      homeResults.push({ relativePath: dir, status: 'failed' });
-    }
-    if (homeResults.length === 0) {
-      const skillName = (skill) =>
-        Array.isArray(skill) ? skill[0] : skill?.name || skill;
-      const projectHasCatalog = skills.some((skill) =>
-        fs.existsSync(path.join(root, '.agents', 'skills', skillName(skill), 'SKILL.md'))
-      );
-      if (projectHasCatalog) {
-        console.log(
-          '  Project .agents/skills already has this catalog; home write is optional. Prefer the project copy.'
-        );
-      }
-      for (const result of installSkillCatalog({
-        directory: dir,
-        skills,
-        packageVersion: version,
-        force: args.force,
-        scope: 'home',
-      })) {
-        console.log(skillInstallLine(result));
-        homeResults.push(result);
-      }
-    }
-  }
-
-  installRequestedAgentHomes({
+  const { skillNames, homeResults } = applySkillCatalogFollowup({
     root,
+    tools,
     skills,
     version,
-    force: args.force,
-    claudeHome: args.claudeHome,
-    grokHome: args.grokHome,
-    agentHomes: args.agentHomes,
-    json: args.json,
+    args,
   });
 
   // Optional legacy/home fallback. Normal Codex installs use the project-scoped
@@ -679,8 +642,10 @@ export function runInstallAgentGates(args) {
   // A redirected CODEX_HOME (tests/isolation) may still wire as requested.
   let codexMcp = null;
   const wantCodexWire = !args.compact && !args.skillsOnly && args.codexHome;
+  const projectCodexMcp = fs.existsSync(path.join(root, '.codex', 'config.toml'));
   const skipHomeWire =
-    wantCodexWire && isTempOrUpgradeRoot(root) && usesDefaultCodexHome();
+    wantCodexWire &&
+    ((isTempOrUpgradeRoot(root) && usesDefaultCodexHome()) || projectCodexMcp);
   if (wantCodexWire && !skipHomeWire) {
     codexMcp = wireCodexMcp(root, args.force);
     console.log('');
@@ -702,7 +667,14 @@ export function runInstallAgentGates(args) {
       );
     }
   } else if (skipHomeWire) {
-    codexMcp = { status: 'skipped', file: codexConfigPath(), reason: 'temp-root' };
+    const reason = projectCodexMcp ? 'project-config' : 'temp-root';
+    codexMcp = { status: 'skipped', file: codexConfigPath(), reason };
+    if (projectCodexMcp && !args.json) {
+      console.log('');
+      console.log(
+        'Skip Codex home MCP — project .codex/config.toml is the binding. Home config pointing at another checkout is leftover; do not rebind it from this install.'
+      );
+    }
   }
 
   const { codexProjectConfigured, runtimeActivation } =

package/bin/lib/managed-upgrade.mjs

@@ -126,13 +126,8 @@ function hasArkText(root, relativePath) {
 
 const HOST_SIGNALS = {
   claude: ['.claude/settings.json', '.claude/skills/ark-upgrade/SKILL.md'],
-  cursor: [
-    '.cursor/mcp.json',
-    '.cursor/hooks.json',
-    '.cursor/rules/ark.mdc',
-    '.cursor/commands/ark-upgrade.md',
-  ],
-  codex: ['.codex/hooks.json', '.codex/config.toml', '.agents/skills/ark-upgrade/SKILL.md'],
+  cursor: ['.cursor/mcp.json', '.cursor/hooks.json', '.cursor/rules/ark.mdc'],
+  codex: ['.codex/hooks.json', '.codex/config.toml'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json', '.grok/skills/ark-upgrade/SKILL.md'],
   antigravity: ['.agents/hooks.json'],
   opencode: ['opencode.json', '.opencode/skills/ark-upgrade/SKILL.md'],

package/bin/lib/skill-catalog-apply.mjs

@@ -0,0 +1,126 @@
+/**
+ * HS post-write skill catalog: adapters, home skip/prune, Claude/Grok home skip.
+ * Kept out of install-migrate so that file stays inside its module budget.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { installRequestedAgentHomes } from './agent-homes.mjs';
+import { codexSkillsDir } from './codex-home.mjs';
+import {
+  canonicalSkillPath,
+  linkSkillHostAdapters,
+  pruneHomeArkSkillDuplicates,
+  skillTemplateNames,
+} from './skill-install.mjs';
+import { installSkillCatalog, skillInstallLine } from './skill-write.mjs';
+
+function skillName(skill) {
+  return Array.isArray(skill) ? skill[0] : skill?.name || skill;
+}
+
+export function projectCatalogReady(root, skillNames) {
+  return skillNames.some((name) => fs.existsSync(path.join(root, canonicalSkillPath(name))));
+}
+
+export function applySkillCatalogFollowup({
+  root,
+  tools,
+  skills,
+  version,
+  args,
+}) {
+  const skillNames = skills.map(skillName);
+  if (!args.compact && skillNames.length > 0) {
+    const adapterResults = linkSkillHostAdapters(root, tools, skillNames, Boolean(args.force));
+    for (const row of adapterResults) {
+      if (row.status === 'linked' || row.status === 'copied') {
+        console.log(
+          `  ${row.status.padEnd(7)} ${row.relativePath}  (adapter → .agents/skills/${row.name})`
+        );
+      }
+    }
+  }
+  if (args.pruneHomeDuplicates) {
+    const pruned = pruneHomeArkSkillDuplicates(
+      root,
+      skillNames.length ? skillNames : skillTemplateNames()
+    );
+    if (!pruned.ok) {
+      console.log('  skip    --prune-home-duplicates (no project .agents/skills catalog yet)');
+    } else if (pruned.removed.length === 0) {
+      console.log('  skip    --prune-home-duplicates (no home ark-* copies)');
+    } else {
+      console.log(`  pruned  ${pruned.removed.length} home ark-* path(s) (project catalog is enough)`);
+    }
+  }
+
+  const homeResults = [];
+  if (args.codexHome) {
+    const dir = codexSkillsDir();
+    console.log('');
+    console.log(
+      `Codex home skills (scope=home-shared; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}; target=${dir}/<name>/SKILL.md):`
+    );
+    console.log(
+      '  Compatibility: monotonic downgrade protection requires every shared-catalog writer ' +
+        'to use ArkGate 4.2.0+; pre-4.2 --codex-home ignores this catalog. Upgrade legacy repos first.'
+    );
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (error) {
+      console.error(`  FAILED to create ${dir} (${error.message})`);
+      homeResults.push({ relativePath: dir, status: 'failed' });
+    }
+    if (homeResults.length === 0) {
+      const hasCatalog = skills.some((skill) =>
+        fs.existsSync(path.join(root, '.agents', 'skills', skillName(skill), 'SKILL.md'))
+      );
+      if (hasCatalog) {
+        console.log(
+          '  Skip home write — project .agents/skills is the catalog. Codex lists user+repo; a home copy duplicates every /ark-*.'
+        );
+        console.log(
+          `  Remove leftover home copies: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --prune-home-duplicates')}`
+        );
+      } else {
+        for (const result of installSkillCatalog({
+          directory: dir,
+          skills,
+          packageVersion: version,
+          force: args.force,
+          scope: 'home',
+        })) {
+          console.log(skillInstallLine(result));
+          homeResults.push(result);
+        }
+      }
+    }
+  }
+
+  const catalogReady = projectCatalogReady(root, skillNames);
+  if ((args.claudeHome || args.grokHome || args.agentHomes) && catalogReady) {
+    if (!args.json) {
+      console.log('');
+      console.log(
+        'Skip Claude/Grok home skill write — project .agents/skills + adapters are the catalog. Home ark-* copies override or duplicate.'
+      );
+      console.log(
+        `  Remove leftover home copies: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --prune-home-duplicates')}`
+      );
+    }
+  } else {
+    installRequestedAgentHomes({
+      root,
+      skills,
+      version,
+      force: args.force,
+      claudeHome: args.claudeHome,
+      grokHome: args.grokHome,
+      agentHomes: args.agentHomes,
+      json: args.json,
+    });
+  }
+
+  return { skillNames, homeResults };
+}