archgen-skill 0.0.2 → 0.0.4

package/README.md

@@ -21,13 +21,27 @@ Antigravity** — and any [agentskills.io](https://agentskills.io)-compatible ha
 
 ## Install
 
-**Prepare a project** (recommended) — copies the skill locally + writes
-`AGENTS.md` / `CLAUDE.md` pointer blocks so every harness auto-discovers it:
+**Prepare a project** (recommended) — installs ONE canonical skill copy plus
+harness bridges so every agent auto-discovers it:
 
 ```bash
 npx archgen-skill init
 ```
 
+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) |
+
+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`.
+
 **Or install globally** into every detected harness:
 
 ```bash
@@ -56,11 +70,23 @@ architecture contract, docs, ADRs, plans, and a `tasks.yaml` task graph — vers
 
 | Command | What it does |
 | --- | --- |
-| `npx archgen-skill init [dir]` | Copy the skill into `.agents/skills/archgen` + `.claude/skills/archgen` and write AGENTS.md / CLAUDE.md pointer blocks |
+| `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 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.
+
 ## Why archgen
 
 AI coding agents fail at scale for predictable reasons: plans with hidden cycles,

package/bin/archgen.mjs

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 // archgen — npm CLI for the archgen skill.
 //
-//   npx archgen-skill init            Install skill into THIS project + write
-//                               AGENTS.md / CLAUDE.md context pointers
+//   npx archgen-skill init [dir]      ONE canonical skill store + claude symlink
+//                               adapter + AGENTS.md / CLAUDE.md context pointers
+//   npx archgen-skill doctor [dir]    Verify/repair a project install (--check = report only)
 //   npx archgen-skill install         Install skill into global harness dirs
 //                               (Claude Code, OpenCode, Cursor, agentskills)
 //   npx archgen-skill uninstall       Remove globally-installed copies (manifest-based)
+//     --project [dir]           Remove archgen from a specific project instead
+//   npx archgen-skill restore          List/restore archgen backups (project + global vaults)
+//   npx archgen-skill migrate [dir]    Evolve generated-artifact formats (--check default)
 //
 // Zero dependencies. Cross-platform (Windows included — no bash required).
 
@@ -13,20 +17,60 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { installGlobal, uninstallGlobal } from '../lib/install.js';
 import { initProject } from '../lib/init.js';
+import { doctorProject } from '../lib/doctor.js';
+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 { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
+function cliVersion() {
+  return JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+}
+
+function runInitAndDoctor(dir) {
+  const r = initProject(dir, PACKAGE_ROOT);
+  console.log('  = store refreshed at ' + r.storePath);
+  doctorProject(dir, PACKAGE_ROOT, {});
+}
+
 const HELP = `archgen — architecture generation & autonomous task execution for coding agents
 
 Usage:
-  npx archgen-skill init [dir]        Prepare a project: copy the skill into
-                                .agents/skills/archgen + .claude/skills/archgen
-                                and generate AGENTS.md / CLAUDE.md pointer blocks
-                                so every agent harness auto-discovers it.
+  npx archgen-skill init [dir]        Prepare a project: create the canonical skill
+                                store at .agents/skills/archgen, symlink
+                                .claude/skills/archgen -> ../../.agents/skills/archgen,
+                                and generate AGENTS.md / CLAUDE.md pointer blocks.
+    [--force]                     proceed automatically; divergent copies are
+                                  backed up to .archgen/.backup/ (never destroyed)
+  npx archgen-skill doctor [dir]      Health-check a project install: store integrity,
+                                version stamp, claude link, managed blocks,
+                                manifest. Repairs safe issues in place.
+    [--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         Alias for install --uninstall
+  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
+                                  customized) and manifest; .archgen feature
+                                  folders and backups are preserved
+  npx archgen-skill restore           List backup snapshots across the project and
+                                  global vaults; nothing is restored by default
+    [--snapshot <ts>]             restore that snapshot (current state is backed
+                                  up first); --project <dir> / --global scope it
+  npx archgen-skill migrate [dir]     Evolve generated-artifact formats in place;
+                                  --check (default) lists pending migrations
+    [--apply]                     apply them (every touched file is backed up)
+    [--migration <id>]            target a single migration
+  npx archgen-skill update [dir]      Check npm for a newer archgen-skill, upgrade
+                                  the global install when outdated, then
+                                  re-init this project + doctor against the
+                                  new version. No-op when already latest.
+  npx archgen-skill --version         Print the running CLI version
   npx archgen-skill --help            This help
 
 Docs: https://github.com/akashmaurya99/archgen`;
