archgen-skill 0.0.4 → 0.0.6

package/README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/akashmaurya99/archgen/actions/workflows/ci.yml/badge.svg)](https://github.com/akashmaurya99/archgen/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/akashmaurya99/archgen/blob/main/LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
 Describe what you want to build. archgen interviews you (or surveys your existing
 codebase), produces an architecture contract plus a dependency-ordered task graph,
@@ -32,15 +32,15 @@ What `init` writes (nothing is ever duplicated):
 
 | Path | What |
 | --- | --- |
-| `.agents/skills/archgen/` | **The only real copy** — the agentskills.io standard location read natively by OpenCode, Cursor, Codex, Gemini CLI, Copilot and Antigravity |
-| `.claude/skills/archgen → ../../.agents/skills/archgen` | Relative symlink for Claude Code (the one harness needing it). Skipped gracefully where symlinks need privileges — Claude still works via the bridge below |
-| `AGENTS.md` | Managed hub block: skill pointer + quick triggers + a features registry that stays current as you add features |
-| `CLAUDE.md` | One-line bridge: `@AGENTS.md` (existing files keep all their content; if it already imports AGENTS.md we write nothing) |
+| `.agents/skills/archgen/` | **The only real copy** — the agentskills.io standard location, read natively by OpenCode, Cursor, Codex, Gemini CLI, Copilot, and Antigravity |
+| `.claude/skills/archgen → ../../.agents/skills/archgen` | Relative symlink for Claude Code (the one harness that needs it); skipped gracefully where symlinks require privileges |
+| `AGENTS.md` | Managed hub block: skill pointer, quick triggers, and a features registry that stays current as you add features |
+| `CLAUDE.md` | One-line bridge: `@AGENTS.md` (existing content is preserved; nothing is written if it already imports AGENTS.md) |
 
-Existing projects with user content are safe: managed blocks upsert between
-markers, modified skill copies are backed up to `.archgen/.backup/<timestamp>/`
-before refresh, and legacy dual-copy layouts are migrated to symlinks
-automatically. Verify anytime with `archgen-skill doctor`.
+Existing projects are safe: managed blocks upsert between markers, modified skill
+copies are backed up to `.archgen/.backup/<timestamp>/` before refresh, and legacy
+dual-copy layouts are migrated to symlinks automatically. Verify anytime with
+`archgen-skill doctor`.
 
 **Or install globally** into every detected harness:
 
@@ -49,12 +49,18 @@ npx archgen-skill install          # symlinks; --copy for real copies
 ```
 
 Prefer shell? Clone the repo and run `./install.sh` (same behavior, plus
-`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 18.
-The skill itself has zero npm dependencies.
+`--init`, `--project`, `--uninstall`). Requires Node.js ≥ 20 — the official MCP
+SDK v2 floor.
+
+**What `init` actually does:** installs the skill (guidance only — no code),
+wires the `archgen-mcp` MCP server into every detected harness, and ensures
+CodeGraph (its CLI, its MCP entry, and the project index). The CLI itself is
+zero-dependency; the MCP server it installs depends on the official MCP SDK.
 
 ## Quick start
 
-After `npx archgen-skill init`, open your project in any supported agent and talk naturally:
+After `npx archgen-skill init`, open your project in any supported agent and talk
+naturally:
 
 | You say | What runs |
 | --- | --- |
@@ -64,39 +70,33 @@ After `npx archgen-skill init`, open your project in any supported agent and tal
 | *"roll back the auth changes"* | Impact analysis → reverse-order revert plan → approval |
 
 Everything archgen produces lives in one reviewable `.archgen/<slug>/` folder —
-architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — versioned by git.
+architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — versioned
+by git.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `npx archgen-skill init [dir]` | Install the single canonical skill store at `.agents/skills/archgen`, add the Claude symlink adapter, write the AGENTS.md hub + CLAUDE.md `@AGENTS.md` bridge |
+| `npx archgen-skill init [dir]` | Prepare a project: canonical skill store at `.agents/skills/archgen`, Claude symlink adapter, AGENTS.md hub + CLAUDE.md bridge |
 | `npx archgen-skill install [--copy]` | Install into global harness skill dirs (symlinks by default, real copies with `--copy`) |
 | `npx archgen-skill uninstall` | Remove globally-installed copies (manifest-recorded, safe removal) |
