arkgate 4.1.1 → 4.2.0

package/bin/lib/html-report-evolution.mjs

@@ -0,0 +1,114 @@
+export function renderEvolutionSection({
+  originSnapshot,
+  currentSnapshot,
+  originJustCreated,
+  esc,
+  formatDelta,
+  historyMax,
+}) {
+  if (!currentSnapshot) return '';
+  if (originJustCreated || !originSnapshot) {
+    return `<div class="section card evolve">
+        <h2>Origin baseline captured</h2>
+        <p class="dim" style="margin:.2rem 0 0;font-size:.9rem">
+          This is the <b>first</b> architecture snapshot for this project
+          (<code>.ark/reports/origin.json</code> + <code>origin.html</code>).
+          Future reports will show deltas against this starting point so you can prove evolution.
+        </p>
+      </div>`;
+  }
+  const scoreComparable =
+    typeof originSnapshot.arkVersion === 'string' &&
+    originSnapshot.arkVersion.length > 0 &&
+    originSnapshot.arkVersion === currentSnapshot.arkVersion;
+  const rows = [
+    ['Ark score', originSnapshot.score, currentSnapshot.score, '', scoreComparable],
+    ['Governed %', originSnapshot.governedPercent, currentSnapshot.governedPercent, 'pp', true],
+    ['Files in scope', originSnapshot.totalFiles, currentSnapshot.totalFiles, '', true],
+    ['Classified files', originSnapshot.classifiedFiles, currentSnapshot.classifiedFiles, '', true],
+    ['Active violations', originSnapshot.activeViolations, currentSnapshot.activeViolations, '', true],
+    ['Value violations', originSnapshot.valueViolations, currentSnapshot.valueViolations, '', true],
+    ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, '', true],
+    ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, '', true],
+    ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, '', true],
+    ['Gates configured', originSnapshot.gatesOn, currentSnapshot.gatesOn, '', true],
+  ];
+  const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
+  const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';
+  const tr = rows
+    .map(([label, from, to, unit, comparable]) => {
+      const d =
+        comparable && typeof from === 'number' && typeof to === 'number'
+          ? to - from
+          : null;
+      const good =
+        label.includes('violation') || label.includes('Violation')
+          ? d != null && d <= 0
+          : label.includes('Governed') ||
+              label.includes('score') ||
+              label.includes('Classified') ||
+              label.includes('Gates')
+            ? d != null && d >= 0
+            : null;
+      const cls =
+        d == null || d === 0 ? 'flat' : good === true ? 'up' : good === false ? 'down' : 'flat';
+      const delta =
+        d == null
+          ? '—'
+          : unit === 'pp'
+            ? formatDelta(Math.round(d * 10) / 10, { suffix: ' pp' })
+            : formatDelta(d);
+      return `<tr>
+          <td>${esc(label)}</td>
+          <td class="num">${from ?? '—'}</td>
+          <td class="num">${to ?? '—'}</td>
+          <td class="num delta ${cls}">${esc(delta)}</td>
+        </tr>`;
+    })
+    .join('\n');
+  const originLayers = originSnapshot.layerFiles || {};
+  const currentLayers = currentSnapshot.layerFiles || {};
+  const layerKeys = [
+    ...new Set([...Object.keys(originLayers), ...Object.keys(currentLayers)]),
+  ].sort();
+  const layerTr = layerKeys
+    .map((name) => {
+      const from = originLayers[name] || 0;
+      const to = currentLayers[name] || 0;
+      const d = to - from;
+      const cls = d === 0 ? 'flat' : d > 0 ? 'up' : 'down';
+      return `<tr>
+          <td class="ln">${esc(name)}</td>
+          <td class="num">${from}</td>
+          <td class="num">${to}</td>
+          <td class="num delta ${cls}">${esc(formatDelta(d))}</td>
+        </tr>`;
+    })
+    .join('\n');
+  const scoreNote = scoreComparable
+    ? ''
+    : `<p class="dim" style="margin:-.35rem 0 .75rem;font-size:.88rem">
+        Ark score is not comparable across Ark versions
+        (<code>${esc(originSnapshot.arkVersion ?? 'unknown')}</code> →
+        <code>${esc(currentSnapshot.arkVersion ?? 'unknown')}</code>); its Δ is shown as —.
+        Raw coverage, files, violations, layers, rules, and gate metrics remain visible.
+      </p>`;
+  return `<div class="section card evolve">
+      <h2>Evolution vs origin</h2>
+      <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
+        Origin snapshot <code>${esc(originDate)}</code> → this report <code>${esc(nowDate)}</code>
+        · frozen at <code>.ark/reports/origin.*</code> · reopen origin HTML anytime for the starting picture.
+      </p>
+      ${scoreNote}
+      <table class="layers">
+        <tr><th>Metric</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
+        ${tr}
+      </table>
+      <h3>Files per layer</h3>
+      <table class="layers">
+        <tr><th>Layer</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
+        ${layerTr || '<tr><td colspan="4" class="dim">No layer file data in snapshots.</td></tr>'}
+      </table>
+      <p class="legend">Green Δ = improvement for that metric (↑ coverage/score/gates, ↓ violations). Score Δ is comparable only within the same Ark version. History JSON under <code>.ark/reports/history/</code> (last ${historyMax}).</p>
+    </div>`;
+}