@@ -40,19 +84,40 @@ function flag(name) {
   return true;
 }
 
+function positionalDir() {
+  return rest[0] ? resolve(rest[0]) : process.cwd();
+}
+
 try {
   switch (cmd) {
     case 'init': {
-      const dir = rest[0] ? resolve(rest[0]) : process.cwd();
-      const r = initProject(dir, PACKAGE_ROOT);
-      console.log('archgen: skill installed into project');
-      for (const p of r.skillCopies) console.log('  + ' + p);
+      flag('--force');
+      const r = initProject(positionalDir(), PACKAGE_ROOT);
+      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');
+      else if (r.claudeLink === 'existing') console.log('  = link  .claude/skills/archgen (already points at the store)');
+      else if (r.claudeLink === 'migrated') console.log('  ~ link  .claude/skills/archgen migrated from copy to symlink');
+      else if (r.claudeLink === 'kept-divergent') console.log('  ! kept  .claude/skills/archgen (divergent - left untouched)');
+      else console.log('  ! skip  .claude/skills/archgen (symlink unavailable)');
+      for (const b of r.backups) console.log('  ~ backup ' + b + ' (previous store moved aside)');
       for (const f of r.contextFiles) {
         console.log(`  ${r.createdContextFiles.includes(f) ? 'created' : 'updated'} ${f} (archgen pointer block)`);
       }
+      for (const w of r.warnings) console.log('  note: ' + w);
       console.log('\nNext: open this project in your agent and say "generate architecture" or "add feature X".');
       break;
     }
+    case 'doctor': {
+      const check = flag('--check');
+      const r = doctorProject(positionalDir(), 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;
+      console.log(`Summary: ${t.OK} ok, ${t.FIXED} fixed, ${t['WOULD-FIX']} would-fix, ${t.WARN} warning(s), ${t.FAIL} failure(s)`);
+      if (r.failures > 0) process.exitCode = 1;
+      break;
+    }
     case 'install': {
       const copy = flag('--copy');
       if (flag('--uninstall')) { uninstall(); break; }
@@ -64,7 +129,76 @@ try {
       break;
     }
     case 'uninstall': {
-      uninstall();
+      if (flag('--project')) {
+        const r = uninstallProject(positionalDir(), 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 w of r.warnings) console.log('  note: ' + w);
+        console.log('  .archgen feature folders and backups are preserved.');
+      } else {
+        uninstall();
+      }
+      break;
+    }
+    case 'restore': {
+      // restoreMain parses its own flags and returns its own exit code.
+      process.exitCode = await restoreMain(rest);
+      break;
+    }
+    case 'migrate': {
+      // migrateMain parses its own args and returns its own exit code
+      // (0 ok, 1 apply failure, 2 usage error).
+      process.exitCode = await migrateMain(rest);
+      break;
+    }
+    case 'update': {
+      const dir = positionalDir();
+      const current = cliVersion();
+      console.log('archgen update — running v' + current + ', checking npm registry…');
+      const latest = fetchLatestVersion('archgen-skill');
+      if (!latest) {
+        console.log('  ! could not reach the npm registry (offline?). Nothing changed.');
+        break;
+      }
+      const cmp = compareSemver(latest, current);
+      if (cmp === 0) {
+        console.log('  = already on the latest published version (' + latest + ').');
+        console.log('  Refreshing this project against it anyway…');
+        runInitAndDoctor(dir);
+        break;
+      }
+      if (cmp < 0) {
+        console.log('  ↑ running v' + current + ' is newer than npm (' + latest + ') — not published yet.');
+        console.log('  Refreshing this project against the running version…');
+        runInitAndDoctor(dir);
+        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' });
+      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();
+      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' });
+      spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
+      break;
+    }
+    case '--version': case '-v': {
+      console.log(cliVersion());
       break;
     }
     case '--help': case '-h': case undefined: {

package/lib/block.js

@@ -4,17 +4,84 @@
 // archgen writes lives between START/END markers; re-runs replace the block
 // in place, uninstalls strip it, and anything the user wrote outside the
 // markers is untouched.
+//
+// AGENTS.md carries the full pointer block with an embedded features registry
+// (between FEATURES_START/FEATURES_END). CLAUDE.md carries a one-line
+// `@AGENTS.md` bridge inside the same managed markers.
+//
+// Block provenance: the FIRST line inside every managed block is a machine-
+// readable `<!-- archgen:block vX.Y.Z -->` stamp sourced from the canonical
+// config (lib/config.js loadConfig()). upsertBlock normalizes every block it
+// writes to carry the CURRENT stamp, so legacy unversioned blocks upgrade in
+// place on the next init/doctor pass and detectBlockVersion() lets doctor
+// report stale formats precisely.
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { loadConfig } from './config.js';
+
+// Markers + block-format version come from the single source of truth.
+// Module-level load is safe: config resolution is module-relative and
+// deterministic, and a missing/corrupt config fails loudly at import by design.
+const CONFIG = loadConfig();
+
+export const START = CONFIG.markers.start;
+export const END = CONFIG.markers.end;
+export const FEATURES_START = CONFIG.markers.featuresStart;
+export const FEATURES_END = CONFIG.markers.featuresEnd;
+
+/** The exact provenance line rendered as the first line of a managed block. */
+export function provenanceLine() {
+  return '<!-- archgen:block v' + CONFIG.version + ' -->';
+}
 
-export const START = '<!-- archgen:start (managed block - do not edit between markers) -->';
-export const END = '<!-- archgen:end -->';
+const PROVENANCE_LINE_RE = /^<!--\s*archgen:block\s+v[^\s>]*\s*-->$/;
+
+/**
+ * Normalize an archgen-rendered block so the current provenance line sits
+ * immediately after START: stale/differently-versioned stamps are dropped and
+ * the canonical one inserted. Blocks not beginning with START pass through
+ * untouched. Preserves the block's own CRLF/LF convention.
+ */
+function injectProvenance(block) {
+  if (typeof block !== 'string' || !block.startsWith(START)) return block;
+  const eol = block.includes('\r\n') ? '\r\n' : '\n';
+  const lines = block.split(/\r?\n/).filter((l, i) => i === 0 || !PROVENANCE_LINE_RE.test(l.trim()));
+  lines.splice(1, 0, provenanceLine());
+  return lines.join(eol);
+}
+
+/**
+ * Detect the provenance stamp of a managed block inside file content.
+ * @param {string} content file contents (BOM/CRLF tolerated)
+ * @returns {{present: boolean, version: string|null}} present=true when a
+ *   provenance line is found as the first non-empty line after START; version
+ *   is the stamped semver, or null when the line is malformed.
+ */
+export function detectBlockVersion(content) {
+  const src = String(content ?? '');
+  const s = src.indexOf(START);
+  if (s === -1) return { present: false, version: null };
+  const e = src.indexOf(END, s + START.length);
+  const head = src.slice(s + START.length, e === -1 ? undefined : e);
+  for (const line of head.split(/\r?\n/)) {
+    const t = line.trim();
+    if (t === '') continue;
+    if (!t.includes('archgen:block')) return { present: false, version: null };
+    const m = /^<!--\s*archgen:block\s+v([^\s>]+)\s*-->$/.exec(t);
+    return { present: true, version: m ? m[1] : null };
+  }
+  return { present: false, version: null };
+}
 
 /**
  * Render the archgen pointer block for a project.
  * @param {string} skillRelPath relative path to the skill dir from project root
+ * @param {string} eol line ending used to join the block lines
  */
-export function renderBlock(skillRelPath = '.agents/skills/archgen') {
+export function renderBlock(skillRelPath = '.agents/skills/archgen', eol = '\n') {
   return [
     START,
+    provenanceLine(),
     '# ArchGen - Architecture Generation & Autonomous Task Execution',
     '',
     'This project uses the **archgen** skill, installed at `' + skillRelPath + '/`.',
@@ -32,27 +99,56 @@ export function renderBlock(skillRelPath = '.agents/skills/archgen') {
     '- Generated artifacts live ONLY under `.archgen/<slug>/`',
     '- Never hand-edit task statuses - use `scripts/set-status.mjs` (comment-safe)',
     '- Two gates before any execution: verifier approval, then human approval',
+    '',
+    '## Features registry',
+    '',
+    FEATURES_START,
+    '| Feature | Status | Updated |',
+    '| --- | --- | --- |',
+    FEATURES_END,
     END,
-  ].join('\n');
+  ].join(eol);
+}
+
+/**
+ * Canonical AGENTS.md managed-block text (LF-joined, provenance included).
+ * Integration contract: install.sh's heredoc is regenerated byte-identically
+ * from this function's output — do not let the two drift.
+ */
+export function renderManagedBlockText() {
+  return renderBlock();
+}
+
+/**
+ * Canonical CLAUDE.md bridge text (LF-joined, provenance included).
+ * Same integration contract as renderManagedBlockText().
+ */
+export function renderClaudeBridgeText() {
+  return [START, provenanceLine(), '@AGENTS.md', END].join('\n');
 }
 
 /**
  * Insert or replace the managed block inside existing file content.
  * @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
  */
-export function upsertBlock(existing, block) {
+export function upsertBlock(existing, block, eol = '\n') {
+  // Every write carries the CURRENT provenance stamp regardless of what the
+  // caller rendered — this is what upgrades legacy unversioned blocks in place.
+  const fresh = injectProvenance(block);
   const trimmed = existing ?? '';
   const startIdx = trimmed.indexOf(START);
   const endIdx = trimmed.indexOf(END);
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    return trimmed.slice(0, startIdx) + block + trimmed.slice(endIdx + END.length);
+    return trimmed.slice(0, startIdx) + fresh + trimmed.slice(endIdx + END.length);
   }
   if (startIdx !== -1 || endIdx !== -1) {
     throw new Error('found only one archgen marker - fix or remove it manually');
   }
-  if (trimmed.trim() === '') return block + '\n';
-  return trimmed.replace(/\n*$/, '\n\n') + block + '\n';
+  if (trimmed.trim() === '') return fresh + eol;
+  const core = trimmed.replace(/(?:\r?\n)+$/, '');
+  return core + eol + eol + fresh + eol;
 }
 
 /**
@@ -69,3 +165,96 @@ export function stripBlock(existing) {
   out = out.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
   return { content: out, hadBlock: true };
 }
+
+function splitBom(raw) {
+  const bom = raw.charCodeAt(0) === 0xfeff;
+  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();
+  writeFileSync(tmp, data);
+  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.
+ * @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) {
+  const existed = existsSync(absPath);
+  const raw = existed ? readFileSync(absPath, 'utf8') : '';
+  const { bom, body } = splitBom(raw);
+  const eol = body.includes('\r\n') ? '\r\n' : '\n';
+  const next = upsertBlock(body, blockLines.join(eol), eol);
+  atomicWrite(absPath, (bom ? '\uFEFF' : '') + next);
+  return existed;
+}
+
+/**
+ * True when the file already contains a trimmed `@AGENTS.md` line anywhere
+ * (BOM- and CRLF-tolerant).
+ */
+export function importsAgents(absPath) {
+  let raw = '';
+  try { raw = readFileSync(absPath, 'utf8'); } catch { return false; }
+  const { body } = splitBom(raw);
+  return body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
+}
+
+/** Strip the managed block from a file on disk, preserving BOM. */
+export function stripManagedFile(absPath) {
+  let raw = '';
+  try { raw = readFileSync(absPath, 'utf8'); } catch { return { hadBlock: false }; }
+  const { bom, body } = splitBom(raw);
+  const { content, hadBlock } = stripBlock(body);
+  if (hadBlock) writeFileSync(absPath, (bom ? '\uFEFF' : '') + content);
+  return { hadBlock };
+}
+
+function renderRow(row) {
+  const cells = Array.isArray(row)
+    ? row.map(String)
+    : [row.feature ?? row.name ?? '', row.status ?? '', row.updated ?? ''].map(String);
+  return '| ' + cells.join(' | ') + ' |';
+}
+
+/**
+ * Replace the content between the archgen:features markers in a file with the
+ * registry table (header rows plus `rows`). When the markers are missing but
+ * the managed block exists, the registry section is inserted before its END
+ * marker. Never touches anything outside the markers.
+ * @param {string} fileAbsPath absolute path to AGENTS.md-style file
+ * @param {Array<string[]|{feature:string,status:string,updated:string}>} rows
+ * @returns {string} the new file content
+ */
+export function upsertFeaturesRegistry(fileAbsPath, rows = []) {
+  const raw = readFileSync(fileAbsPath, 'utf8');
+  const table = [
+    '| Feature | Status | Updated |',
+    '| --- | --- | --- |',
+    ...rows.map(renderRow),
+  ].join('\n');
+  const s = raw.indexOf(FEATURES_START);
+  const e = raw.indexOf(FEATURES_END);
+  let next;
+  if (s !== -1 && e !== -1 && e > s) {
+    next = raw.slice(0, s + FEATURES_START.length) + '\n' + table + '\n' + raw.slice(e);
+  } else if (s === -1 && e === -1) {
+    const bStart = raw.indexOf(START);
+    const bEnd = raw.indexOf(END);
+    if (bStart === -1 || bEnd === -1 || bEnd < bStart) {
+      throw new Error('no archgen managed block - cannot place features registry');
+    }
+    const section = '\n## Features registry\n\n' + FEATURES_START + '\n' + table + '\n' + FEATURES_END + '\n';
+    next = raw.slice(0, bEnd) + section + raw.slice(bEnd);
+  } else {
+    throw new Error('found only one archgen:features marker - fix or remove it manually');
+  }
+  if (next !== raw) writeFileSync(fileAbsPath, next);
+  return next;
+}

package/lib/config.js

@@ -0,0 +1,96 @@
+// config.js — loader for the single-source-of-truth archgen.config.json.
+//
+// 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;
+// 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).
+//
+// Resolution is module-relative (cwd-independent), tried in order:
+//   1. ../../../archgen.config.json                  — monorepo checkout
+//   2. ../vendor/skills/archgen/archgen.config.json  — published package layout
+// The first readable candidate wins; a candidate that exists but cannot be
+// parsed/validated fails LOUDLY rather than silently falling through to a
+// possibly stale copy. Cached per process.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // packages/cli/lib
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+/** Candidate canonical-config paths for a given lib directory. */
+export function configCandidates(baseDir = HERE) {
+  return [
+    resolve(baseDir, '../../../archgen.config.json'),
+    resolve(baseDir, '../vendor/skills/archgen/archgen.config.json'),
+  ];
+}
+
+/**
+ * Parse + validate raw config JSON text.
+ * @param {string} text file contents
+ * @param {string} sourcePath path used in error messages
+ */
+export function parseConfig(text, sourcePath) {
+  let cfg;
+  try {
+    cfg = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`cannot load ${sourcePath}: invalid JSON (${e.message})`);
+  }
+  const bad = (msg) => new Error(`cannot load ${sourcePath}: ${msg}`);
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw bad('expected a JSON object');
+  if (typeof cfg.version !== 'string' || !SEMVER_RE.test(cfg.version)) {
+    throw bad(`"version" must be MAJOR.MINOR.PATCH, got ${JSON.stringify(cfg.version ?? null)}`);
+  }
+  if (typeof cfg.skillName !== 'string' || !cfg.skillName) throw bad('"skillName" must be a non-empty string');
+  const m = cfg.markers;
+  if (!m || typeof m !== 'object') throw bad('"markers" object is required');
+  for (const k of ['start', 'end', 'featuresStart', 'featuresEnd']) {
+    if (typeof m[k] !== 'string' || !m[k]) throw bad(`"markers.${k}" must be a non-empty string`);
+  }
+  const f = cfg.files;
+  if (!f || typeof f !== 'object') throw bad('"files" object is required');
+  for (const k of ['stamp', 'projectManifest', 'globalManifest', 'backupDir']) {
+    if (typeof f[k] !== 'string' || !f[k]) throw bad(`"files.${k}" must be a non-empty string`);
+  }
+  return cfg;
+}
+
+/**
+ * Resolve + parse the canonical config relative to `baseDir` (a lib dir).
+ * @returns {object} the validated config object
+ */
+export function loadConfigFrom(baseDir) {
+  const candidates = configCandidates(baseDir);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    let text = '';
+    try {
+      text = readFileSync(p, 'utf8');
+    } catch (e) {
+      throw new Error(`cannot load ${p}: ${e.message}`);
+    }
+    return parseConfig(text, p);
+  }
+  throw new Error(
+    'archgen config not found. Expected one of:\n' +
+      candidates.map((c) => '  - ' + c).join('\n') +
+      '\nIn a repository checkout archgen.config.json lives at the repo root; ' +
+      'in the published package it is vendored at vendor/skills/archgen/. ' +
+      'Run `npm run sync:config` inside packages/cli to (re)generate both.',
+  );
+}
+
+let cached = null;
+
+/** Load the canonical config for this process (cached after first call). */
+export function loadConfig() {
+  if (!cached) cached = loadConfigFrom(HERE);
+  return cached;
+}