archgen-skill 0.0.5 → 0.0.7

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,
@@ -42,6 +42,13 @@ copies are backed up to `.archgen/.backup/<timestamp>/` before refresh, and lega
 dual-copy layouts are migrated to symlinks automatically. Verify anytime with
 `archgen-skill doctor`.
 
+Every destructive step is behind a rail: the project root is asserted **before**
+anything is written or deleted, a symlinked target is never written through, the
+store swap is atomic (the old store is moved aside, not deleted, and restored if
+the swap fails), and a restore puts back exactly the paths the snapshot recorded
+— never a sibling skill. `archgen-skill uninstall <dir>` removes that project;
+the global uninstall happens only when no project is named.
+
 **Or install globally** into every detected harness:
 
 ```bash
@@ -49,8 +56,13 @@ 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
 
@@ -75,7 +87,7 @@ by git.
 | `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 a project install: strips managed blocks, symlink, and store **only if unmodified** — `.archgen/` feature folders and all user content are preserved |
+| `npx archgen-skill uninstall [dir]` | Remove a **project** install (same as `--project [dir]`): 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) |
@@ -125,11 +137,12 @@ are supported for all of them.
 
 ## VS Code extension (optional)
 
-A read-only visual layer that renders `.archgen/` as a live task DAG, your
+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 anything: uninstalling it loses nothing.
+edits your plan, your tasks, or your code — only its own runtime state under
+`.archgen/.runtime/`, so uninstalling it loses nothing.
 
 ## Documentation
 