package/bin/lib/html-report.mjs

@@ -21,7 +21,9 @@ import {
 } from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
 import { capabilityBadgesFor, renderAdvisorySections } from './html-report-advisories.mjs';
+import { renderEvolutionSection } from './html-report-evolution.mjs';
 import { arkGitignoreAppendDecision } from './ark-gitignore.mjs';
+import { captureGitSnapshot } from './report-snapshot-context.mjs';
 
 export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
@@ -161,6 +163,7 @@ export function buildReportSnapshot({
         return path.basename(root);
       }
     })(),
+    git: captureGitSnapshot(root),
     ok: Boolean(ok),
     mode: mode ?? null,
     score: score ?? null,
@@ -1228,95 +1231,14 @@ export function renderHtmlReport({
     <div class="gates">${enforcementRows}</div>
   </div>
 
-  ${(() => {
-    if (!currentSnapshot) return '';
-    // First report: originSnapshot is null at render time (written to disk just after).
-    if (originJustCreated || !originSnapshot) {
-      return `<div class="section card evolve">
-        <h2>Origin baseline captured</h2>
-        <p class="dim" style="margin:.2rem 0 0;font-size:.9rem">
-          This is the <b>first</b> architecture snapshot for this project
-          (<code>.ark/reports/origin.json</code> + <code>origin.html</code>).
-          Future reports will show deltas against this starting point so you can prove evolution.
-        </p>
-      </div>`;
-    }
-    const rows = [
-      ['Ark score', originSnapshot.score, currentSnapshot.score, ''],
-      ['Governed %', originSnapshot.governedPercent, currentSnapshot.governedPercent, 'pp'],
-      ['Files in scope', originSnapshot.totalFiles, currentSnapshot.totalFiles, ''],
-      ['Classified files', originSnapshot.classifiedFiles, currentSnapshot.classifiedFiles, ''],
-      ['Active violations', originSnapshot.activeViolations, currentSnapshot.activeViolations, ''],
-      ['Value violations', originSnapshot.valueViolations, currentSnapshot.valueViolations, ''],
-      ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, ''],
-      ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, ''],
-      ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, ''],
-      ['Gates configured', originSnapshot.gatesOn, currentSnapshot.gatesOn, ''],
-    ];
-    const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
-    const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';
-    const tr = rows
-      .map(([label, from, to, unit]) => {
-        const d =
-          typeof from === 'number' && typeof to === 'number' ? to - from : null;
-        const good =
-          label.includes('violation') || label.includes('Violation')
-            ? d != null && d <= 0
-            : label.includes('Governed') || label.includes('score') || label.includes('Classified') || label.includes('Gates')
-              ? d != null && d >= 0
-              : null;
-        const cls =
-          d == null || d === 0 ? 'flat' : good === true ? 'up' : good === false ? 'down' : 'flat';
-        const delta =
-          d == null
-            ? '—'
-            : unit === 'pp'
-              ? formatDelta(Math.round(d * 10) / 10, { suffix: ' pp' })
-              : formatDelta(d);
-        return `<tr>
-          <td>${esc(label)}</td>
-          <td class="num">${from ?? '—'}</td>
-          <td class="num">${to ?? '—'}</td>
-          <td class="num delta ${cls}">${esc(delta)}</td>
-        </tr>`;
-      })
-      .join('\n');
-    // Layer file deltas
-    const originLayers = originSnapshot.layerFiles || {};
-    const currentLayers = currentSnapshot.layerFiles || {};
-    const layerKeys = [...new Set([...Object.keys(originLayers), ...Object.keys(currentLayers)])].sort();
-    const layerTr = layerKeys
-      .map((name) => {
-        const from = originLayers[name] || 0;
-        const to = currentLayers[name] || 0;
-        const d = to - from;
-        const cls = d === 0 ? 'flat' : d > 0 ? 'up' : 'down';
-        return `<tr>
-          <td class="ln">${esc(name)}</td>
-          <td class="num">${from}</td>
-          <td class="num">${to}</td>
-          <td class="num delta ${cls}">${esc(formatDelta(d))}</td>
-        </tr>`;
-      })
-      .join('\n');
-    return `<div class="section card evolve">
-      <h2>Evolution vs origin</h2>
-      <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
-        Origin snapshot <code>${esc(originDate)}</code> → this report <code>${esc(nowDate)}</code>
-        · frozen at <code>.ark/reports/origin.*</code> · reopen origin HTML anytime for the starting picture.
-      </p>
-      <table class="layers">
-        <tr><th>Metric</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${tr}
-      </table>
-      <h3>Files per layer</h3>
-      <table class="layers">
-        <tr><th>Layer</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${layerTr || '<tr><td colspan="4" class="dim">No layer file data in snapshots.</td></tr>'}
-      </table>
-      <p class="legend">Green Δ = improvement for that metric (↑ coverage/score/gates, ↓ violations). History JSON under <code>.ark/reports/history/</code> (last ${ARK_REPORT_HISTORY_MAX}).</p>
-    </div>`;
-  })()}
+  ${renderEvolutionSection({
+    originSnapshot,
+    currentSnapshot,
+    originJustCreated,
+    esc,
+    formatDelta,
+    historyMax: ARK_REPORT_HISTORY_MAX,
+  })}
 
   <div class="section card senior">
     <h2>Senior diagnostics</h2>

