archgen-skill 0.0.5 → 0.0.7

package/lib/doctor.js

@@ -3,13 +3,13 @@
 // Verifies a project install: canonical store integrity, version stamp,
 // claude link resolution, managed blocks (exactly once each), and manifest
 // entry resolution. Safe issues are repaired in place unless --check is given
-// (report-only). Advisory FAIL rows (broken states only a human can fix) are
-// reported and counted in the summary but do NOT fail the run: the process
-// exits non-zero only when a repair operation itself throws.
+// (report-only). A FAIL row is a broken state a human must fix: it is
+// reported AND it fails the run (the process exits non-zero whenever any
+// FAIL row was produced).
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { globalTargets } from './install.js';
 import {
   END,
@@ -22,9 +22,10 @@ import {
   upsertManagedFile,
 } from './block.js';
 import { resolveSkillSource } from './init.js';
-import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, hashDir, loadManifest, pruneDevOnly, saveManifest } from './store.js';
+import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, assertNotSymlink, assertWithinRoot, cliVersion, findObsolete, hashDir, loadManifest, pruneDevOnly, pruneObsolete, saveManifest } from './store.js';
 import { compareSemver, parseSemver } from './version.js';
 import { readStamp, writeStamp } from './version-stamp.js';
+import { mcpDoctor } from './mcp-server.js';
 
 function lstatSafe(p) {
   try { return lstatSync(p); } catch { return null; }
@@ -47,8 +48,7 @@ function relJoin(rel) {
  *   mutations; home overrides the homedir scanned for global installs (tests)
  * @returns {{root: string, checks: {status: 'OK'|'FIXED'|'WOULD-FIX'|'WARN'|'FAIL', msg: string}[],
  *            tally: Record<string, number>, failures: number}} `failures` counts
- *   repair operations that THEMSELVES threw — advisory FAIL rows are reported
- *   but never fail the run.
+ *   the FAIL rows — a broken state a human must fix always fails the run.
  */
 export function doctorProject(projectDir, packageRoot, opts = {}) {
   const root = resolve(projectDir);
@@ -56,16 +56,20 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   const homeDir = opts.home ?? homedir();
   const version = cliVersion(packageRoot);
   const checks = [];
-  const add = (status, msg) => checks.push({ status, msg });
-  let opFailures = 0;
+  let failures = 0;
+  // A FAIL row is a broken state a human must fix, so it MUST fail the run:
+  // the counter below is what the CLI turns into a non-zero exit code.
+  const add = (status, msg) => {
+    checks.push({ status, msg });
+    if (status === 'FAIL') failures++;
+  };
   // Run one repair step; a throw becomes a FAIL row instead of aborting the
-  // whole doctor pass (and is the only thing that flips the exit code).
+  // whole doctor pass.
   const attempt = (fn, okStatus, okMsg, failLabel) => {
     try {
       fn();
       add(okStatus, okMsg);
     } catch (e) {
-      opFailures++;
       add('FAIL', `${failLabel}: ${e.message} - fix manually`);
     }
   };
@@ -83,7 +87,39 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!existsSync(join(storeAbs, 'SKILL.md'))) {
     add('FAIL', 'store .agents/skills/archgen missing or incomplete - run `archgen init`');
   } else {
-    const missingCore = ['scripts', 'references'].filter((d) => !existsSync(join(storeAbs, d)));
+    // MIGRATION: the skill no longer ships code. An install carried over from
+    // the pre-MCP layout still has a scripts/ tree — dead weight that would
+    // otherwise read as "diverges from packaged skill (customized?)".
+    // Pruned BEFORE the divergence check so an upgrade is not misreported.
+    const packaged = (() => {
+      try { return resolveSkillSource(packageRoot); } catch { return null; }
+    })();
+    if (packaged) {
+      // --check reports WITHOUT mutating; repair mode prunes.
+      const obsolete = findObsolete(storeAbs, packaged);
+      if (obsolete.length > 0) {
+        if (checkOnly) {
+          for (const rel of obsolete) {
+            add('WOULD-FIX', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> would prune`);
+          }
+        } else {
+          // Pruning DELETES inside the store: refuse when the store (or one of
+          // its parents) is a symlink — the prune would otherwise reach
+          // outside the project through the link.
+          try {
+            assertNotSymlink(storeAbs);
+            assertWithinRoot(root, storeAbs);
+            pruneObsolete(storeAbs, packaged);
+            for (const rel of obsolete) {
+              add('FIXED', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> pruned`);
+            }
+          } catch (e) {
+            add('FAIL', `cannot prune the obsolete store tree: ${e.message} - fix manually`);
+          }
+        }
+      }
+    }
+    const missingCore = ['references'].filter((d) => !existsSync(join(storeAbs, d)));
     if (missingCore.length > 0) {
       // Deferred so the managed-block FAIL rows below stay FIRST: existing
       // consumers read checks.find(FAIL) expecting the marker verdict.
@@ -109,7 +145,12 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       if (checkOnly) {
         add('WOULD-FIX', `store carries dev-only ${devOnlyPresent.join(', ')} -> pruned`);
       } else {
-        attempt(() => pruneDevOnly(storeAbs), 'FIXED',
+        // Same rule as the obsolete prune: never delete through a symlink.
+        attempt(() => {
+          assertNotSymlink(storeAbs);
+          assertWithinRoot(root, storeAbs);
+          pruneDevOnly(storeAbs);
+        }, 'FIXED',
           `dev-only ${devOnlyPresent.join(', ')} pruned from store`, 'cannot prune dev-only artifacts');
       }
     }
@@ -137,6 +178,10 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
       return;
     }
     try {
+      // Escape check FIRST, exactly as init does: a symlinked .claude/
+      // .claude/skills parent must not redirect the recreated link outside
+      // the project root.
+      assertWithinRoot(root, dirname(claudeAbs));
       try { unlinkSync(claudeAbs); } catch { /* absent */ }
       mkdirSync(dirname(claudeAbs), { recursive: true });
       symlinkSync('../../.agents/skills/archgen', claudeAbs);
@@ -169,60 +214,66 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
         'AGENTS.md created with managed block', 'cannot create AGENTS.md managed block');
     }
   } else {
-    let raw = readFileSync(agentsAbs, 'utf8');
-    const starts = countOccurrences(raw, START);
-    const ends = countOccurrences(raw, END);
-    if (starts === 0 && ends === 0) {
-      if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
-      else {
-        attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
-          'AGENTS.md managed block added', 'cannot add AGENTS.md managed block');
-      }
-    } else if (starts > 1 || ends > 1) {
-      add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
-    } else if (starts === 0 || ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
-      // Orphan/inverted markers: repairing through upsertBlock would throw, so
-      // classify as FAIL instead of attempting the write.
-      add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
-    } else {
-      // Block-format currency: an unversioned or older-stamped managed block is
-      // upgraded in place through the normal upsert path (everything outside the
-      // markers survives byte-for-byte by design). Newer stamps are left alone.
-      const det = detectBlockVersion(raw);
-      const parsed = det.version ? parseSemver(det.version) : null;
-      const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
-      if (stale) {
-        const from = det.version ? 'v' + det.version : 'unversioned';
-        if (checkOnly) {
-          add('WOULD-FIX', `WOULD-UPGRADE: AGENTS.md block ${from} -> v${version}`);
-        } else {
-          let upgraded = false;
-          attempt(() => { upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')); upgraded = true; },
-            'FIXED', `UPGRADED: AGENTS.md block ${from} -> v${version}`, 'cannot upgrade AGENTS.md block');
-          if (upgraded) raw = readFileSync(agentsAbs, 'utf8');
-        }
-      }
-      const fsCount = countOccurrences(raw, FEATURES_START);
-      const feCount = countOccurrences(raw, FEATURES_END);
-      const fsIdx = raw.indexOf(FEATURES_START);
-      const feIdx = raw.indexOf(FEATURES_END);
-      if (fsCount === 1 && feCount === 1 && fsIdx < feIdx) {
-        add('OK', 'AGENTS.md block + features registry present');
-      } else if (fsCount === 1 && feCount === 1) {
-        // Counts are right but ORDER is inverted (end before start): any
-        // registry write would throw (upsertFeaturesRegistry requires
-        // end > start), so flag the state instead of blessing it as OK.
-        if (checkOnly) add('WOULD-FIX', 'AGENTS.md archgen:features markers are reversed -> swap them');
-        else add('FAIL', 'AGENTS.md archgen:features markers are reversed - fix manually');
-      } else if (fsCount === 0 && feCount === 0) {
-        if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+    // An unreadable managed file is a FAIL row, not a reason to abort the
+    // whole doctor pass.
+    try {
+      let raw = readFileSync(agentsAbs, 'utf8');
+      const starts = countOccurrences(raw, START);
+      const ends = countOccurrences(raw, END);
+      if (starts === 0 && ends === 0) {
+        if (checkOnly) add('WOULD-FIX', 'AGENTS.md has no archgen block -> added');
         else {
-          attempt(() => upsertFeaturesRegistry(agentsAbs, []), 'FIXED',
-            'AGENTS.md features registry inserted', 'cannot insert AGENTS.md features registry');
+          attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
+            'AGENTS.md managed block added', 'cannot add AGENTS.md managed block');
         }
+      } else if (starts > 1 || ends > 1) {
+        add('FAIL', `AGENTS.md has ${starts} start / ${ends} end markers - fix manually`);
+      } else if (starts === 0 || ends === 0 || raw.indexOf(START) > raw.indexOf(END)) {
+        // Orphan/inverted markers: repairing through upsertBlock would throw, so
+        // classify as FAIL instead of attempting the write.
+        add('FAIL', 'AGENTS.md has broken archgen markers - fix manually');
       } else {
-        add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+        // Block-format currency: an unversioned or older-stamped managed block is
+        // upgraded in place through the normal upsert path (everything outside the
+        // markers survives byte-for-byte by design). Newer stamps are left alone.
+        const det = detectBlockVersion(raw);
+        const parsed = det.version ? parseSemver(det.version) : null;
+        const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
+        if (stale) {
+          const from = det.version ? 'v' + det.version : 'unversioned';
+          if (checkOnly) {
+            add('WOULD-FIX', `WOULD-UPGRADE: AGENTS.md block ${from} -> v${version}`);
+          } else {
+            let upgraded = false;
+            attempt(() => { upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')); upgraded = true; },
+              'FIXED', `UPGRADED: AGENTS.md block ${from} -> v${version}`, 'cannot upgrade AGENTS.md block');
+            if (upgraded) raw = readFileSync(agentsAbs, 'utf8');
+          }
+        }
+        const fsCount = countOccurrences(raw, FEATURES_START);
+        const feCount = countOccurrences(raw, FEATURES_END);
+        const fsIdx = raw.indexOf(FEATURES_START);
+        const feIdx = raw.indexOf(FEATURES_END);
+        if (fsCount === 1 && feCount === 1 && fsIdx < feIdx) {
+          add('OK', 'AGENTS.md block + features registry present');
+        } else if (fsCount === 1 && feCount === 1) {
+          // Counts are right but ORDER is inverted (end before start): any
+          // registry write would throw (upsertFeaturesRegistry requires
+          // end > start), so flag the state instead of blessing it as OK.
+          if (checkOnly) add('WOULD-FIX', 'AGENTS.md archgen:features markers are reversed -> swap them');
+          else add('FAIL', 'AGENTS.md archgen:features markers are reversed - fix manually');
+        } else if (fsCount === 0 && feCount === 0) {
+          if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing features registry -> inserted');
+          else {
+            attempt(() => upsertFeaturesRegistry(agentsAbs, []), 'FIXED',
+              'AGENTS.md features registry inserted', 'cannot insert AGENTS.md features registry');
+          }
+        } else {
+          add('FAIL', 'AGENTS.md has broken archgen:features markers - fix manually');
+        }
       }
+    } catch (e) {
+      add('FAIL', 'cannot read AGENTS.md: ' + e.message + ' - fix manually');
     }
   }
 
@@ -234,18 +285,44 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
         'CLAUDE.md created with @AGENTS.md bridge', 'cannot create CLAUDE.md bridge');
     }
   } else {
-    const raw = readFileSync(claudeMdAbs, 'utf8');
-    const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
-    const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
-    const starts = countOccurrences(raw, START);
-    const ends = countOccurrences(raw, END);
-    if (imports && starts <= 1 && ends <= 1) add('OK', 'CLAUDE.md bridges to AGENTS.md');
-    else if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
-    else if (starts !== ends) add('FAIL', 'CLAUDE.md has broken archgen markers - fix manually');
-    else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
-    else {
-      attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
-        'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
+    // An unreadable managed file is a FAIL row, not a reason to abort the
+    // whole doctor pass.
+    let raw = null;
+    try {
+      raw = readFileSync(claudeMdAbs, 'utf8');
+    } catch (e) {
+      add('FAIL', 'cannot read CLAUDE.md: ' + e.message + ' - fix manually');
+    }
+    if (raw !== null) {
+      const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+      const imports = body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
+      const starts = countOccurrences(raw, START);
+      const ends = countOccurrences(raw, END);
+      if (starts > 1 || ends > 1) add('FAIL', 'CLAUDE.md has multiple archgen blocks - fix manually');
+      else if (starts !== ends) add('FAIL', 'CLAUDE.md has broken archgen markers - fix manually');
+      else if (starts === 1) {
+        // The managed block is ours: keep its provenance stamp current, the
+        // same way the AGENTS.md block is kept current.
+        const det = detectBlockVersion(raw);
+        const parsed = det.version ? parseSemver(det.version) : null;
+        const stale = !det.present || !parsed || compareSemver(det.version, version) < 0;
+        if (stale) {
+          const from = det.version ? 'v' + det.version : 'unversioned';
+          if (checkOnly) {
+            add('WOULD-FIX', `WOULD-UPGRADE: CLAUDE.md block ${from} -> v${version}`);
+          } else {
+            attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+              `UPGRADED: CLAUDE.md block ${from} -> v${version}`, 'cannot upgrade CLAUDE.md block');
+          }
+        } else {
+          add('OK', 'CLAUDE.md bridges to AGENTS.md');
+        }
+      } else if (imports) add('OK', 'CLAUDE.md bridges to AGENTS.md');
+      else if (checkOnly) add('WOULD-FIX', 'CLAUDE.md missing @AGENTS.md bridge -> written');
+      else {
+        attempt(() => upsertManagedFile(claudeMdAbs, [START, '@AGENTS.md', END]), 'FIXED',
+          'CLAUDE.md @AGENTS.md bridge written', 'cannot write CLAUDE.md bridge');
+      }
     }
   }
 
