archgen-skill 0.0.7 → 0.1.0

package/README.md

@@ -87,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 [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 uninstall [dir]` | Remove a **project** install (same as `--project [dir]`): strips managed blocks, symlink, the store **only if unmodified**, and the dead `.archgen/.runtime/` extension state — `.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) |
@@ -135,15 +135,6 @@ 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 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
 
 | Doc | Contents |

package/bin/archgen.mjs

@@ -57,6 +57,9 @@ Usage:
                                   backed up to .archgen/.backup/ (never destroyed)
     [--no-codegraph]              skip the CodeGraph bootstrap
     [--no-mcp]                   skip wiring the archgen MCP server
+    [--location-project]          wire the PROJECT-local harness configs too
+                                   (by default only the global ones are wired,
+                                   so a project carries no MCP configuration)
   npx archgen-skill doctor [dir]      Health-check a project install: store integrity,
                                 version stamp, claude link, managed blocks,
                                 manifest. Repairs safe issues in place.
@@ -166,9 +169,17 @@ try {
       flag('--force');
       const noCodegraph = flag('--no-codegraph');
       const noMcp = flag('--no-mcp');
+      // The harness configs live in the user's home by default, so a project
+      // carries no MCP configuration of its own. `--location project` opts
+      // into wiring the project-local configs instead.
+      const location = flag('--location-project') ? 'project' : 'global';
       const dir = targetDir();
       assertNoUnknownFlags();
-      const r = initProject(dir, PACKAGE_ROOT, { codegraph: !noCodegraph, mcp: !noMcp });
+      const r = initProject(dir, PACKAGE_ROOT, {
+        codegraph: !noCodegraph,
+        mcp: !noMcp,
+        location,
+      });
       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');
@@ -238,6 +249,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');
+        if (r.runtimeRemoved) console.log('  - .archgen/.runtime (legacy extension state)');
         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.');

package/lib/bootstrap.js

@@ -3,8 +3,8 @@
 //
 // 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).
+// server, so the CLI drives THAT instead. One implementation, two ways in
+// (agent -> MCP stdio, CLI -> `archgen-mcp bootstrap`).
 //
 // The bootstrap does two things in one pass:
 //   1. wires the archgen MCP entry into every detected harness
@@ -15,26 +15,31 @@
 // the caller (ok:false + detail) and rendered as a warning by it — never
 // thrown, and never swallowed.
 import { bootstrapMcp, resolveMcpBinary } from './mcp-server.js';
+import { ensureGlobalServer, serverVersion } from './global-server.js';
 
 /**
  * @param {{
  *   projectDir: string,
+ *   packageRoot?: string,
  *   location?: 'project'|'global'|'both',
  *   log?: (line: string) => void,
  *   env?: Record<string, string|undefined>,
  *   noCodegraph?: boolean,
  *   noMcp?: boolean,
+ *   global?: boolean,
  * }} opts
  * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
  */
 export function bootstrapServers(opts) {
   const {
     projectDir,
+    packageRoot = null,
     location = 'both',
     log = () => {},
     env = process.env,
     noCodegraph = false,
     noMcp = false,
+    global = true,
   } = opts;
 
   // ARCHGEN_CODEGRAPH=0 skips the bootstrap (no spawn, no network, no writes)
@@ -46,8 +51,25 @@ export function bootstrapServers(opts) {
     return { ok: true, skipped: '--no-mcp and --no-codegraph passed' };
   }
 
+  // ONE server for every harness. A global install gives every harness the
+  // same binary at a stable path, so a harness config can name an absolute
+  // executable that keeps working — instead of pointing into npm's npx
+  // CACHE, which `npm cache clean` removes out from under it.
+  //
+  // The server is refreshed to the version THIS CLI ships with: the CLI and
+  // the server are released together, so an older server is an older
+  // implementation of the very tools the CLI wires.
+  let serverNote = '';
+  if (global && !noMcp) {
+    const version = packageRoot ? serverVersion(packageRoot) : 'latest';
+    const installed = ensureGlobalServer({ env, version });
+    serverNote = installed.note;
+    if (installed.detail) serverNote += ` (${installed.detail})`;
+  }
+
   const resolved = resolveMcpBinary({ projectRoot: projectDir, env });
   log(`  + mcp server: ${resolved.bin ?? 'npx -y archgen-mcp'} (${resolved.source})`);
+  if (serverNote) log(`  + mcp server: ${serverNote}`);
 
   if (noMcp) {
     log('  ! archgen MCP wiring skipped (--no-mcp)');
@@ -57,7 +79,7 @@ export function bootstrapServers(opts) {
   }
 
   const r = bootstrapMcp({
-    projectDir,
+    projectRoot: projectDir,
     location,
     approved: true,
     env,

package/lib/doctor.js

@@ -363,9 +363,9 @@ export function doctorProject(projectDir, packageRoot, opts = {}) {
 
   // 7. Version-stamp inventory — every archgen skill tree visible from this
   //    project/machine, one line each, for tools that probe
-  //    <skillRoot>/.archgen-version (the VS Code extension reads it to warn
-  //    "skill outdated"). Report-only: doctor repairs the project stamp in
-  //    section 2, never global installs.
+  //    <skillRoot>/.archgen-version (the MCP server reads it to report the
+  //    installed skill's version). Report-only: doctor repairs the project
+  //    stamp in section 2, never global installs.
   const seen = new Set();
   const installs = [];
   const noteInstall = (p) => {

package/lib/global-server.js

@@ -0,0 +1,154 @@
+// global-server.js — ONE archgen MCP server for every harness, kept current.
+//
+// WHY A GLOBAL INSTALL.
+//
+// The harness configs name the server's executable by ABSOLUTE PATH, so the
+// path has to keep working. The npx fallback points into npm's npx CACHE
+// (~/.npm/_npx/<hash>/…), which `npm cache clean --force` removes — and the
+// harness then fails to start a server that was wired minutes earlier.
+//
+// A global install (`npm install -g archgen-mcp`) puts the binary in the
+// npm prefix's bin directory: one copy, shared by every harness, at a path
+// that does not move when the registry publishes a new version.
+//
+// THE UPGRADE.
+//
+// The CLI and the server are released TOGETHER, so the CLI knows exactly
+// which server version it was tested against. An installed server that is
+// OLDER is refreshed to that version; one that is NEWER (a dev build, or a
+// version published after this CLI) is left alone — downgrading it would
+// break a working setup.
+//
+// The install is BEST EFFORT. A machine without a writable npm prefix, an
+// offline machine, or a user who does not want a global package must still
+// get a working skill install: the npx fallback covers all of them, and the
+// OLD server keeps working until it is replaced.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { npmInvocation, whichOnPath } from './spawn-npm.js';
+import { compareSemver } from './version.js';
+
+export const MCP_PACKAGE = 'archgen-mcp';
+
+/**
+ * The version of the server this CLI ships with.
+ *
+ * The CLI and the server are released together, so the installer can ask for
+ * exactly the version it was tested against instead of "whatever is latest".
+ *
+ * @param {string} packageRoot the CLI's own package root
+ * @returns {string}
+ */
+export function serverVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : 'latest';
+  } catch {
+    return 'latest';
+  }
+}
+
+/**
+ * The version of an INSTALLED server, read from its own package.
+ *
+ * The binary is a symlink into the global package's bin directory, so the
+ * package root is one level above the script's directory.
+ *
+ * @param {string} bin the resolved executable
+ * @returns {string|null} the version, or null when it cannot be read
+ */
+export function installedServerVersion(bin) {
+  try {
+    const real = realpathSync(bin);
+    const pkg = JSON.parse(readFileSync(join(dirname(real), '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Make sure `archgen-mcp` is installed globally, at the right version.
+ *
+ * @param {{env?: Record<string, string|undefined>, version?: string}} opts
+ * @returns {{installed: boolean, bin: string|null, upgraded: boolean,
+ *   note: string, detail?: string}}
+ */
+export function ensureGlobalServer(opts = {}) {
+  const { env = process.env, version = 'latest' } = opts;
+
+  const onPath = whichOnPath(MCP_PACKAGE, env);
+  if (onPath) {
+    const installed = installedServerVersion(onPath);
+    if (installed === version) {
+      return {
+        installed: true,
+        bin: onPath,
+        upgraded: false,
+        note: `already installed at ${onPath} (v${installed})`,
+      };
+    }
+    if (installed && version !== 'latest' && compareSemver(installed, version) > 0) {
+      // A newer server is already there — a dev build, or a release published
+      // after this CLI. Downgrading it would break a working setup.
+      return {
+        installed: true,
+        bin: onPath,
+        upgraded: false,
+        note: `installed v${installed} is newer than this CLI's v${version} — left as it is`,
+      };
+    }
+    const refreshed = installGlobal(version, env);
+    if (refreshed.installed) {
+      return {
+        installed: true,
+        bin: refreshed.bin,
+        upgraded: true,
+        note: `upgraded the archgen MCP server to v${version} at ${refreshed.bin}`,
+      };
+    }
+    // The upgrade failed — the OLD server still works, so keep it and say so.
+    return {
+      installed: true,
+      bin: onPath,
+      upgraded: false,
+      note: `could not upgrade the archgen MCP server to v${version} — the installed v${installed} stays`,
+      detail: refreshed.detail,
+    };
+  }
+
+  const fresh = installGlobal(version, env);
+  return {
+    installed: fresh.installed,
+    bin: fresh.bin,
+    upgraded: false,
+    note: fresh.installed
+      ? `installed the archgen MCP server globally at ${fresh.bin}`
+      : `could not install the archgen MCP server globally — the npx fallback will be used`,
+    detail: fresh.detail,
+  };
+}
+
+/** `npm install -g archgen-mcp@<version>`. */
+function installGlobal(version, env) {
+  const spec = version === 'latest' ? MCP_PACKAGE : `${MCP_PACKAGE}@${version}`;
+  const inv = npmInvocation(['install', '-g', spec], env);
+  const r = spawnSync(inv.command, inv.args, {
+    encoding: 'utf8',
+    timeout: 300000,
+    env,
+    shell: inv.shell,
+  });
+  if (r.status !== 0) {
+    const detail = (r.stderr || r.stdout || '').trim().split('\n').pop();
+    return { installed: false, bin: null, detail: detail || `npm exited ${r.status}` };
+  }
+  // npm succeeded — but the install only COUNTS if the binary is now
+  // findable. A prefix that is not on PATH, or a package that shipped no
+  // bin, would otherwise be reported as a success.
+  const bin = whichOnPath(MCP_PACKAGE, env);
+  return bin
+    ? { installed: true, bin, detail: undefined }
+    : { installed: false, bin: null, detail: 'npm reported success but the binary is not on PATH' };
+}

package/lib/init.js

@@ -205,10 +205,17 @@ export function initProject(projectDir, packageRoot, opts = {}) {
   //    harness AND ensure CodeGraph (its CLI, its MCP entry, the project
   //    index). Non-fatal by design: an offline machine still gets the skill
   //    installed.
+  //
+  //    The wiring is GLOBAL by default: the server is one binary for every
+  //    harness, and the harness configs live in the user's home. A project
+  //    that carries its own `.mcp.json`, `.codex/` and `.gemini/` is a
+  //    project that has to be re-wired in every clone. `--location project`
+  //    opts into the per-project wiring.
   if (codegraphAllowed || mcpAllowed) {
     const r = bootstrapServers({
       projectDir: root,
-      location: 'both',
+      packageRoot: packageRoot,
+      location: opts.location ?? 'global',
       log,
       env: opts.env,
       noCodegraph: !codegraphAllowed,

package/lib/mcp-server.js

@@ -11,8 +11,9 @@
 // never thrown — the same posture bootstrapCodegraph has always had.
 import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { whichOnPath } from './spawn-npm.js';
 import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 
 export const MCP_PACKAGE = 'archgen-mcp';
 
@@ -52,25 +53,16 @@ export function resolveMcpBinary(opts = {}) {
 
 /**
  * Locate an executable on PATH (cross-platform, no shell).
- * @param {string} bin
- * @param {Record<string, string|undefined>} env
- * @returns {string|null}
+ *
+ * ONE implementation, in spawn-npm.js — this module used to carry its own
+ * copy, and the two had drifted: the copy here skipped a path ending in '/',
+ * the one there did not, and neither checked that the path was a FILE. Two
+ * implementations of one rule is how the rules start disagreeing.
+ *
+ * Imported for this module's own use AND re-exported, so the callers that
+ * already import it from here keep working.
  */
-export function whichOnPath(bin, env = process.env) {
-  const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';') : [''];
-  const dirs = (env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
-  for (const d of dirs) {
-    for (const ext of exts) {
-      const p = join(d, bin + ext);
-      try {
-        if (existsSync(p) && !p.endsWith('/')) return p;
-      } catch {
-        /* not here */
-      }
-    }
-  }
-  return null;
-}
+export { whichOnPath };
 
 /**
  * Quote one argument for cmd.exe.
@@ -155,6 +147,33 @@ export function mcpInvocation(command, args, platform = process.platform, env =
   return { command: quoteWindowsArg(cmd), args: args.map(quoteWindowsArg), shell: true };
 }
 
+/**
+ * The project root an MCP call is made against.
+ *
+ * It MUST be an ABSOLUTE path.
+ *
+ * The child process resolves a relative root against ITS OWN working
+ * directory, so a root that was missing — or a property-name mismatch
+ * between the caller and the callee — did not fail. It silently wrote the
+ * harness configs, the CodeGraph index and the managed blocks into a
+ * directory named "undefined", next to the real project.
+ *
+ * The guard turns that class of mistake into an immediate, named failure.
+ *
+ * @param {unknown} projectRoot
+ * @param {string} fn the caller's name, for the message
+ * @returns {string} the absolute project root
+ */
+export function requireProjectRoot(projectRoot, fn) {
+  if (typeof projectRoot !== 'string' || projectRoot.trim() === '') {
+    throw new Error(`${fn}: projectRoot is required and must be an absolute path`);
+  }
+  if (!isAbsolute(projectRoot)) {
+    throw new Error(`${fn}: projectRoot must be an absolute path (got '${projectRoot}')`);
+  }
+  return resolve(projectRoot);
+}
+
 /**
  * Run one `archgen-mcp` subcommand and return its JSON output.
  *
@@ -163,7 +182,8 @@ export function mcpInvocation(command, args, platform = process.platform, env =
  * @returns {{ok: boolean, code: number|null, data: any, stdout: string, stderr: string, detail?: string}}
  */
 export function runMcp(args, opts = {}) {
-  const { projectRoot = process.cwd(), timeout = 600000, env = process.env } = opts;
+  const { timeout = 600000, env = process.env } = opts;
+  const projectRoot = requireProjectRoot(opts.projectRoot ?? process.cwd(), 'runMcp');
   const resolved = resolveMcpBinary({ projectRoot, env });
   const inv = mcpInvocation(resolved.command, [...resolved.args, ...args], process.platform, env);
 
@@ -198,6 +218,25 @@ export function runMcp(args, opts = {}) {
   };
 }
 
+/**
+ * The arguments for the server's bootstrap call.
+ *
+ * Exported so the project root in them can be asserted directly: the bug
+ * this guards against was a property-name mismatch that put the literal
+ * string "undefined" in this exact position.
+ *
+ * @param {string} projectRoot
+ * @param {{location?: 'project'|'global'|'both', approved?: boolean}} [opts]
+ * @returns {string[]}
+ */
+export function bootstrapArgs(projectRoot, opts = {}) {
+  const { location = 'both', approved = true } = opts;
+  const root = requireProjectRoot(projectRoot, 'bootstrapArgs');
+  const args = ['bootstrap', '--project', root, '--location', location, '--json'];
+  if (approved) args.push('--yes');
+  return args;
+}
+
 /**
  * Wire the archgen MCP server into the detected harnesses and ensure CodeGraph.
  *
@@ -205,11 +244,10 @@ export function runMcp(args, opts = {}) {
  * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
  */
 export function bootstrapMcp(opts) {
-  const { projectRoot, location = 'both', approved = true, env = process.env } = opts;
-  const args = ['bootstrap', '--project', projectRoot, '--location', location, '--json'];
-  if (approved) args.push('--yes');
+  const { location = 'both', approved = true, env = process.env } = opts;
+  const args = bootstrapArgs(opts.projectRoot, { location, approved });
 
-  const r = runMcp(args, { projectRoot, env });
+  const r = runMcp(args, { projectRoot: opts.projectRoot, env });
   if (r.detail) {
     return { ok: false, detail: `cannot run ${MCP_PACKAGE}: ${r.detail}` };
   }
@@ -225,7 +263,8 @@ export function bootstrapMcp(opts) {
  * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
  */
 export function mcpDoctor(opts) {
-  const { projectRoot, env = process.env } = opts;
+  const { env = process.env } = opts;
+  const projectRoot = requireProjectRoot(opts.projectRoot, 'mcpDoctor');
   const r = runMcp(['doctor', '--project', projectRoot, '--json'], { projectRoot, env, timeout: 60000 });
   return { ok: r.ok, report: r.data, detail: r.detail ?? (r.data ? undefined : r.stderr.trim().split('\n')[0]) };
 }
@@ -235,7 +274,8 @@ export function mcpDoctor(opts) {
  * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
  */
 export function uninstallMcp(opts) {
-  const { projectRoot, env = process.env } = opts;
+  const { env = process.env } = opts;
+  const projectRoot = requireProjectRoot(opts.projectRoot, 'uninstallMcp');
   const r = runMcp(['uninstall-mcp', '--project', projectRoot, '--yes', '--json'], { projectRoot, env, timeout: 60000 });
   return { ok: r.ok, report: r.data, detail: r.detail };
 }

package/lib/migrations/001-stamp-provenance.mjs

@@ -5,9 +5,9 @@
 // What it writes: three YAML COMMENT lines at the very top of tasks.yaml and
 // architecture.yaml. Comments are inert to every consumer by contract — the
 // MCP core's parser records them positionally (`archgen_tasks{set_status}`
-// preserves them verbatim), the verifier never sees them as data, and the VS
-// Code extension port behaves identically. Additive-only: no existing key is
-// touched, nothing becomes required.
+// preserves them verbatim), the verifier never sees them as data, and every
+// other YAML consumer ignores them by the same contract. Additive-only: no
+// existing key is touched, nothing becomes required.
 //
 //   # schema_version: 1
 //   # generator: archgen v1.2.3      (version token omitted when unknowable)

package/lib/spawn-npm.js

@@ -37,12 +37,22 @@ export function npmInvocation(npmArgs, env = process.env) {
   return { command: isWin ? 'npm.cmd' : 'npm', args: npmArgs, shell: isWin };
 }
 
-/** Cross-platform `which` (PATHEXT on Windows). */
-export function whichOnPath(bin) {
+/**
+ * Cross-platform `which` (PATHEXT on Windows).
+ *
+ * The env is a PARAMETER, not an assumption: a caller may be searching a
+ * modified PATH (a test, a sandboxed HOME), and reading process.env behind
+ * its back would answer a different question than the one asked.
+ *
+ * @param {string} bin
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function whichOnPath(bin, env = process.env) {
   const exts = process.platform === 'win32'
-    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+    ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
     : [''];
-  const dirs = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+  const dirs = (env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
   for (const d of dirs) {
     for (const ext of exts) {
       const p = join(d, bin + ext);

package/lib/uninstall-project.js

@@ -2,10 +2,11 @@
 //
 // Removes exactly what archgen owns in a project: the claude symlink, the
 // managed blocks, the canonical store (ONLY when unmodified vs the vendor
-// skill — a customized store is kept with a warning), and the install
-// manifest. `.archgen/<slug>` feature folders and `.archgen/.backup/` are
-// always preserved. Parents are pruned only when left completely empty, and
-// never past the guarded .claude/.agents levels.
+// skill — a customized store is kept with a warning), the install
+// manifest, and the legacy extension runtime directory. `.archgen/<slug>`
+// feature folders and `.archgen/.backup/` are always preserved. Parents are
+// pruned only when left completely empty, and never past the guarded
+// .claude/.agents levels.
 
 import { existsSync, lstatSync, readlinkSync, rmSync, unlinkSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -36,6 +37,7 @@ function relJoin(rel) {
  * @param {string} packageRoot dir containing this CLI package (vendor source)
  * @returns {{root: string, linkRemoved: boolean, strippedBlocks: string[],
  *            storeRemoved: boolean, storeKept: boolean, manifestRemoved: boolean,
+ *            runtimeRemoved: boolean,
  *            mcpRemoved: string[], warnings: string[]}}
  */
 export function uninstallProject(projectDir, packageRoot) {
@@ -122,5 +124,23 @@ export function uninstallProject(projectDir, packageRoot) {
   const manifestRemoved = rmIfExists(join(root, relJoin(MANIFEST_REL)));
   if (manifestRemoved) pruneEmptyParents(root, dirname(MANIFEST_REL));
 
-  return { root, linkRemoved, strippedBlocks, storeRemoved, storeKept, manifestRemoved, mcpRemoved, warnings };
+  // 6. The legacy extension runtime directory. The VS Code extension wrote a
+  //    heartbeat and per-command acknowledgements under `.archgen/.runtime/`;
+  //    it is dead state now that the extension and its bridge are gone, and it
+  //    is archgen-owned, so the uninstall removes it. Feature folders and
+  //    backups beside it are untouched.
+  const runtimeRemoved = rmIfExists(join(root, '.archgen', '.runtime'));
+  if (runtimeRemoved) pruneEmptyParents(root, '.archgen/.runtime');
+
+  return {
+    root,
+    linkRemoved,
+    strippedBlocks,
+    storeRemoved,
+    storeKept,
+    manifestRemoved,
+    runtimeRemoved,
+    mcpRemoved,
+    warnings,
+  };
 }

package/lib/version-stamp.js

@@ -1,7 +1,7 @@
 // version-stamp.js — the `.archgen-version` stamp contract.
 //
-// WHY: the VS Code extension reads `<skillRoot>/.archgen-version` to tell an
-// outdated skill copy from a current one and warns non-blockingly (missing or
+// WHY: the MCP server reads `<skillRoot>/.archgen-version` to tell an
+// outdated skill copy from a current one and reports it (missing or
 // unparseable content means "unknown (legacy)" — a pre-stamp install). The
 // CLI is the only writer: every operation that lays down skill files (init,
 // global install in symlink AND --copy mode, update via its init/doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "Architecture generation & autonomous task execution for coding agents - conversational requirements in, dependency-ordered tasks out, executed wave-by-wave with verifier gates. Works with Claude Code, OpenCode, Cursor, Codex, Gemini CLI and any agentskills.io harness.",
   "license": "MIT",
   "type": "module",
@@ -38,10 +38,10 @@
   "bugs": {
     "url": "https://github.com/akashmaurya99/archgen/issues"
   },
-  "//": "vendor/skills/archgen is a full mirror of ../../skill synced by scripts/sync-vendor.mjs (run automatically via prepublishOnly). The extension ships separately as a VS Code vsix.",
+  "//": "vendor/skills/archgen is a full mirror of ../../skill synced by scripts/sync-vendor.mjs (run automatically via prepublishOnly).",
   "scripts": {
     "sync:config": "node scripts/sync-config.mjs",
-    "sync:check": "node scripts/sync-config.mjs --check",
+    "sync:check": "node scripts/sync-config.mjs --check && node scripts/sync-vendor.mjs --check",
     "sync": "node scripts/sync-config.mjs && node scripts/sync-vendor.mjs",
     "prepublishOnly": "node scripts/sync-config.mjs && node scripts/sync-vendor.mjs",
     "test": "ARCHGEN_CODEGRAPH=0 node --test test/*.test.mjs"