package/bin/lib/import-resolve.mjs

@@ -35,32 +35,55 @@ export function readTsconfigAliases(ts, root) {
   }
 }
 
+function canonicalPathWithMissingTail(value) {
+  const resolved = path.resolve(value);
+  let current = resolved;
+  const tail = [];
+  while (true) {
+    try {
+      return path.join(fs.realpathSync(current), ...tail.reverse());
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return resolved;
+      tail.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
 /**
  * Resolve an import specifier to a repo-relative path.
  * Relative + tsconfig-aliased only; bare packages → undefined.
  */
 export function resolveSpecifierToRel(specifier, fromFilePath, root, tsAliases) {
+  const canonicalRoot = canonicalPathWithMissingTail(root);
   let abs;
   if (specifier.startsWith('./') || specifier.startsWith('../')) {
     if (!fromFilePath) return undefined;
-    const fromAbs = path.isAbsolute(fromFilePath)
-      ? fromFilePath
-      : path.resolve(root, fromFilePath);
-    abs = path.resolve(path.dirname(fromAbs), specifier);
+    const fromAbs = canonicalPathWithMissingTail(
+      path.isAbsolute(fromFilePath) ? fromFilePath : path.resolve(root, fromFilePath)
+    );
+    abs = canonicalPathWithMissingTail(path.resolve(path.dirname(fromAbs), specifier));
   } else {
     const alias = tsAliases.aliases.find((a) => specifier.startsWith(a.from));
     if (!alias) return undefined;
-    abs = path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`);
+    abs = canonicalPathWithMissingTail(
+      path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`)
+    );
   }
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  return rel.startsWith('..') ? undefined : rel;
+  const relative = path.relative(canonicalRoot, abs);
+  if (path.isAbsolute(relative) || relative.startsWith('..')) return undefined;
+  return relative.split(path.sep).join('/');
 }
 
 function filePathToRel(filePath, root) {
   if (!filePath || typeof filePath !== 'string') return undefined;
-  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath);
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  return rel.startsWith('..') ? undefined : rel;
+  const abs = canonicalPathWithMissingTail(
+    path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath)
+  );
+  const relative = path.relative(canonicalPathWithMissingTail(root), abs);
+  if (path.isAbsolute(relative) || relative.startsWith('..')) return undefined;
+  return relative.split(path.sep).join('/');
 }
 
 function classifyProbe(root, rel, layers) {
@@ -130,4 +153,3 @@ export function createImportTargetResolver(ts, root, config) {
     return undefined;
   };
 }