@@ -256,8 +333,23 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!manifest) {
     if (existsSync(storeAbs)) add('WARN', `no install manifest at ${MANIFEST_REL} (re-run init to regenerate)`);
     else add('OK', 'no manifest (nothing installed)');
+  } else if (!Array.isArray(manifest.entries)) {
+    // A manifest without an entries array is malformed: report it instead of
+    // crashing the whole doctor pass on it.
+    add('FAIL', `manifest ${MANIFEST_REL} has no entries array - fix manually`);
   } else {
-    const resolves = (e) => e && typeof e.path === 'string' && existsSync(join(root, ...e.path.split('/')));
+    // An entry only "resolves" when its path stays inside the project root:
+    // a manifest path like `../../etc/passwd` must never count as resolved.
+    const entryAbs = (rel) => {
+      if (typeof rel !== 'string' || rel === '') return null;
+      const abs = resolve(root, ...rel.split('/'));
+      if (abs !== root && !abs.startsWith(root + sep)) return null;
+      return abs;
+    };
+    const resolves = (e) => {
+      const abs = entryAbs(e && e.path);
+      return abs !== null && existsSync(abs);
+    };
     const stale = manifest.entries.filter((e) => !resolves(e));
     if (stale.length === 0) {
       add('OK', `manifest: all ${manifest.entries.length} entr${manifest.entries.length === 1 ? 'y' : 'ies'} resolve`);
@@ -296,7 +388,35 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     add(v ? 'OK' : 'WARN', `skill ${p}: ${slot}`);
   }
 
+  // 8. MCP server wiring — the archgen MCP server is what actually gives the
+  //    agent its tools. A skill with no MCP entry is a skill the agent cannot
+  //    use, so this is a first-class check, not a footnote.
+  //
+  // READ-ONLY and NEVER FATAL: doctor must work on a machine with no npm, no
+  // network, and no MCP server installed. The MCP server is asked for its own
+  // report; if it cannot run, that is a WARN with the remediation command.
+  const mcp = mcpDoctor({ projectRoot: root, env: { ...process.env, HOME: homeDir } });
+  if (!mcp.report) {
+    add('WARN', `archgen MCP server not reachable${mcp.detail ? ` — ${mcp.detail}` : ''} — install with: npx archgen-mcp bootstrap --project . --yes`);
+  } else {
+    const rep = mcp.report;
+    add(
+      rep.skill ? 'OK' : 'WARN',
+      rep.skill
+        ? `archgen MCP server v${rep.server} ready (skill ${rep.skill.version ?? 'unknown'})`
+        : 'archgen MCP server ready, but no skill was found',
+    );
+    const wired = (rep.mcpTargets ?? []).filter((t) => t.exists).length;
+    if (wired === 0) {
+      add('WARN', 'archgen MCP is not wired into any harness config — run: npx archgen-mcp bootstrap --project . --yes');
+    } else {
+      add('OK', `archgen MCP wiring present in ${wired} harness config(s)`);
+    }
+    if (rep.codegraph) add('OK', `codegraph ${rep.codegraph.version}`);
+    else add('WARN', 'codegraph not installed — run: npx archgen-mcp bootstrap --project . --yes');
+  }
+
   const tally = { OK: 0, FIXED: 0, 'WOULD-FIX': 0, WARN: 0, FAIL: 0 };
   for (const c of checks) tally[c.status]++;
-  return { root, checks, tally, failures: opFailures };
+  return { root, checks, tally, failures };
 }