-| `npx archgen-skill uninstall --project [dir]` | Remove project install: strips managed blocks, our symlink and the store **only if unmodified** — feature folders in `.archgen/` and all user content are preserved |
-| `npx archgen-skill doctor [dir] [--check]` | Verify + auto-repair an installation: store integrity, version stamp, Claude link, blocks present exactly once, manifest resolution (`--check` reports without fixing) |
-| `npx archgen-skill --help` | Help |
-
-### Version stamp (`.archgen-version`)
-
-Every skill tree the CLI writes carries a one-line `MAJOR.MINOR.PATCH\n` stamp
-at its root — the canonical store from `init`, each `install --copy` tree, and
-the real directory behind global symlink installs. `update` refreshes it via
-its init/doctor pass. `doctor` lists every detected install with its stamped
-version (`missing` / `unknown (pre-0.1 stamp)` when absent or unparseable).
-The VS Code extension reads the same file to warn about outdated skills;
-absent or corrupt means "unknown (legacy)", never an error.
+| `npx archgen-skill uninstall --project [dir]` | Remove a project install: strips managed blocks, symlink, and store **only if unmodified** — `.archgen/` feature folders and all user content are preserved |
+| `npx archgen-skill doctor [dir] [--check]` | Verify and auto-repair an installation: store integrity, version stamp, Claude link, managed blocks, manifest (`--check` reports without fixing) |
+| `npx archgen-skill update [dir]` | Check npm for a newer `archgen-skill`, upgrade the global install if outdated, then re-init the project and run doctor against the new version |
+| `npx archgen-skill restore` | List backup snapshots; `--snapshot <ts>` restores one (current state is backed up first) |
+| `npx archgen-skill migrate [dir] [--apply]` | Evolve generated-artifact formats in place (`--check` by default; every touched file is backed up) |
+| `npx archgen-skill --version` / `--help` | Print the CLI version / show help |
 
 ## Why archgen
 
 AI coding agents fail at scale for predictable reasons: plans with hidden cycles,
 workers editing the same files, tasks without objective acceptance criteria, and no
 human checkpoint before execution. archgen makes each of these a *structural*
-guarantee rather than a hope:
+guarantee:
 
 | Guarantee | Mechanism |
 | --- | --- |
-| Plans are valid before work starts | Verifier gate — catches cycles, dangling refs, ownership overlaps, plan↔task coverage gaps |
+| Plans are valid before work starts | Verifier gate — cycles, dangling refs, ownership overlaps, plan↔task coverage |
 | You approve before code is written | Explicit user gate after verifier approval |
 | Parallel workers never collide | Disjoint `file_ownership` globs enforced per wave |
 | Task order is always correct | Topological waves from `depends_on`; chains stay sequential |
@@ -124,23 +124,18 @@ guarantee rather than a hope:
 
 ## Supported harnesses
 
-| Harness | Global install | Project-local (`init`) |
-| --- | --- | --- |
-| Claude Code | ✅ | ✅ |
-| OpenCode | ✅ | ✅ |
-| Cursor | ✅ | ✅ |
-| Codex | ✅ | ✅ |
-| Gemini CLI | ✅ | ✅ |
-| Antigravity | ✅ | ✅ |
-| Any agentskills.io harness | ✅ | ✅ |
+Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Antigravity — and any
+agentskills.io-compatible harness. Both global install and project-local `init`
+are supported for all of them.
 
 ## VS Code extension (optional)
 