-

package/bin/lib/install-activation.mjs

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { codexProjectMcpIsValid } from './codex-home.mjs';
+import { codexRuntimeActivation } from './enforcement-state.mjs';
+
+export function inspectCodexInstallActivation(root, enabled) {
+  let configuredOnDisk = false;
+  if (enabled) {
+    try {
+      configuredOnDisk = codexProjectMcpIsValid(
+        fs.readFileSync(path.join(root, '.codex', 'config.toml'), 'utf8'),
+        root
+      );
+    } catch {
+      // Missing/unreadable configuration remains explicitly unverified.
+    }
+  }
+  return {
+    codexProjectConfigured: configuredOnDisk,
+    runtimeActivation: codexRuntimeActivation({
+      configuredOnDisk,
+      restartRequired: configuredOnDisk,
+    }),
+  };
+}
+
+export function reportPartialInstall({
+  root,
+  tools,
+  results,
+  homeResults,
+  earlyWritten,
+  codexMcp,
+  runtimeActivation,
+}) {
+  const failed = [...results, ...homeResults]
+    .filter((result) => result.status === 'failed')
+    .map((result) => ({
+      target: result.relativePath ?? '(unknown template)',
+      reason: 'write failed',
+    }));
+  if (codexMcp?.status === 'failed') {
+    failed.push({
+      target: codexMcp.file,
+      reason: codexMcp.message ?? 'Codex MCP registration failed',
+    });
+  }
+  if (failed.length === 0) return false;
+
+  const written = new Set([
+    ...earlyWritten,
+    ...[...results, ...homeResults]
+      .filter((result) => result.status === 'written' || result.status === 'merged')
+      .map((result) => result.relativePath),
+  ]);
+  console.error('\nINSTALL PARTIAL — some artifacts were written; activation is not complete.');
+  console.error('Written:');
+  if (written.size === 0) console.error('  - (none)');
+  for (const relativePath of written) console.error(`  - ${relativePath}`);
+  console.error('Failed:');
+  for (const failure of failed) console.error(`  - ${failure.target}: ${failure.reason}`);
+  console.error('Recovery:');
+  console.error(
+    `  - Fix the listed path or permission error, then re-run ${arkCommand(root, 'ark-check', `--install-agent-gates${tools.size > 0 ? ` --tools ${[...tools].join(',')}` : ''}`)}.`
+  );
+  console.error('  - Existing customized files were preserved; no destructive rollback was attempted.');
+  if (tools.has('codex')) {
+    console.error(`  - Runtime activation: ${JSON.stringify(runtimeActivation)}`);
+  }
+  return true;
+}
+
+export function printCodexActivationHandoff(root, configuredOnDisk, runtimeActivation) {
+  console.log(
+    configuredOnDisk
+      ? '  CODEX MCP CONFIGURED — RUNTIME NOT VERIFIED'
+      : '  CODEX MCP CONFIGURATION UNRESOLVED — RUNTIME NOT VERIFIED'
+  );
+  console.log(`  Runtime activation: ${JSON.stringify(runtimeActivation)}`);
+  console.log(
+    configuredOnDisk
+      ? `  Restart Codex, then call ark_identity with expectedRoot "${path.resolve(root)}".`
+      : '  Repair `.codex/config.toml`, then restart Codex and call ark_identity.'
+  );
+  console.log('  Do not trust MCP verdicts before the project identity matches.');
+}