package/lib/init.js

@@ -17,12 +17,13 @@
 //   to a symlink; a customized one is left untouched with a warning;
 // - installs are atomic: built in a temp sibling dir, then renamed.
 
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
-import { importsAgents, renderBlock, START, END, upsertManagedFile } from './block.js';
+import { importsAgents, hasManagedBlock, renderBlock, START, END, upsertManagedFile } from './block.js';
 import { CLAUDE_LINK_REL, STORE_REL, VERSION_FILE, appendEntry, assertNotSymlink, assertWithinRoot, cliVersion, hashDir, moveToBackup, pruneDevOnly } from './store.js';
 import { writeStamp } from './version-stamp.js';
+import { bootstrapServers } from './bootstrap.js';
 
 const CONTEXT_FILES = ['AGENTS.md', 'CLAUDE.md'];
 
@@ -56,6 +57,12 @@ function relJoin(rel) {
 function installClaudeAdapter(root, source, warnings) {
   const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
   const storeAbs = join(root, relJoin(STORE_REL));
+
+  // Escape check FIRST — before anything is removed or created: a symlinked
+  // .claude/.claude/skills parent must not redirect the adapter (nor the
+  // removal of a legacy copy) outside the project root.
+  assertWithinRoot(root, dirname(claudeAbs));
+
   const st = lstatSafe(claudeAbs);
   let migrating = false;
 
@@ -80,9 +87,6 @@ function installClaudeAdapter(root, source, warnings) {
     return 'kept-divergent';
   }
 
-  // Escape check: a symlinked .claude/.claude/skills parent must not redirect
-  // the adapter creation outside the project root.
-  assertWithinRoot(root, claudeAbs);
   try {
     mkdirSync(dirname(claudeAbs), { recursive: true });
     symlinkSync('../../.agents/skills/archgen', claudeAbs);
@@ -99,8 +103,11 @@ function installClaudeAdapter(root, source, warnings) {
  * claude adapter, and write context pointers.
  * @param {string} projectDir target repo root
  * @param {string} packageRoot dir containing this CLI package
- * @param {{force?: boolean}} opts --force proceeds automatically; divergent
- *   copies are always auto-backed-up (never refused, never destroyed)
+ * @param {{force?: boolean, codegraph?: boolean, mcp?: boolean, log?: (s: string) => void, env?: NodeJS.ProcessEnv}} opts
+ *   --force proceeds automatically; divergent copies are always auto-backed-up
+ *   (never refused, never destroyed). opts.codegraph === false opts OUT of the
+ *   automatic CodeGraph bootstrap (install + MCP wiring + index build);
+ *   opts.mcp === false opts OUT of the archgen MCP wiring.
  * @returns {{storePath: string, claudeLink: 'created'|'existing'|'migrated'|'skipped'|'kept-divergent',
  *            backups: string[], contextFiles: string[], createdContextFiles: string[], warnings: string[]}}
  */
@@ -110,6 +117,9 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   // both plain and --force runs take the same safe path.
   const force = opts.force === true;
   void force;
+  const codegraphAllowed = opts.codegraph !== false;
+  const mcpAllowed = opts.mcp !== false;
+  const log = opts.log ?? console.log;
 
   const root = resolve(projectDir);
   const source = resolveSkillSource(packageRoot);
@@ -127,21 +137,44 @@ export function initProject(projectDir, packageRoot, opts = {}) {
 
   // 1. Canonical store — fingerprint before mutating (ownership check).
   const prev = lstatSafe(storeAbs);
-  if (prev) {
-    const identical = prev.isDirectory() && !prev.isSymbolicLink()
-      && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source);
-    if (!identical) backups.push(moveToBackup(root, STORE_REL));
-  }
+  const identical = !!(prev && prev.isDirectory() && !prev.isSymbolicLink()
+    && hashDir(storeAbs, { ignore: [VERSION_FILE] }) === hashDir(source));
 
-  // Atomic install: build in a temp sibling dir, then rename into place.
+  // Atomic install: build in a temp sibling dir, then swap it into place.
+  // The current store is renamed aside (identical) or moved into the backup
+  // vault (divergent) so the swap can be undone: a failed swap puts the old
+  // store back, and a failed copy never leaves an orphan temp directory.
   const skillsParent = dirname(storeAbs);
   mkdirSync(skillsParent, { recursive: true });
   const tmp = join(skillsParent, '.archgen-tmp-' + randomBytes(6).toString('hex'));
-  cpSync(source, tmp, { recursive: true });
-  pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
-  writeStamp(tmp, version);
-  rmSync(storeAbs, { recursive: true, force: true });
-  renameSync(tmp, storeAbs);
+  const aside = join(skillsParent, '.archgen-old-' + randomBytes(6).toString('hex'));
+  let asideUsed = false;
+  try {
+    cpSync(source, tmp, { recursive: true });
+    pruneDevOnly(tmp); // dev-only artifacts (scripts/test) never reach the installed store
+    writeStamp(tmp, version);
+    if (lstatSafe(storeAbs)) {
+      if (identical) {
+        renameSync(storeAbs, aside);
+        asideUsed = true;
+      } else {
+        backups.push(moveToBackup(root, STORE_REL));
+      }
+    }
+    renameSync(tmp, storeAbs);
+  } catch (e) {
+    if (asideUsed) {
+      // Put the previous store back: a failed swap must never leave the
+      // project without a store.
+      try {
+        renameSync(aside, storeAbs);
+        asideUsed = false;
+      } catch { /* keep it aside rather than deleting the user's data */ }
+    }
+    rmSync(tmp, { recursive: true, force: true });
+    throw e;
+  }
+  if (asideUsed) rmSync(aside, { recursive: true, force: true });
   appendEntry(root, 'dir', STORE_REL);
 
   // 2. Claude adapter — relative symlink, never a second copy.
@@ -152,7 +185,10 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   const createdContextFiles = [];
   for (const name of CONTEXT_FILES) {
     const abs = join(root, name);
-    if (name === 'CLAUDE.md' && importsAgents(abs)) {
+    // A hand-written `@AGENTS.md` import is the user's — leave it alone. A
+    // managed block is ours: refresh it so its provenance stamp tracks the
+    // running CLI instead of freezing at the first-ever install.
+    if (name === 'CLAUDE.md' && !hasManagedBlock(abs) && importsAgents(abs)) {
       warnings.push('CLAUDE.md already imports @AGENTS.md - skipped (already-imports)');
       continue;
     }
@@ -165,5 +201,27 @@ export function initProject(projectDir, packageRoot, opts = {}) {
     appendEntry(root, 'block', name);
   }
 
+  // 4. Server bootstrap — wire the archgen MCP server into every detected
+  //    harness AND ensure CodeGraph (its CLI, its MCP entry, the project
+  //    index). Non-fatal by design: an offline machine still gets the skill
+  //    installed.
+  if (codegraphAllowed || mcpAllowed) {
+    const r = bootstrapServers({
+      projectDir: root,
+      location: 'both',
+      log,
+      env: opts.env,
+      noCodegraph: !codegraphAllowed,
+      noMcp: !mcpAllowed,
+    });
+    if (!r.ok) {
+      warnings.push(`server bootstrap incomplete${r.detail ? ': ' + r.detail : ''} — install later with: npx archgen-mcp bootstrap --project . --yes`);
+    } else if (r.skipped) {
+      warnings.push(`server bootstrap skipped (${r.skipped})`);
+    }
+  } else {
+    warnings.push('server bootstrap skipped (--no-codegraph --no-mcp)');
+  }
+
   return { storePath: storeAbs, claudeLink, backups, contextFiles, createdContextFiles, warnings };
 }

package/lib/install.js

@@ -10,6 +10,7 @@ import { resolveSkillSource } from './init.js';
 import { assertNotSymlink, assertWithinRoot, cliVersion, hashDir, moveToBackupInto, pruneDevOnly, refuseSymlinkMessage } from './store.js';
 import { writeStamp } from './version-stamp.js';
 import { loadConfig } from './config.js';
+import { bootstrapServers } from './bootstrap.js';
 
 // Module-anchored default: works from the npm package (cli/lib -> cli/vendor)
 // AND from a monorepo checkout (packages/cli/lib -> ../../skill) without depending on cwd.
@@ -58,7 +59,7 @@ function nextBackupTs(tdir) {
 }
 
 /**
- * @param {{copy?: boolean, home?: string, packageRoot?: string}} opts
+ * @param {{copy?: boolean, home?: string, packageRoot?: string, codegraph?: boolean, mcp?: boolean, log?: (s: string) => void, env?: NodeJS.ProcessEnv}} opts
  * @returns {{rows: Array<[string, string, string]>, failures: number, manifest: string,
  *            backups: string[]}} rows are [STATUS, MODE, PATH]; `backups` lists
  *            absolute vault locations written by this run.
@@ -165,6 +166,24 @@ export function installGlobal(opts = {}) {
       rows.push(['FAILED', '-', dest + ' (' + e.message + ')']);
     }
   }
+  // Server bootstrap — GLOBAL wiring only (project-local configs belong to
+  // `init`). Wires the archgen MCP server and CodeGraph into every DETECTED
+  // global harness. Non-fatal: an offline machine still gets the skill
+  // installed.
+  if (opts.codegraph !== false || opts.mcp !== false) {
+    const r = bootstrapServers({
+      projectDir: process.cwd(),
+      location: 'global',
+      log: opts.log ?? console.log,
+      env: opts.env,
+      noCodegraph: opts.codegraph === false,
+      noMcp: opts.mcp === false,
+    });
+    if (!r.ok) {
+      rows.push(['WARN', '-', 'server bootstrap incomplete' + (r.detail ? ` (${r.detail})` : '') + ' — run: npx archgen-mcp bootstrap --location global --yes']);
+    }
+  }
+
   return { rows, failures, manifest, backups };
 }
 
@@ -177,17 +196,70 @@ function stampNote(rows, dest, write) {
   }
 }
 
-export function uninstallGlobal(home = homedir()) {
+/**
+ * The exact destinations a global install may create.
+ *
+ * A manifest entry is acted on ONLY when it names one of them. A plain
+ * suffix test (`endsWith('skills/archgen')`) would let any path with that
+ * ending be removed — including paths outside the known harness dirs.
+ */
+function allowedGlobalDestinations(home) {
+  const set = new Set(globalTargets(home).map((d) => resolve(join(d, 'archgen'))));
+  set.add(resolve(join(process.cwd(), '.github', 'skills', 'archgen')));
+  return set;
+}
+
+/**
+ * Move an edited copy-mode install into the global backup vault before it is
+ * removed: the uninstall must never be the last place those edits exist.
+ * An install that still matches the packaged skill needs no backup.
+ */
+function backupEditedCopy(dest, packageRoot, backups) {
+  let identical = false;
+  try {
+    identical = hashDir(dest) === hashDir(resolveSkillSource(packageRoot));
+  } catch {
+    identical = false; // unverifiable -> preserve it
+  }
+  if (identical) return;
+  const tdir = dirname(dest);
+  const loc = moveToBackupInto(tdir, 'archgen', GLOBAL_BACKUP_REL, nextBackupTs(tdir));
+  backups.push(join(tdir, ...loc.split('/')));
+}
+
+/**
+ * Remove the globally-installed copies recorded in the manifest.
+ *
+ * Only entries that name a known harness destination are removed. An entry
+ * that cannot be verified is SKIPPED and KEPT in the manifest — the manifest
+ * is only removed when nothing was left behind.
+ *
+ * @param {string} home home directory holding the manifest
+ * @param {{packageRoot?: string}} opts
+ */
+export function uninstallGlobal(home = homedir(), opts = {}) {
   const manifest = join(home, MANIFEST_NAME);
   if (!existsSync(manifest)) return { removed: 0, failed: 0, noop: true };
+  const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+  const allowed = allowedGlobalDestinations(home);
   let removed = 0, failed = 0;
+  const kept = [];
+  const backups = [];
   for (const line of readFileSync(manifest, 'utf8').split('\n')) {
     if (!line.trim()) continue;
     const [kind, p] = line.split('\t');
-    if (!p || !p.endsWith(join('skills', 'archgen'))) { failed++; continue; } // safety guard
-    try { rmSync(p, { force: true, recursive: true }); removed++; }
-    catch { failed++; }
+    if (!p || !allowed.has(resolve(p))) { failed++; kept.push(line); continue; } // safety guard
+    try {
+      if (kind === 'copy') backupEditedCopy(p, packageRoot, backups);
+      rmSync(p, { force: true, recursive: true }); removed++;
+    } catch { failed++; kept.push(line); }
+  }
+  if (kept.length === 0) {
+    try { rmSync(manifest, { force: true }); } catch { failed++; }
+  } else {
+    // The skipped entries stay recorded: the manifest is the only thing that
+    // knows they were never removed.
+    try { writeFileSync(manifest, kept.join('\n') + '\n'); } catch { failed++; }
   }
-  rmSync(manifest, { force: true });
-  return { removed, failed, noop: false };
+  return { removed, failed, noop: false, backups };
 }