@@ -145,7 +158,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, globalBinPath } from '../lib/spawn-npm.js';
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 
@@ -34,7 +35,13 @@ function cliVersion() {
 function runInitAndDoctor(dir) {
   const r = initProject(dir, PACKAGE_ROOT);
   console.log('  = store refreshed at ' + r.storePath);
-  doctorProject(dir, PACKAGE_ROOT, {});
+  const d = doctorProject(dir, PACKAGE_ROOT, {});
+  // A failed doctor must fail the update too: the project was NOT brought to
+  // the new version.
+  if (d.failures > 0) {
+    console.error('  ! doctor reported ' + d.failures + ' failure(s)');
+    process.exitCode = 1;
+  }
 }
 
 const HELP = `archgen — architecture generation & autonomous task execution for coding agents
@@ -44,16 +51,26 @@ Usage:
                                 store at .agents/skills/archgen, symlink
                                 .claude/skills/archgen -> ../../.agents/skills/archgen,
                                 and generate AGENTS.md / CLAUDE.md pointer blocks.
+    [--project <dir>]              the project directory (same as the positional
+                                   form; give it once, not both)
     [--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.
+    [--project <dir>]              the project directory (same as the positional form)
     [--check]                     report only - change nothing
   npx archgen-skill install           Install into global harness skill dirs
     [--copy]                      real copies instead of symlinks
     [--uninstall]                 remove manifest-recorded entries
-  npx archgen-skill uninstall         Remove globally-installed copies (manifest-based)
+    [--no-codegraph]              skip the CodeGraph bootstrap
+    [--no-mcp]                   skip wiring the archgen MCP server
+  npx archgen-skill uninstall [dir]     Remove archgen from a project (the same
+                                 as the positional form); without a directory
+                                 the globally-installed copies are removed
+                                 (manifest-based)
     --project [dir]               remove archgen from a project: claude link,
                                   managed blocks, canonical store (kept when
                                   customized) and manifest; .archgen feature
@@ -84,15 +101,74 @@ function flag(name) {
   return true;
 }
 
-function positionalDir() {
-  return rest[0] ? resolve(rest[0]) : process.cwd();
+/**
+ * Consume an option that takes a value: `--name <value>` or `--name=<value>`.
+ *
+ * Returns null when the option is absent, '' when it is present with no
+ * value ("use the default"), and the value otherwise.
+ */
+function takeValue(name) {
+  const eq = rest.findIndex((a) => a.startsWith(name + '='));
+  if (eq !== -1) {
+    const v = rest[eq].slice(name.length + 1);
+    rest.splice(eq, 1);
+    return v;
+  }
+  const i = rest.indexOf(name);
+  if (i === -1) return null;
+  rest.splice(i, 1);
+  const v = rest[i];
+  if (v === undefined || v.startsWith('-')) return '';
+  rest.splice(i, 1);
+  return v;
+}
+
+/**
+ * The project directory for a command.
+ *
+ * Accepts a POSITIONAL dir (`init myproj`) and `--project <dir>` alike. The
+ * same flag name is used by `uninstall` and `restore`, and the MCP server's
+ * own commands take `--project` too — so a user who typed one form must
+ * never get a directory literally named "--project" created in their cwd.
+ *
+ * Extra positional arguments are REFUSED: silently ignoring the second one
+ * would install into a directory the user did not name.
+ */
+function targetDir() {
+  const explicit = takeValue('--project');
+  const positionals = rest.filter((a) => !a.startsWith('-'));
+  if (positionals.length > 1) {
+    throw new Error(`unexpected argument: ${positionals[1]} — give the project directory once`);
+  }
+  const positional = positionals[0];
+  const explicitDir = explicit === null ? null : (explicit === '' ? process.cwd() : resolve(explicit));
+  if (explicitDir !== null && positional !== undefined && explicitDir !== resolve(positional)) {
+    throw new Error('give the project directory once: either positionally or with --project');
+  }
+  return explicitDir ?? (positional !== undefined ? resolve(positional) : process.cwd());
+}
+
+/**
+ * Refuse an option we do not understand.
+ *
+ * An unknown flag is a TYPO. It is never a directory name — creating a
+ * directory called "--no-mcp" because the flag was misspelled is exactly the
+ * kind of silent mess this check exists to prevent.
+ */
+function assertNoUnknownFlags() {
+  const unknown = rest.find((a) => a.startsWith('-'));
+  if (unknown) throw new Error(`unknown option: ${unknown}`);
 }
 
 try {
   switch (cmd) {
     case 'init': {
       flag('--force');
-      const r = initProject(positionalDir(), PACKAGE_ROOT);
+      const noCodegraph = flag('--no-codegraph');
+      const noMcp = flag('--no-mcp');
+      const dir = targetDir();
+      assertNoUnknownFlags();
+      const r = initProject(dir, 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');
@@ -110,7 +186,9 @@ try {
     }
     case 'doctor': {
       const check = flag('--check');
-      const r = doctorProject(positionalDir(), PACKAGE_ROOT, { check });
+      const dir = targetDir();
+      assertNoUnknownFlags();
+      const r = doctorProject(dir, PACKAGE_ROOT, { check });
       console.log('archgen doctor — ' + r.root + (check ? '  (check mode: no changes made)' : ''));
       for (const c of r.checks) console.log(`  [${c.status.toLowerCase().padEnd(9)}] ${c.msg}`);
       const t = r.tally;
@@ -120,8 +198,14 @@ try {
     }
     case 'install': {
       const copy = flag('--copy');
-      if (flag('--uninstall')) { uninstall(); break; }
-      const r = installGlobal({ copy });
+      const noCodegraph = flag('--no-codegraph');
+      const noMcp = flag('--no-mcp');
+      const uninstallMode = flag('--uninstall');
+      assertNoUnknownFlags();
+      const stray = rest.find((a) => !a.startsWith('-'));
+      if (stray) throw new Error(`unexpected argument: ${stray} — install takes no directory`);
+      if (uninstallMode) { uninstall(); break; }
+      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');
@@ -129,14 +213,32 @@ try {
       break;
     }
     case 'uninstall': {
-      if (flag('--project')) {
-        const r = uninstallProject(positionalDir(), PACKAGE_ROOT);
+      // `--project` may carry a directory (`uninstall --project myproj`) or
+      // stand alone (`uninstall --project` → this directory). A POSITIONAL
+      // directory (`uninstall myproj`) is a project uninstall as well: the
+      // GLOBAL uninstall happens only when no project was named at all.
+      const explicit = takeValue('--project');
+      const positionals = rest.filter((a) => !a.startsWith('-'));
+      assertNoUnknownFlags();
+      if (positionals.length > 1) {
+        throw new Error(`unexpected argument: ${positionals[1]} — give the project directory once`);
+      }
+      const positional = positionals[0];
+      const projectTarget = explicit !== null
+        ? (explicit === '' ? process.cwd() : resolve(explicit))
+        : (positional !== undefined ? resolve(positional) : null);
+      if (explicit !== null && positional !== undefined && projectTarget !== resolve(positional)) {
+        throw new Error('give the project directory once: either positionally or with --project');
+      }
+      if (projectTarget !== null) {
+        const r = uninstallProject(projectTarget, PACKAGE_ROOT);
         console.log('archgen: project uninstall — ' + r.root);
         if (r.linkRemoved) console.log('  - .claude/skills/archgen (link)');
         if (r.strippedBlocks.length) console.log('  - managed blocks stripped from ' + r.strippedBlocks.join(', '));
         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 {
@@ -156,7 +258,8 @@ try {
       break;
     }
     case 'update': {
-      const dir = positionalDir();
+      const dir = targetDir();
+      assertNoUnknownFlags();
       const current = cliVersion();
       console.log('archgen update — running v' + current + ', checking npm registry…');
       const latest = fetchLatestVersion('archgen-skill');
@@ -165,6 +268,14 @@ try {
         break;
       }
       const cmp = compareSemver(latest, current);
+      if (cmp === null) {
+        // The registry answered with something that is not a semver (e.g. a
+        // "beta" dist-tag). It is NOT "already the latest version" — refuse
+        // instead, and never interpolate it into a command line.
+        console.error('  ! registry returned a non-semver version string; refusing: ' + JSON.stringify(latest));
+        process.exitCode = 1;
+        break;
+      }
       if (cmp === 0) {
         console.log('  = already on the latest published version (' + latest + ').');
         console.log('  Refreshing this project against it anyway…');
@@ -177,17 +288,26 @@ 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();
+      // The PATH search would find the FIRST match — often the OLD global
+      // install — so the binary npm actually wrote is preferred.
+      const freshBin = globalBinPath('archgen-skill') ?? whichOnPath('archgen-skill');
       if (!freshBin) {
         console.log('\nUpgraded to v' + latest + '. Now finish per project with:\n  npx archgen-skill@latest init');
         break;
@@ -201,7 +321,13 @@ try {
         process.exitCode = upInit.status ?? 1;
         break;
       }
-      spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
+      const upDoctor = spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
+      if (upDoctor.status !== 0) {
+        // A failed doctor must fail the update too — the project was NOT
+        // brought to the new version.
+        console.error('  ! doctor failed during update (see message above)');
+        process.exitCode = upDoctor.status ?? 1;
+      }
       break;
     }
     case '--version': case '-v': {
@@ -226,5 +352,6 @@ function uninstall() {
   const r = uninstallGlobal();
   if (r.noop) { console.log('archgen: nothing to uninstall (no manifest found).'); return; }
   console.log(`archgen: removed ${r.removed} entr${r.removed === 1 ? 'y' : 'ies'}` + (r.failed ? `, ${r.failed} FAILED` : ''));
+  for (const b of r.backups ?? []) console.log('  ~ backup ' + b + ' (edited copy saved before removal)');
   if (r.failed > 0) process.exitCode = 1;
 }

package/lib/block.js

@@ -16,7 +16,7 @@
 // place on the next init/doctor pass and detectBlockVersion() lets doctor
 // report stale formats precisely.
 
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { loadConfig } from './config.js';
 import { assertNotSymlink } from './store.js';
 
@@ -98,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',
@@ -171,11 +171,14 @@ export function upsertBlock(existing, block, eol = '\n') {
     if (s === -1 || e === -1) {
       throw new Error('found only one archgen marker - fix or remove it manually');
     }
+    const prefix = trimmed.slice(0, s);
     const tail = stripCompleteBlocks(trimmed.slice(e + END.length));
-    if (tail.includes(START) || tail.includes(END)) {
+    // An orphan marker ANYWHERE (before the first block as well as after it)
+    // would survive the rewrite and leave the file broken — refuse instead.
+    if (prefix.includes(START) || prefix.includes(END) || 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;
+    return prefix + fresh + tail;
   }
 
   const startIdx = trimmed.indexOf(START);
@@ -209,13 +212,37 @@ function splitBom(raw) {
   return { bom, body: bom ? raw.slice(1) : 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();
-  // '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);
+/**
+ * Write via sibling temp file + rename so readers never observe partial content.
+ * @param {string} absPath target file
+ * @param {string} data contents
+ */
+export function atomicWrite(absPath, data) {
+  let tmp = absPath + '.tmp-' + process.pid + '-' + Date.now();
+  for (let attempt = 0; ; attempt++) {
+    try {
+      // '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' });
+      break;
+    } catch (e) {
+      // A collision (two writes inside the same millisecond) is not a failure:
+      // retry with a fresh name instead of failing the whole write.
+      if (e && e.code === 'EEXIST' && attempt < 10) {
+        tmp = absPath + '.tmp-' + process.pid + '-' + Date.now() + '-' + (attempt + 1);
+        continue;
+      }
+      throw e;
+    }
+  }
+  try {
+    renameSync(tmp, absPath);
+  } catch (e) {
+    // Never leave the temp file behind: a failed rename must not litter the
+    // project with half-written siblings.
+    try { unlinkSync(tmp); } catch { /* original intact; leftover tmp is harmless */ }
+    throw e;
+  }
 }
 
 /**
@@ -250,6 +277,20 @@ export function importsAgents(absPath) {
   return body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
 }
 
+/**
+ * True when the file carries a COMPLETE managed block (both markers).
+ *
+ * A file with a hand-written `@AGENTS.md` import has none — that import is
+ * the user's, not ours, and must survive untouched. A file WITH a managed
+ * block is ours: its provenance stamp is refreshed on every init, exactly
+ * like the AGENTS.md block.
+ */
+export function hasManagedBlock(absPath) {
+  let raw = '';
+  try { raw = readFileSync(absPath, 'utf8'); } catch { return false; }
+  return raw.includes(START) && raw.includes(END);
+}
+
 /** Strip the managed block from a file on disk, preserving BOM. */
 export function stripManagedFile(absPath) {
   assertNotSymlink(absPath);

package/lib/bootstrap.js

@@ -0,0 +1,107 @@
+// 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 to
+// the caller (ok:false + detail) and rendered as a warning by it — never
+// thrown, and never swallowed.
+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) {
+    // The bootstrap did NOT run: report it as a failure so the caller tells
+    // the user. The skill install itself still succeeded — this is a warning,
+    // not a fatal error — but it must never be swallowed silently.
+    return {
+      ok: false,
+      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: r.detail ? `server bootstrap incomplete: ${r.detail}` : 'one or more server bootstrap steps failed',
+    };
+  }
+  return { ok: true, report };
+}

package/lib/config.js

@@ -2,8 +2,9 @@
 //
 // WHY: the version, managed-block marker strings, and well-known filenames
 // were hardcoded independently in block.js, store.js, install.js, install.sh,
-// and SKILL.md frontmatter — and drifted (SKILL.md advertised 1.0.0 while the
-// CLI shipped 0.0.x). The canonical file lives at <repo-root>/archgen.config.json;
+// and SKILL.md frontmatter — and drifted (SKILL.md advertised a version the
+// CLI had never shipped). The canonical file lives at
+// <repo-root>/archgen.config.json;
 // a byte-identical derived copy ships inside the published npm package at
 // vendor/skills/archgen/archgen.config.json (kept in sync by
 // scripts/sync-config.mjs + scripts/sync-vendor.mjs).