package/bin/lib/install-migrate.mjs

@@ -63,12 +63,11 @@ import {
   SKILL_TOOL_TARGETS,
   skillTemplates,
   stampSkill,
-  installedSkillVersion,
-  isVersionOlder,
   detectSkillGaps,
   arkPackageVersion,
   verifyHostSkillCatalog,
 } from './skill-install.mjs';
+import { installRepoSkillFile, installSkillCatalog, skillInstallLine, skillInstallNote } from './skill-write.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import {
   stripMcpServerArgs,
@@ -78,6 +77,7 @@ import {
   PREFERRED_CHECK_BIN,
   RUNNER_BEFORE_ARK,
 } from './mcp-adoption.mjs';
+import { inspectCodexInstallActivation, printCodexActivationHandoff, reportPartialInstall } from './install-activation.mjs';
 import {
   hasHardWriteHook,
   validateHardWriteRequest,
@@ -181,7 +181,7 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
       compact ? compactAgentInstructions(root, compactHost) : agentInstructions(root)
     );
     // Always write project MCP registration — compact hosts other than Claude still need
-    // ark://manifest for agents (field: compact grok start left doctor reporting Missing .mcp.json
+    // project-bound ark_identity/ark_manifest (field: compact Grok start left doctor reporting Missing .mcp.json
     // when AGENTS lost compact markers or hosts were mixed).
     add('.mcp.json', mcpJson(root));
     const deploy = detectDeployPathQuality(root);