-A read-only visual layer that renders `.archgen/` as a live task DAG (running tasks
-pulse, edges animate), your code-dependency graph, and rendered docs — with a ▶
-button that launches your agent on any task. Install the `.vsix` from
-[GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It is strictly
-a viewer: uninstalling it loses nothing.
+A visual layer that renders `.archgen/` as a live task DAG, your
+code-dependency graph, and rendered docs — with a ▶ button that hands any task to
+your agent. Install it from the VS Code Marketplace or from a `.vsix` on
+[GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It never
+edits your plan, your tasks, or your code — only its own runtime state under
+`.archgen/.runtime/`, so uninstalling it loses nothing.
 
 ## Documentation
 
@@ -149,7 +144,6 @@ a viewer: uninstalling it loses nothing.
 | [Architecture walkthrough](https://github.com/akashmaurya99/archgen/blob/main/docs/architecture.md) | Dual-mode design, gates, wave mechanics, platform detection |
 | [The skill contract](https://github.com/akashmaurya99/archgen/blob/main/skill/SKILL.md) | The full skill specification agents execute |
 | [Changelog](https://github.com/akashmaurya99/archgen/blob/main/CHANGELOG.md) | Release history |
-| [Contributing](https://github.com/akashmaurya99/archgen/blob/main/CONTRIBUTING.md) | Development setup and PR guide |
 
 ## Contributing
 
@@ -157,7 +151,7 @@ See [CONTRIBUTING.md](https://github.com/akashmaurya99/archgen/blob/main/CONTRIB
 Skill suite and CLI tests run with zero dependencies:
 
 ```sh
-node --test skill/scripts/test/*.test.mjs   # skill suite
+node --test packages/mcp/test/**/*.test.mjs   # MCP server suite
 cd packages/cli && npm test                 # CLI suite
 ```
 

package/bin/archgen.mjs

@@ -22,6 +22,7 @@ import { uninstallProject } from '../lib/uninstall-project.js';
 import { restoreMain } from '../lib/restore.js';
 import { migrateMain } from '../lib/migrate.js';
 import { compareSemver, fetchLatestVersion } from '../lib/version.js';
+import { npmInvocation, whichOnPath } from '../lib/spawn-npm.js';
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 
@@ -46,6 +47,8 @@ Usage:
                                 and generate AGENTS.md / CLAUDE.md pointer blocks.
     [--force]                     proceed automatically; divergent copies are
                                   backed up to .archgen/.backup/ (never destroyed)
+    [--no-codegraph]              skip the CodeGraph bootstrap
+    [--no-mcp]                   skip wiring the archgen MCP server
   npx archgen-skill doctor [dir]      Health-check a project install: store integrity,
                                 version stamp, claude link, managed blocks,
                                 manifest. Repairs safe issues in place.
@@ -53,6 +56,8 @@ Usage:
   npx archgen-skill install           Install into global harness skill dirs
     [--copy]                      real copies instead of symlinks
     [--uninstall]                 remove manifest-recorded entries
+    [--no-codegraph]              skip the CodeGraph bootstrap
+    [--no-mcp]                   skip wiring the archgen MCP server
   npx archgen-skill uninstall         Remove globally-installed copies (manifest-based)
     --project [dir]               remove archgen from a project: claude link,
                                   managed blocks, canonical store (kept when
@@ -92,7 +97,9 @@ try {
   switch (cmd) {
     case 'init': {
       flag('--force');
-      const r = initProject(positionalDir(), PACKAGE_ROOT);
+      const noCodegraph = flag('--no-codegraph');
+      const noMcp = flag('--no-mcp');
+      const r = initProject(positionalDir(), PACKAGE_ROOT, { codegraph: !noCodegraph, mcp: !noMcp });
       console.log('archgen: project ready (single-store layout)');
       console.log('  + store ' + r.storePath);
       if (r.claudeLink === 'created') console.log('  + link  .claude/skills/archgen -> ../../.agents/skills/archgen');
@@ -120,8 +127,10 @@ try {
     }
     case 'install': {
       const copy = flag('--copy');
+      const noCodegraph = flag('--no-codegraph');
+      const noMcp = flag('--no-mcp');
       if (flag('--uninstall')) { uninstall(); break; }
-      const r = installGlobal({ copy });
+      const r = installGlobal({ copy, codegraph: !noCodegraph, mcp: !noMcp });
       console.log('archgen: global harness install (mode: ' + (copy ? 'copy' : 'symlink') + ')');
       for (const [status, mode, path] of r.rows) console.log(`  ${status.padEnd(7)} ${mode.padEnd(5)} ${path}`);
       console.log('\nPer-project setup (recommended): npx archgen-skill init');
@@ -137,6 +146,7 @@ try {
         if (r.storeRemoved) console.log('  - .agents/skills/archgen (unmodified store)');
         if (r.storeKept) console.log('  = .agents/skills/archgen KEPT (customized)');
         if (r.manifestRemoved) console.log('  - .archgen/.install-manifest.json');
+        for (const m of r.mcpRemoved ?? []) console.log(`  - ${m} (archgen MCP entry)`);
         for (const w of r.warnings) console.log('  note: ' + w);
         console.log('  .archgen feature folders and backups are preserved.');
       } else {
@@ -177,23 +187,37 @@ try {
         runInitAndDoctor(dir);
         break;
       }
+      if (!/^\d+\.\d+\.\d+[-+]?[0-9A-Za-z.-]*$/.test(latest)) {
+        // Registry returned something that is not a semver tag — never
+        // interpolate it into a command line.
+        console.error('  ! registry returned a non-semver version string; refusing: ' + JSON.stringify(latest));
+        process.exitCode = 1;
+        break;
+      }
       console.log('  ↑ newer version available: ' + latest);
       console.log('  upgrading global install: npm install -g archgen-skill@' + latest);
-      const up = spawnSync('npm', ['install', '-g', 'archgen-skill@' + latest], { stdio: 'inherit' });
+      const inv = npmInvocation(['install', '-g', 'archgen-skill@' + latest]);
+      const up = spawnSync(inv.command, inv.args, { stdio: 'inherit', shell: inv.shell });
       if (up.status !== 0) {
         console.error('  ! global upgrade failed — run it manually, then re-run: archgen-skill update');
         process.exitCode = 1;
         break;
       }
       // The running process is the OLD code; re-exec the freshly installed binary.
-      const bin = spawnSync('command', ['-v', 'archgen-skill'], { encoding: 'utf8', shell: true });
-      const freshBin = (bin.stdout || '').trim();
+      const freshBin = whichOnPath('archgen-skill');
       if (!freshBin) {
         console.log('\nUpgraded to v' + latest + '. Now finish per project with:\n  npx archgen-skill@latest init');
         break;
       }
       console.log('\nre-running init + doctor with the new binary (' + latest + ')…');
-      spawnSync(freshBin, ['init', dir], { stdio: 'inherit' });
+      const upInit = spawnSync(freshBin, ['init', dir], { stdio: 'inherit' });
+      if (upInit.status !== 0) {
+        // An aborted init (e.g. symlink refusal) must surface as a failure —
+        // running doctor over a half-finished install would mask it.
+        console.error('  ! init failed during update - doctor skipped (see message above)');
+        process.exitCode = upInit.status ?? 1;
+        break;
+      }
       spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
       break;
     }

package/lib/block.js

@@ -18,6 +18,7 @@
 
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { loadConfig } from './config.js';
+import { assertNotSymlink } from './store.js';
 
 // Markers + block-format version come from the single source of truth.
 // Module-level load is safe: config resolution is module-relative and
@@ -97,7 +98,7 @@ export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n')
     '',
     'Rules of the road:',
     '- Generated artifacts live ONLY under `.archgen/<slug>/`',
-    '- Never hand-edit task statuses - use `scripts/set-status.mjs` (comment-safe)',
+    '- Never hand-edit task statuses - call the `archgen_tasks` MCP tool (comment-safe)',
     '- Two gates before any execution: verifier approval, then human approval',
     '',
     '## Features registry',
@@ -127,8 +128,31 @@ export function renderClaudeBridgeText() {
   return [START, provenanceLine(), '@AGENTS.md', END].join('\n');
 }
 
+function countOccurrences(haystack, needle) {
+  let n = 0;
+  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + needle.length)) n++;
+  return n;
+}
+
+function stripCompleteBlocks(text) {
+  let out = text;
+  for (;;) {
+    const s = out.indexOf(START);
+    if (s === -1) break;
+    const e = out.indexOf(END, s + START.length);
+    if (e === -1) break;
+    out = out.slice(0, s) + out.slice(e + END.length);
+  }
+  return out;
+}
+
 /**
  * Insert or replace the managed block inside existing file content.
+ * Corrupted input with DUPLICATED markers (more than one START or END, e.g. a
+ * twice-appended block) is normalized: the first complete block is replaced
+ * in place, every later complete block is removed, and anything outside the
+ * markers survives — the result carries exactly one block. Orphan markers
+ * left over after normalization still throw, as does a single orphan marker.
  * @param {string} existing file contents ('' when creating new)
  * @param {string} block rendered block
  * @param {string} eol line ending used when appending to empty/missing files
@@ -138,6 +162,22 @@ export function upsertBlock(existing, block, eol = '\n') {
   // caller rendered — this is what upgrades legacy unversioned blocks in place.
   const fresh = injectProvenance(block);
   const trimmed = existing ?? '';
+  const starts = countOccurrences(trimmed, START);
+  const ends = countOccurrences(trimmed, END);
+
+  if (starts > 1 || ends > 1) {
+    const s = trimmed.indexOf(START);
+    const e = s === -1 ? -1 : trimmed.indexOf(END, s + START.length);
+    if (s === -1 || e === -1) {
+      throw new Error('found only one archgen marker - fix or remove it manually');
+    }
+    const tail = stripCompleteBlocks(trimmed.slice(e + END.length));
+    if (tail.includes(START) || tail.includes(END)) {
+      throw new Error('found only one archgen marker - fix or remove it manually');
+    }
+    return trimmed.slice(0, s) + fresh + tail;
+  }
+
   const startIdx = trimmed.indexOf(START);
   const endIdx = trimmed.indexOf(END);
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
@@ -152,18 +192,16 @@ export function upsertBlock(existing, block, eol = '\n') {
 }
 
 /**
- * Strip the managed block from file contents.
+ * Strip EVERY managed block from file contents (duplicated markers normalize
+ * to zero blocks, matching upsertBlock's one-block guarantee).
  * @returns {{content: string, hadBlock: boolean}}
  */
 export function stripBlock(existing) {
   const trimmed = existing ?? '';
-  const startIdx = trimmed.indexOf(START);
-  const endIdx = trimmed.indexOf(END);
-  if (startIdx === -1 || endIdx === -1) return { content: trimmed, hadBlock: false };
-  let out = trimmed.slice(0, startIdx) + trimmed.slice(endIdx + END.length);
+  const out = stripCompleteBlocks(trimmed);
+  if (out === trimmed) return { content: trimmed, hadBlock: false };
   // Collapse whitespace left behind; drop file if nothing else remains.
-  out = out.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
-  return { content: out, hadBlock: true };
+  return { content: out.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n'), hadBlock: true };
 }
 
 function splitBom(raw) {
@@ -174,18 +212,24 @@ function splitBom(raw) {
 /** Write via sibling temp file + rename so readers never observe partial content. */
 function atomicWrite(absPath, data) {
   const tmp = absPath + '.tmp-' + process.pid + '-' + Date.now();
-  writeFileSync(tmp, data);
+  // 'wx' (O_CREAT|O_EXCL): if the tmp name already exists — e.g. an attacker
+  // planted a symlink there to redirect the write — fail instead of following.
+  writeFileSync(tmp, data, { flag: 'wx' });
   renameSync(tmp, absPath);
 }
 
 /**
  * BOM/EOL-aware upsert of a managed block directly into a file.
  * Preserves a leading UTF-8 BOM and the file's CRLF/LF convention.
+ * Refuses (throws) when the target is a symlink: managed files must never be
+ * written through a link (the final rename replaces the link itself, but the
+ * read+upsert would otherwise operate on attacker-chosen content).
  * @param {string} absPath target file (created when missing)
  * @param {string[]} blockLines lines between the managed markers
  * @returns {boolean} whether the file existed before the call
  */
 export function upsertManagedFile(absPath, blockLines) {
+  assertNotSymlink(absPath);
   const existed = existsSync(absPath);
   const raw = existed ? readFileSync(absPath, 'utf8') : '';
   const { bom, body } = splitBom(raw);
@@ -208,6 +252,7 @@ export function importsAgents(absPath) {
 
 /** Strip the managed block from a file on disk, preserving BOM. */
 export function stripManagedFile(absPath) {
+  assertNotSymlink(absPath);
   let raw = '';
   try { raw = readFileSync(absPath, 'utf8'); } catch { return { hadBlock: false }; }
   const { bom, body } = splitBom(raw);
@@ -233,6 +278,7 @@ function renderRow(row) {
  * @returns {string} the new file content
  */
 export function upsertFeaturesRegistry(fileAbsPath, rows = []) {
+  assertNotSymlink(fileAbsPath);
   const raw = readFileSync(fileAbsPath, 'utf8');
   const table = [
     '| Feature | Status | Updated |',

package/lib/bootstrap.js

@@ -0,0 +1,103 @@
+// bootstrap.js — the install-time server bootstrap for `archgen init` /
+// `archgen install`.
+//
+// The CLI used to shell out to the skill's scripts/codegraph.mjs. That script
+// no longer exists: ALL deterministic capability now lives in the archgen MCP
+// server, so the CLI drives THAT instead. One implementation, three ways in
+// (agent -> MCP stdio, CLI -> `archgen-mcp bootstrap`, extension -> exec).
+//
+// The bootstrap does two things in one pass:
+//   1. wires the archgen MCP entry into every detected harness
+//   2. ensures CodeGraph: its CLI, its MCP entry, and the project index
+//
+// NEVER FATAL: no npm, no network, a read-only config, or a missing MCP
+// server must still leave a working skill install. Failures are REPORTED,
+// never thrown.
+import { bootstrapMcp, resolveMcpBinary } from './mcp-server.js';
+
+/**
+ * @param {{
+ *   projectDir: string,
+ *   location?: 'project'|'global'|'both',
+ *   log?: (line: string) => void,
+ *   env?: Record<string, string|undefined>,
+ *   noCodegraph?: boolean,
+ *   noMcp?: boolean,
+ * }} opts
+ * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
+ */
+export function bootstrapServers(opts) {
+  const {
+    projectDir,
+    location = 'both',
+    log = () => {},
+    env = process.env,
+    noCodegraph = false,
+    noMcp = false,
+  } = opts;
+
+  // ARCHGEN_CODEGRAPH=0 skips the bootstrap (no spawn, no network, no writes)
+  // — without it the test suite would wire the developer's real MCP configs.
+  if (env.ARCHGEN_CODEGRAPH === '0' || env.ARCHGEN_CODEGRAPH === 'off') {
+    return { ok: true, skipped: 'ARCHGEN_CODEGRAPH=0 (bootstrap disabled)' };
+  }
+  if (noMcp && noCodegraph) {
+    return { ok: true, skipped: '--no-mcp and --no-codegraph passed' };
+  }
+
+  const resolved = resolveMcpBinary({ projectRoot: projectDir, env });
+  log(`  + mcp server: ${resolved.bin ?? 'npx -y archgen-mcp'} (${resolved.source})`);
+
+  if (noMcp) {
+    log('  ! archgen MCP wiring skipped (--no-mcp)');
+  }
+  if (noCodegraph) {
+    log('  ! CodeGraph bootstrap skipped (--no-codegraph)');
+  }
+
+  const r = bootstrapMcp({
+    projectDir,
+    location,
+    approved: true,
+    env,
+  });
+
+  if (!r.report) {
+    return {
+      ok: true, // never fatal — the skill install itself succeeded
+      detail: `server bootstrap incomplete: ${r.detail ?? 'unknown error'}`,
+    };
+  }
+
+  const report = r.report;
+  const mcp = report.mcp ?? {};
+  const codegraph = report.codegraph ?? {};
+
+  for (const w of mcp.wired ?? []) {
+    log(`  + harness: ${w.harness} → ${w.path} [${w.key}] ${w.status}${w.detail ? ' — ' + w.detail : ''}`);
+  }
+  if (codegraph.cli) {
+    log(
+      `  + codegraph ${codegraph.cli.version ?? 'unknown'}${codegraph.cli.action !== 'none' ? ' (' + codegraph.cli.action + ')' : ''}${codegraph.cli.latest ? ' · latest available ' + codegraph.cli.latest : ''}`,
+    );
+  }
+  if (codegraph.telemetry) {
+    log(`  + telemetry: ${codegraph.telemetry.state ?? 'unknown'}${codegraph.telemetry.action !== 'none' ? ' → ' + codegraph.telemetry.action : ''}`);
+  }
+  for (const w of codegraph.wiring?.native ?? []) {
+    log(`  + harness: ${w.targets} (${w.location}) → ${w.status}${w.detail ? ' — ' + w.detail : ''}`);
+  }
+  if (codegraph.index) {
+    log(`  + index: ${codegraph.index.action ?? 'none'}${codegraph.index.files != null ? ' (' + codegraph.index.files + ' files)' : ''}`);
+  }
+  log('  + realtime: the MCP server watches files — the index stays live, no re-indexing needed');
+
+  if (r.ok === false || codegraph.ok === false) {
+    return {
+      ok: false,
+      report,
+      detail: 'one or more server bootstrap steps failed',
+    };
+  }
+  return { ok: true, report };
+}

package/lib/doctor.js

@@ -7,7 +7,7 @@
 // reported and counted in the summary but do NOT fail the run: the process
 // exits non-zero only when a repair operation itself throws.
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+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 { globalTargets } from './install.js';
@@ -22,9 +22,10 @@ import {
   upsertManagedFile,
 } from './block.js';
 import { resolveSkillSource } from './init.js';
-import { CLAUDE_LINK_REL, MANIFEST_REL, STORE_REL, VERSION_FILE, cliVersion, hashDir, loadManifest, saveManifest } from './store.js';
+import { CLAUDE_LINK_REL, DEV_ONLY_RELPATHS, MANIFEST_REL, STORE_REL, VERSION_FILE, 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; }
@@ -83,7 +84,21 @@ 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 = checkOnly ? findObsolete(storeAbs, packaged) : pruneObsolete(storeAbs, packaged);
+      for (const rel of obsolete) {
+        add(checkOnly ? 'WOULD-FIX' : 'FIXED', `store carried the obsolete ${rel}/ tree (pre-MCP layout) -> ${checkOnly ? 'would prune' : 'pruned'}`);
+      }
+    }
+    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.
@@ -98,6 +113,23 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
     }
   }
 
+  // 1b. Prune dev-only artifacts (scripts/test) that older installers shipped
+  //     into the store. They are repo-only CI tooling and never belong in an
+  //     installed tree; removing them here cleans existing stores without a
+  //     full backup+re-copy. hashDir ignores the same subtrees, so this prune
+  //     neither masks real customization nor reads as divergence.
+  if (existsSync(storeAbs)) {
+    const devOnlyPresent = DEV_ONLY_RELPATHS.filter((rel) => existsSync(join(storeAbs, ...rel.split('/'))));
+    if (devOnlyPresent.length > 0) {
+      if (checkOnly) {
+        add('WOULD-FIX', `store carries dev-only ${devOnlyPresent.join(', ')} -> pruned`);
+      } else {
+        attempt(() => pruneDevOnly(storeAbs), 'FIXED',
+          `dev-only ${devOnlyPresent.join(', ')} pruned from store`, 'cannot prune dev-only artifacts');
+      }
+    }
+  }
+
   // 2. Version stamp currency.
   const stampAbs = join(storeAbs, VERSION_FILE);
   let stamp = null;
@@ -146,8 +178,10 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
   if (!existsSync(agentsAbs)) {
     if (checkOnly) add('WOULD-FIX', 'AGENTS.md missing -> created with managed block');
     else {
-      writeFileSync(agentsAbs, renderBlock(STORE_REL) + '\n');
-      add('FIXED', 'AGENTS.md created with managed block');
+      // Through the guarded upsert (not raw writeFileSync): existsSync follows
+      // symlinks, so a dangling symlink would otherwise be written through.
+      attempt(() => upsertManagedFile(agentsAbs, renderBlock(STORE_REL).split('\n')), 'FIXED',
+        'AGENTS.md created with managed block', 'cannot create AGENTS.md managed block');
     }
   } else {
     let raw = readFileSync(agentsAbs, 'utf8');
@@ -277,6 +311,34 @@ 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 };