@@ -416,9 +416,11 @@ export function runInstallAgentGates(args) {
   // settings.json, CI workflow, rules) are the ones users customize, so a plain
   // `--force` clobbers them — this is the safe way to pick up new skill versions.
   // Do not mutate package.json under --skills-only (typecheck bootstrap is gates/CI).
+  const earlyWritten = new Set();
   if (!args.skillsOnly) {
     // S4.4: always write check:architecture on gate install / start (including compact).
     const checkBootstrap = ensureCheckArchitectureScript(root, { write: true });
+    if (checkBootstrap.changed) earlyWritten.add('package.json');
     if (checkBootstrap.changed && !args.json) {
       console.log(
         `Added package.json script "check:architecture": "${checkBootstrap.script}" (local/CI parity).`
@@ -426,6 +428,7 @@ export function runInstallAgentGates(args) {
     }
     // Bootstrap typecheck before CI template so generated workflow includes the step.
     const typecheckBootstrap = ensureTypecheckScript(root, { write: !args.compact });
+    if (typecheckBootstrap.changed && !args.compact) earlyWritten.add('package.json');
     if (typecheckBootstrap.changed && !args.compact && !args.json) {
       console.log(
         `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
@@ -438,7 +441,7 @@ export function runInstallAgentGates(args) {
     compact: args.compact,
     skillsOnly: args.skillsOnly,
   });
-  const { skills, skillPaths, version } = catalog;
+  const { skills, version } = catalog;
   const assetKindByPath = new Map(
     catalog.assets.map((asset) => [asset.relativePath, asset.kind ?? 'gate'])
   );
@@ -450,7 +453,10 @@ export function runInstallAgentGates(args) {
   if (args.compact && priorCompactHost === 'none' && [...tools][0]) {
     const genericMcp = path.join(root, '.mcp.json');
     try {
-      if (fs.readFileSync(genericMcp, 'utf8') === mcpJson(root)) fs.rmSync(genericMcp);
+      if (fs.readFileSync(genericMcp, 'utf8') === mcpJson(root)) {
+        fs.rmSync(genericMcp);
+        earlyWritten.add('.mcp.json');
+      }
     } catch {
       // Missing or customized user MCP configuration is deliberately retained.
     }
@@ -459,6 +465,9 @@ export function runInstallAgentGates(args) {
   const results = templates.map(([relativePath, content]) => {
     // S4.1: preserve content-identity customized/conflicted managed assets even under --force.
     const kind = assetKindByPath.get(relativePath) ?? 'gate';
+    if (kind === 'skill') {
+      return installRepoSkillFile(root, relativePath, content, version, args.force);
+    }
     if (
       args.force &&
       managedPresent &&
@@ -477,7 +486,14 @@ export function runInstallAgentGates(args) {
       }
       const tableStart = content.indexOf('[mcp_servers.ark]');
       const generatedPrelude = tableStart > 0 ? content.slice(0, tableStart) : '';
-      const mergeBase = generatedPrelude ? existing.replace(generatedPrelude, '') : existing;
+      const mergeBase = generatedPrelude
+        ? existing
+            .replace(generatedPrelude, '')
+            .replace(
+              /^# Generated by ark-check --install-agent-gates \(Codex project scope\)\.\n# Restart Codex after changes; MCP servers are loaded when the project session starts\.\n/m,
+              ''
+            )
+        : existing;
       const merged = upsertCodexMcpTable(mergeBase, 'ark', content);
       if (merged === existing) return { relativePath, status: 'skipped' };
       return writeTemplate(root, relativePath, merged, true);
@@ -527,7 +543,9 @@ export function runInstallAgentGates(args) {
     );
   });
 
-  console.log('Ark agent gate templates:');
+  console.log(
+    `Ark agent gate templates (scope=repo; source=${version ? `arkgate@${version}` : 'arkgate@unknown'}):`
+  );
   let staleSkipped = 0;
   let preservedCustomized = 0;
   for (const result of results) {
@@ -549,13 +567,10 @@ export function runInstallAgentGates(args) {
     if (result.status === 'skipped-customized') {
       preservedCustomized += 1;
       note = '  (customized — content-identity preserved)';
-    } else if (result.status === 'skipped' && skillPaths.has(result.relativePath) && version) {
-      const installed = installedSkillVersion(path.join(root, result.relativePath));
-      if (installed === null || isVersionOlder(installed, version)) {
+    } else if (result.status === 'skipped' && result.skillPlan) {
+      note = `  (${skillInstallNote(result.skillPlan)})`;
+      if (result.skillPlan.reason === 'existing-preserved') {
         staleSkipped += 1;
-        note = `  (stale: ${installed ?? 'no stamp'} < ${version})`;
-      } else {
-        note = '  (up to date)';
       }
     }
     console.log(`  ${marker.padEnd(7)} ${result.relativePath}${note}`);
@@ -581,36 +596,29 @@ export function runInstallAgentGates(args) {
   if (args.codexHome) {
     const dir = codexSkillsDir();
     console.log('');
-    console.log(`Codex home skills (${dir}/<name>/SKILL.md):`);
+    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({ status: 'failed' });
+      homeResults.push({ relativePath: dir, status: 'failed' });
     }
     if (homeResults.length === 0) {
-      for (const [name, content] of skills) {
-        const skillDir = path.join(dir, name);
-        const file = path.join(skillDir, 'SKILL.md');
-        if (fs.existsSync(file) && !args.force) {
-          const installed = installedSkillVersion(file);
-          const behind = installed === null || (version && isVersionOlder(installed, version));
-          const note = behind
-            ? `  (stale: ${installed ?? 'no stamp'} < ${version}; use --force)`
-            : '  (up to date)';
-          console.log(`  ${'skipped'.padEnd(7)} ${name}/SKILL.md${note}`);
-          homeResults.push({ status: 'skipped' });
-          continue;
-        }
-        try {
-          fs.mkdirSync(skillDir, { recursive: true });
-          fs.writeFileSync(file, content);
-          console.log(`  ${'wrote'.padEnd(7)} ${name}/SKILL.md`);
-          homeResults.push({ status: 'written' });
-        } catch (error) {
-          console.log(`  ${'FAILED'.padEnd(7)} ${name}/SKILL.md (${error.message})`);
-          homeResults.push({ status: 'failed' });
-        }
+      for (const result of installSkillCatalog({
+        directory: dir,
+        skills,
+        packageVersion: version,
+        force: args.force,
+        scope: 'home',
+      })) {
+        console.log(skillInstallLine(result));
+        homeResults.push(result);
       }
     }
   }
@@ -643,26 +651,28 @@ export function runInstallAgentGates(args) {
       const verb = codexMcp.status === 'updated' ? 'updated' : 'wrote';
       console.log(`  ${verb.padEnd(7)} [mcp_servers.ark] with absolute paths`);
       console.log('          RESTART Codex — it does not hot-load MCP servers.');
-      console.log('          Then expect: resource ark://manifest + tools validate_code, ark_check, ark_coverage, ark_place.');
+      console.log(
+        '          Then expect: tools ark_identity, ark_manifest, validate_code, ark_check, ark_coverage, ark_place.'
+      );
     }
   } else if (skipHomeWire) {
     codexMcp = { status: 'skipped', file: codexConfigPath(), reason: 'temp-root' };
   }
 
-  // Repo templates + explicit --codex-home skill writes are hard failures.
-  // Home MCP wire is best-effort: unreadable ~/.codex (sandbox, permissions) must not
-  // mark an otherwise successful repo gate install as failed.
-  const hardFailed = [...results, ...homeResults].filter((result) => result.status === 'failed');
-  if (hardFailed.length > 0) {
-    console.error(`\nFailed to write ${hardFailed.length} template(s).`);
+  const { codexProjectConfigured, runtimeActivation } =
+    inspectCodexInstallActivation(root, tools.has('codex') && !args.skillsOnly);
+  if (reportPartialInstall({
+    root,
+    tools,
+    results,
+    homeResults,
+    earlyWritten,
+    codexMcp,
+    runtimeActivation,
+  })) {
     process.exitCode = 1;
     return;
   }
-  if (codexMcp?.status === 'failed') {
-    console.error(
-      `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --codex-home --force.`
-    );
-  }
   if (writeRequest.host) {
     if (!hasHardWriteHook(root, writeRequest.host)) {
       console.error(`\nFailed to verify the ${writeRequest.host} hard-write hook after install.`);
@@ -731,8 +741,14 @@ export function runInstallAgentGates(args) {
   }
   if ((tools.has('codex') || args.codexHome)) {
     console.log('');
+    if (tools.has('codex') && !args.skillsOnly) {
+      printCodexActivationHandoff(root, codexProjectConfigured, runtimeActivation);
+    }
     if (codexMcp && codexMcp.status !== 'failed') {
-      console.log(`  Codex: ark MCP registered in ${codexMcp.file} — restart Codex so \`ark://manifest\` loads.`);
+      console.log(
+        `  Codex: ark MCP registered in ${codexMcp.file} — restart Codex, then bind with ` +
+          '`ark_identity` and read the contract with `ark_manifest`.'
+      );
     }
     if (tools.has('codex') && !args.compact) {
       console.log('  Codex write path (honest):');