vigiles 3.0.0 → 4.0.1

package/dist/cli.js

@@ -6,7 +6,7 @@
  * Commands:
  *   vigiles init            — scaffold a spec from scratch
  *   vigiles compile         — compile .spec.ts → .md with linter verification
- *   vigiles audit           — verify hashes, report coverage, detect duplicates
+ *   vigiles lint            — verify hashes, report coverage, detect duplicates
  *   vigiles generate-types  — emit .d.ts with types from project state
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -28,6 +28,7 @@ const proofs_js_1 = require("./core/proofs.js");
 const inline_js_1 = require("./core/inline.js");
 const frontmatter_js_1 = require("./core/frontmatter.js");
 const generate_schema_js_1 = require("./core/generate-schema.js");
+const compose_js_1 = require("./core/compose.js");
 const compile_generator_js_1 = require("./core/compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
@@ -35,7 +36,7 @@ const refs_js_1 = require("./core/refs.js");
 const mcp_js_1 = require("./core/mcp.js");
 const skill_runtime_js_1 = require("./adapters/claude-code/skill-runtime.js");
 const linters_js_1 = require("./core/linters.js");
-const harness_test_js_1 = require("./adapters/claude-code/harness-test.js");
+const harness_test_js_1 = require("./harness-test.js");
 const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
 const integrity_js_1 = require("./core/integrity.js");
 const coverage_js_1 = require("./core/coverage.js");
@@ -51,7 +52,11 @@ const IGNORE_NODE_MODULES = ["node_modules/**"];
 function findSpecs(pattern) {
     const glob = pattern ?? "**/*.md.spec.ts";
     return (0, glob_1.globSync)(glob, {
-        ignore: [...IGNORE_NODE_MODULES, "dist/**"],
+        // `dot: true` so specs that live in a sync tool's source slot (e.g.
+        // `.ruler/AGENTS.md.spec.ts`, the redirect target) are discovered by
+        // compile/audit/the recompile hook — not just root-level specs.
+        dot: true,
+        ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
         cwd: process.cwd(),
     });
 }
@@ -400,7 +405,7 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
     const allSpecs = findSpecs();
     // If audit was invoked with explicit file arguments, only scan the specs
     // for those files — otherwise an unrelated duplicate elsewhere in the
-    // repo would fail a targeted CI check (e.g. `vigiles audit path/foo.md`).
+    // repo would fail a targeted CI check (e.g. `vigiles lint path/foo.md`).
     //
     // Resolve each requested file to its real source spec by reading the
     // compiled-from header. Multi-target projects compile one spec to
@@ -989,6 +994,34 @@ function discover(silent = false) {
     }
     return { enabled: totalEnabled, documented: totalDocumented };
 }
+/** This package's own version (from the installed package.json). */
+function getVersion() {
+    try {
+        // dist/cli.js → ../package.json (the package root).
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(__dirname, "..", "package.json"), "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** The dependency range to pin `vigiles` to (the running CLI's major, e.g.
+ * `^3`). Falls back to `latest` for the unreleased dev placeholder version. */
+function vigilesDepSpec() {
+    const major = parseInt(getVersion(), 10);
+    return Number.isFinite(major) && major > 0 ? `^${String(major)}` : "latest";
+}
+/** True when the file's first line carries a vigiles integrity hash (i.e. it
+ * is a compiled artifact we own, safe to overwrite — not hand-written prose). */
+function targetHasHash(absPath) {
+    try {
+        const first = (0, node_fs_1.readFileSync)(absPath, "utf-8").split("\n", 1)[0];
+        return first.includes("vigiles:sha256");
+    }
+    catch {
+        return false;
+    }
+}
 function init(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
@@ -997,7 +1030,12 @@ function init(args) {
         console.log(`${specPath} already exists.`);
         return;
     }
-    const targetLine = target !== "CLAUDE.md" ? `\n  target: "${target}",` : "";
+    // The compiled output is derived from the spec FILE path; the spec's `target`
+    // field is the h1 + the name the compiler validates against, so it must be the
+    // bare filename even when the spec lives in a subdir (e.g. a sync tool's
+    // `.ruler/AGENTS.md.spec.ts` source slot → target "AGENTS.md").
+    const targetName = (0, node_path_1.basename)(target);
+    const targetLine = targetName !== "CLAUDE.md" ? `\n  target: "${targetName}",` : "";
     const template = `import { claude, enforce, guidance } from "vigiles/spec";
 
 export default claude({${targetLine}
@@ -1031,19 +1069,22 @@ export default claude({${targetLine}
   },
 });
 `;
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), template);
+    const specAbs = (0, node_path_1.resolve)(process.cwd(), specPath);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(specAbs), { recursive: true });
+    (0, node_fs_1.writeFileSync)(specAbs, template);
     console.log(`Created ${specPath} — edit it and run \`vigiles compile\`.`);
 }
 // ---------------------------------------------------------------------------
 // Setup wizard
 // ---------------------------------------------------------------------------
 /** Full GitHub Actions workflow that wires the production `zernie/vigiles@v1`
- * Action (Pillar 1) and, when Pillar 2 is set up, a deterministic harness job. */
+ * Action (lint pillar) and, when the test pillar is set up, a deterministic
+ * harness job. */
 function vigilesWorkflow(plan) {
     const harness = plan.test
         ? `
   harness:
-    # Pillar 2 — run your *.harness.{mjs,ts} tests against the real agent CLI and
+    # Test pillar — run your *.harness.{mjs,ts} tests against the real agent CLI and
     # a scripted mock model (deterministic, no API key). Drop this job if you only
     # author runHook unit tests, or keep it for the deterministic tier.
     runs-on: ubuntu-latest
@@ -1068,9 +1109,9 @@ permissions:
   pull-requests: write # for the sticky PR comment
 
 jobs:
-  verify:
-    # Pillar 1 — verify the references in your instruction files (composite Action
-    # over the published CLI). Posts a sticky PR comment + a \`valid\` output.
+  lint:
+    # Lint pillar — verify the references in your instruction files (composite
+    # Action over the published CLI). Posts a sticky PR comment + a \`valid\` output.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -1080,18 +1121,46 @@ jobs:
       - uses: zernie/vigiles@v1
 ${harness}`;
 }
-/** Create `.github/workflows/vigiles.yml` (or note it already exists). */
+/**
+ * Detect a workflow that drives vigiles through an OLD API — a bare `npx vigiles`
+ * (a no-op help screen in v2+) rather than the `zernie/vigiles@` Action or a real
+ * subcommand (`audit`/`test`/…). Upgrading users whose workflow predates the
+ * subcommand split silently lose CI validation, so we flag it loudly.
+ */
+function workflowUsesStaleApi(content) {
+    if (content.includes("zernie/vigiles@"))
+        return false; // uses the Action — fine
+    if (!/\bvigiles\b/.test(content))
+        return false; // not a vigiles workflow
+    const hasModernCmd = /vigiles\s+(lint|test|eval|compile|scan|generate-types|generate-schema|init)\b/.test(content);
+    return !hasModernCmd;
+}
+/** Create `.github/workflows/vigiles.yml`. Returns the files it wrote (for the
+ * commit hint). An existing workflow is never clobbered, but a STALE one (old
+ * bare-`npx vigiles` API) is reported loudly instead of silently skipped. */
 function wireGha(plan) {
     const dir = (0, node_path_1.resolve)(process.cwd(), ".github", "workflows");
     const path = (0, node_path_1.resolve)(dir, "vigiles.yml");
     if ((0, node_fs_1.existsSync)(path)) {
-        console.log("✓ .github/workflows/vigiles.yml already exists");
-        return;
+        const content = (0, node_fs_1.readFileSync)(path, "utf-8");
+        if (workflowUsesStaleApi(content)) {
+            console.log("⚠ .github/workflows/vigiles.yml is STALE — it runs a bare `npx vigiles`,\n" +
+                "  which is a no-op help screen now. Replace its run step with the Action +\n" +
+                "  the test job (CI is otherwise silently not validating anything):\n" +
+                "    - uses: zernie/vigiles@v1   # lint pillar — verify references\n" +
+                "    - run: npx vigiles test     # pillar 2 — harness tests\n" +
+                "  Or delete the file and re-run `vigiles init` to regenerate it.");
+        }
+        else {
+            console.log("✓ .github/workflows/vigiles.yml already exists (up to date)");
+        }
+        return [];
     }
     if (!(0, node_fs_1.existsSync)(dir))
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
     (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan));
     console.log("✓ Created .github/workflows/vigiles.yml (uses zernie/vigiles@v1)");
+    return [".github/workflows/vigiles.yml"];
 }
 const STARTER_HARNESS = `/**
  * Starter harness test (Pillar 2) — scaffolded by \`vigiles init\`.
@@ -1127,15 +1196,17 @@ assert.ok(!allowed.blocked, "guard should allow a safe command");
 
 console.log("\\u2713 hook blocks rm -rf / and allows safe commands");
 `;
-/** Pillar 2 — scaffold a starter harness test the user adapts to their hooks. */
+/** Pillar 2 — scaffold a starter harness test the user adapts to their hooks.
+ * Returns the files it wrote (for the commit hint). */
 function scaffoldPillar2() {
     const path = (0, node_path_1.resolve)(process.cwd(), "vigiles.harness.mjs");
     if ((0, node_fs_1.existsSync)(path)) {
         console.log("✓ vigiles.harness.mjs already exists");
-        return;
+        return [];
     }
     (0, node_fs_1.writeFileSync)(path, STARTER_HARNESS);
-    console.log("✓ Scaffolded vigiles.harness.mjs — Pillar 2 starter (npm i -D vigiles && npx vigiles test)");
+    console.log("✓ Scaffolded vigiles.harness.mjs — Pillar 2 starter (npx vigiles test)");
+    return ["vigiles.harness.mjs"];
 }
 /** Interactive prompts (TTY only): which pillars, CI, plugin. */
 async function promptSetup() {
@@ -1151,12 +1222,12 @@ async function promptSetup() {
     });
     const isYes = (s) => /^y(es)?$/i.test(s);
     try {
-        const pillars = (await ask("Set up which pillars? [both/verify/test] (both): ", "both")).toLowerCase();
+        const pillars = (await ask("Set up which pillars? [both/lint/test] (both): ", "both")).toLowerCase();
         const gha = isYes(await ask("Wire CI (GitHub Action)? [Y/n]: ", "y"));
         const plugin = isYes(await ask("Install the Claude Code plugin (hooks + skills)? [Y/n]: ", "y"));
         return {
-            verify: pillars !== "test",
-            test: pillars !== "verify",
+            lint: pillars !== "test",
+            test: pillars !== "lint" && pillars !== "verify",
             gha,
             plugin,
         };
@@ -1240,55 +1311,118 @@ function detectProject() {
         hasClaude: (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, ".claude")),
     };
 }
-/** Pillar 1 — specs + types + schema + compile. Returns the spec targets
- * created/found (empty when every existing file needs migration instead). */
-async function setupPillar1(detected, targetValue) {
-    // Determine targets
-    let targets;
-    if (targetValue) {
-        targets = [targetValue];
-    }
-    else {
-        const needsSpec = detected.instructionFiles.filter((f) => !f.hasSpec);
-        if (needsSpec.length > 0) {
-            for (const f of needsSpec) {
-                console.log(`Found ${f.path} without a spec. Migrate with the migrate-to-spec skill`);
-                console.log(`  or create a blank spec: npx vigiles init --target=${f.path}\n`);
-            }
-            const hasAnySpec = detected.instructionFiles.some((f) => f.hasSpec);
-            if (!hasAnySpec &&
-                needsSpec.length === detected.instructionFiles.length) {
-                // ALL existing files need migration — don't create new specs.
-                console.log("Use the migration skill: npx skills add zernie/vigiles\n");
-                return [];
-            }
-        }
-        targets = ["CLAUDE.md"];
-        const hasAgentsMd = detected.instructionFiles.some((f) => f.path === "AGENTS.md");
-        const hasCodex = detected.agents.includes("Codex / GitHub Copilot") || hasAgentsMd;
-        if (hasCodex && !hasAgentsMd)
-            targets.push("AGENTS.md");
+/** The instruction-file targets Pillar 1 will create specs for — the harness's
+ * native instruction file (CLAUDE.md for Claude Code, AGENTS.md for Codex),
+ * plus any existing instruction file that lacks a spec. */
+function determineTargets(detected, targetValue, harnesses) {
+    if (targetValue)
+        return [targetValue];
+    const targets = [];
+    if (harnesses.includes("claude"))
+        targets.push("CLAUDE.md");
+    if (harnesses.includes("codex"))
+        targets.push("AGENTS.md");
+    if (targets.length === 0)
+        targets.push("CLAUDE.md");
+    // Any existing instruction file without a spec also gets one.
+    for (const f of detected.instructionFiles) {
+        if (!f.hasSpec && !targets.includes(f.path))
+            targets.push(f.path);
     }
-    // Create specs
+    return targets;
+}
+/**
+ * When CLAUDE.md and AGENTS.md are ONE artifact — a symlink, or kept
+ * byte-identical by rulesync/Ruler — collapse them to a single canonical spec
+ * target. Two specs would fight over one file and collide on the integrity hash
+ * (see the "Compose With Sync Tools" rule). The mirror is distributed from the
+ * canonical, not compiled separately.
+ */
+function collapseMirroredTargets(targets, mirror) {
+    if (!mirror)
+        return targets;
+    // The compile source slot: the real file for a symlink, else CLAUDE.md (the
+    // one Claude Code reads natively; the sync tool fans out to AGENTS.md).
+    const canonical = mirror.kind === "symlink"
+        ? (mirror.realTarget ?? "CLAUDE.md")
+        : "CLAUDE.md";
+    const mirrored = mirror.files.find((f) => f !== canonical);
+    if (!mirrored)
+        return targets;
+    if (!targets.includes(canonical) && !targets.includes(mirrored)) {
+        return targets; // neither file is a target — nothing to collapse
+    }
+    const collapsed = targets.filter((t) => t !== mirrored);
+    if (!collapsed.includes(canonical))
+        collapsed.push(canonical);
+    console.log(`Note: CLAUDE.md and AGENTS.md are one artifact (${mirror.kind}). ` +
+        `Scaffolding a single spec for ${canonical}; ${mirrored} is its mirror ` +
+        `(don't add a second spec — it would collide on the integrity hash).`);
+    return collapsed;
+}
+/**
+ * When a detected rule-sync tool (rulesync / Ruler) regenerates a file vigiles
+ * would compile to, REDIRECT the compile target to the tool's source slot
+ * (`.ruler/AGENTS.md`, `.rulesync/rules/vigiles.md`). vigiles compiles upstream;
+ * the tool distributes to CLAUDE.md/AGENTS.md/Cursor/… — so the integrity hash
+ * never collides with the tool's output (the "Compose With Sync Tools" rule).
+ */
+function redirectSyncToolTargets(cwd, targets) {
+    const collisions = (0, compose_js_1.composeCollisions)(cwd, targets);
+    if (collisions.length === 0)
+        return targets;
+    const slotFor = new Map(collisions.map((c) => [c.target, c.redirectTo]));
+    const out = [];
+    for (const t of targets) {
+        const redirected = slotFor.get(t) ?? t;
+        if (!out.includes(redirected))
+            out.push(redirected);
+    }
+    const tool = collisions[0].tool;
+    const slots = [...new Set(collisions.map((c) => c.redirectTo))].join(", ");
+    const from = [...slotFor.keys()].join(", ");
+    console.log(`Note: ${tool} detected — scaffolding the spec to compile into its source ` +
+        `slot (${slots}) instead of ${from}, so ${tool} distributes it without ` +
+        `staling the integrity hash.`);
+    return out;
+}
+/** Pillar 1 — specs + types + schema + compile. Scaffolds a spec for every
+ * instruction file (so `--lint` always delivers a spec), but never compiles
+ * OVER a hand-written file — that is left to the migrate-to-spec skill. */
+async function setupPillar1(detected, targetValue, harnesses) {
+    const cwd = process.cwd();
+    const written = [];
+    const needsMigration = [];
+    // An explicit --target is honoured as-is; otherwise collapse a CLAUDE.md⇄
+    // AGENTS.md mirror (symlink or synced) to one canonical spec, then redirect
+    // into a sync tool's source slot when one would own the output.
+    const targets = targetValue
+        ? determineTargets(detected, targetValue, harnesses)
+        : redirectSyncToolTargets(cwd, collapseMirroredTargets(determineTargets(detected, targetValue, harnesses), (0, compose_js_1.detectInstructionMirror)(cwd)));
+    // Create specs (blank). An existing hand-written target keeps its content —
+    // we scaffold the spec but flag it for migration rather than clobbering it.
     for (const target of targets) {
         const specPath = `${target}.spec.ts`;
-        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), specPath))) {
+        const targetExists = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, target));
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, specPath))) {
             console.log(`✓ ${specPath} already exists`);
         }
-        else if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), target))) {
-            console.log(`⚠ ${target} exists without spec — migrate with migrate-to-spec skill`);
-        }
         else {
-            init(["--target=" + target]);
+            init(["--target=" + target]); // prints "Created …"
+            written.push(specPath);
+        }
+        if (targetExists && !targetHasHash((0, node_path_1.resolve)(cwd, target))) {
+            needsMigration.push(target);
+            console.log(`  ${target} already has content — port it into the spec with the migrate-to-spec skill, then \`vigiles compile\`.`);
         }
     }
-    // Generate types + schema
+    // Generate types + schema.
     console.log("\nScanning linters and project files...");
-    const typesResult = (0, generate_types_js_1.generateTypes)({ basePath: process.cwd() });
-    const outDir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+    const typesResult = (0, generate_types_js_1.generateTypes)({ basePath: cwd });
+    const outDir = (0, node_path_1.resolve)(cwd, ".vigiles");
     if (!(0, node_fs_1.existsSync)(outDir))
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), ".vigiles/generated.d.ts"), typesResult.dts);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, ".vigiles/generated.d.ts"), typesResult.dts);
     for (const l of typesResult.linters) {
         console.log(`  ${l.linter}: ${String(l.rules.length)} rules`);
     }
@@ -1296,83 +1430,132 @@ async function setupPillar1(detected, targetValue) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
     console.log("✓ Generated .vigiles/generated.d.ts");
+    written.push(".vigiles/generated.d.ts");
     const schemaResult = (0, generate_schema_js_1.generateSchema)({
-        basePath: process.cwd(),
+        basePath: cwd,
         linters: (0, validate_js_1.loadConfig)().linters,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), ".vigiles/schema.json"), schemaResult.json);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, ".vigiles/schema.json"), schemaResult.json);
     console.log("✓ Generated .vigiles/schema.json (YAML-LSP frontmatter schema)");
-    // Compile specs
+    written.push(".vigiles/schema.json");
+    // Compile — but only specs whose target is greenfield or already ours. A
+    // freshly-scaffolded blank spec over an existing hand-written file is skipped
+    // so we never overwrite the user's instructions with an empty compile.
     console.log("\nCompiling specs...");
-    const specs = findSpecs();
+    const specs = findSpecs().filter((s) => {
+        const tf = (0, node_path_1.resolve)(cwd, s.replace(/\.spec\.ts$/, ""));
+        return !(0, node_fs_1.existsSync)(tf) || targetHasHash(tf);
+    });
     if (specs.length > 0)
         await compile(specs, (0, validate_js_1.loadConfig)());
-    return targets;
+    return { specTargets: targets, written, needsMigration };
 }
-/** Install the Claude Code plugin (hooks + skills). Returns whether the
- * fallback wrote `.claude/settings.json` (for the commit hint). */
-function installPlugin() {
+/** Whether a harness binary (`claude`, `codex`) is on PATH. */
+function harnessBinaryPresent(bin) {
     try {
         const { execSync: exec } = require("node:child_process");
-        exec("npx skills add zernie/vigiles", {
-            cwd: process.cwd(),
-            stdio: ["pipe", "pipe", "pipe"],
-            timeout: 30000,
-        });
-        console.log("✓ Installed vigiles plugin (hooks + skills) via skills CLI");
-        return false;
+        exec(`${bin} --version`, { stdio: "ignore", timeout: 10000 });
+        return true;
     }
     catch {
-        // skills CLI not available — fall back to direct hook installation.
-    }
-    const settingsDir = (0, node_path_1.resolve)(process.cwd(), ".claude");
-    const settingsPath = (0, node_path_1.resolve)(settingsDir, "settings.json");
-    if (!(0, node_fs_1.existsSync)(settingsDir))
-        (0, node_fs_1.mkdirSync)(settingsDir, { recursive: true });
-    let settings = {};
-    if ((0, node_fs_1.existsSync)(settingsPath)) {
-        try {
-            settings = JSON.parse((0, node_fs_1.readFileSync)(settingsPath, "utf-8"));
+        return false;
+    }
+}
+/**
+ * Install vigiles's skills/hooks for the chosen harness(es) via the per-harness
+ * `planPluginInstall` decision — Claude Code through the GLOBAL plugin
+ * marketplace (nothing vendored into the repo), Codex via AGENTS.md-direct (no
+ * global store). The decision is pure and unit-tested; this is the thin IO.
+ */
+function installPlugins(harnesses) {
+    const { execSync: exec } = require("node:child_process");
+    const plans = (0, setup_plan_js_1.planPluginInstall)(harnesses, {
+        hasClaude: harnesses.includes("claude") && harnessBinaryPresent("claude"),
+    });
+    for (const plan of plans) {
+        console.log("");
+        let installed = false;
+        if (plan.commands.length > 0) {
+            try {
+                for (const cmd of plan.commands) {
+                    exec(cmd, { stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+                }
+                console.log(plan.successMessage);
+                installed = true;
+            }
+            catch {
+                // Fall through to the manual instructions below.
+            }
         }
-        catch {
-            // Ignore malformed settings.
-        }
-    }
-    if (!settings["hooks"])
-        settings["hooks"] = {};
-    const hooks = settings["hooks"];
-    const preCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$FILE" in *.md) [ -f "$FILE" ] && head -1 "$FILE" | grep -q 'vigiles:sha256:' && { SPEC=$(head -1 "$FILE" | sed -n 's/.*compiled from \\(.*\\) -->/\\1/p'); echo "BLOCKED: Edit $SPEC instead." >&2; exit 2; } ;; esac; exit 0`;
-    const postCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$(basename "$FILE")" in eslint.config.*|.eslintrc*|package.json|pyproject.toml|Cargo.toml) npx vigiles generate-types 2>&1 || true ;; esac && case "$FILE" in *.spec.ts) npx vigiles compile 2>&1 || true ;; esac`;
-    const existingStr = JSON.stringify(settings);
-    if (!existingStr.includes("vigiles:sha256")) {
-        const pre = (hooks["PreToolUse"] ?? []);
-        pre.push({ matcher: "Edit|Write", command: preCmd });
-        hooks["PreToolUse"] = pre;
-    }
-    if (!existingStr.includes("vigiles compile")) {
-        const post = (hooks["PostToolUse"] ?? []);
-        post.push({ matcher: "Edit|Write", command: postCmd });
-        hooks["PostToolUse"] = post;
-    }
-    (0, node_fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    console.log("✓ Installed hooks in .claude/settings.json");
-    console.log("  (For skills like edit-spec and migrate-to-spec, also run: npx skills add zernie/vigiles)");
-    return true;
+        if (!installed) {
+            console.log(`Install vigiles for ${plan.harness}:`);
+            for (const step of plan.manualSteps)
+                console.log(`    ${step}`);
+        }
+        for (const note of plan.notes)
+            console.log(`  ${note}`);
+    }
 }
-async function setup(args) {
-    const parsed = (0, setup_plan_js_1.parseSetupArgs)(args);
-    const strict = parsed.strict;
-    // Plan: defaults → flags → interactive prompts (only a human at a TTY).
-    let plan = (0, setup_plan_js_1.resolvePlan)(parsed);
-    if ((0, setup_plan_js_1.shouldPrompt)(parsed, process.stdin.isTTY ?? false)) {
-        plan = (0, setup_plan_js_1.resolvePlan)(parsed, await promptSetup());
+/** Add/upgrade `vigiles` in the project's `devDependencies` (and move it out of
+ * `dependencies` if it's there). Returns the files it wrote (for the commit
+ * hint). No-op in the vigiles repo itself and when there is no package.json. */
+function ensureVigilesDevDep() {
+    const pkgPath = (0, node_path_1.resolve)(process.cwd(), "package.json");
+    if (!(0, node_fs_1.existsSync)(pkgPath))
+        return [];
+    let pkg;
+    try {
+        pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf-8"));
     }
-    const pillars = [plan.verify && "verify", plan.test && "test"]
-        .filter(Boolean)
-        .join(" + ");
-    console.log(`vigiles setup${strict ? " (strict)" : ""} — pillars: ${pillars}\n`);
-    // Detect project.
-    const detected = detectProject();
+    catch {
+        return [];
+    }
+    if (pkg.name === "vigiles")
+        return []; // don't self-depend in this repo
+    const spec = vigilesDepSpec();
+    let changed = false;
+    // Move a stale/misplaced runtime dependency (e.g. a `github:zernie/vigiles`
+    // git pin, or vigiles sitting in `dependencies`) into devDependencies.
+    if (pkg.dependencies && "vigiles" in pkg.dependencies) {
+        delete pkg.dependencies.vigiles;
+        changed = true;
+    }
+    const dev = (pkg.devDependencies ??= {});
+    if (dev.vigiles !== spec) {
+        dev.vigiles = spec;
+        changed = true;
+    }
+    if (!changed)
+        return [];
+    (0, node_fs_1.writeFileSync)(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log(`✓ Set vigiles@${spec} in devDependencies — run \`npm install\` to fetch it`);
+    return ["package.json"];
+}
+/** Which harnesses to set up: an explicit `--harness=` list, else auto-detected
+ * from the repo (Claude Code / Codex), defaulting to Claude Code. */
+function resolveHarnesses(parsed, detected) {
+    if (parsed.harness) {
+        return parsed.harness
+            .split(",")
+            .map((s) => s.trim().toLowerCase())
+            .filter(Boolean);
+    }
+    const set = new Set();
+    if (detected.hasClaude ||
+        detected.agents.includes("Claude Code") ||
+        detected.instructionFiles.some((f) => f.path === "CLAUDE.md")) {
+        set.add("claude");
+    }
+    if (detected.agents.includes("Codex / GitHub Copilot") ||
+        detected.instructionFiles.some((f) => f.path === "AGENTS.md")) {
+        set.add("codex");
+    }
+    if (set.size === 0)
+        set.add("claude");
+    return [...set];
+}
+/** Print the project-detection summary line(s). */
+function printDetection(detected, harnesses) {
     if (detected.agents.length > 0) {
         console.log(`Detected: ${detected.agents.join(", ")}`);
     }
@@ -1386,24 +1569,85 @@ async function setup(args) {
         if (f.isSymlink)
             console.log(`Note: ${f.path} is a symlink`);
     }
-    // Pillar 1 — verify instruction files.
+    console.log(`Harness: ${harnesses.join(", ")}`);
+}
+/** Print the closing next-steps list + an honest commit hint (only files
+ * actually written this run). */
+function printSetupSummary(opts) {
+    const { plan, strict, targets, needsMigration, written } = opts;
+    const specPathsList = targets.map((t) => `${t}.spec.ts`);
+    console.log("\n---\nSetup complete.\n");
+    const nextSteps = [];
+    if (needsMigration.length > 0) {
+        nextSteps.push(`Port ${needsMigration.join(", ")} into its spec with the migrate-to-spec skill, then \`npx vigiles compile\``);
+    }
+    else if (specPathsList.length > 0) {
+        nextSteps.push(`Edit ${specPathsList.join(", ")} — add your conventions, then \`/strengthen\``);
+    }
+    if (plan.test) {
+        nextSteps.push("Edit vigiles.harness.mjs to test a real hook, then `npx vigiles test`");
+    }
+    if (written.includes("package.json")) {
+        nextSteps.push("Run `npm install` to fetch the vigiles dev dependency");
+    }
+    if (!strict) {
+        nextSteps.push("When ready, enforce in CI: npx vigiles init --strict");
+    }
+    nextSteps.forEach((s, i) => {
+        console.log(`  ${String(i + 1)}. ${s}`);
+    });
+    // Only list files actually written this run (deduped, in a stable order).
+    const files = [...new Set(written)];
+    if (files.length > 0) {
+        console.log(`\n  Commit:\n    git add ${files.join(" ")} && git commit -m "Add vigiles"`);
+    }
+}
+async function setup(args) {
+    const parsed = (0, setup_plan_js_1.parseSetupArgs)(args);
+    const strict = parsed.strict;
+    // Plan: defaults → flags → interactive prompts (only a human at a TTY).
+    let plan = (0, setup_plan_js_1.resolvePlan)(parsed);
+    if ((0, setup_plan_js_1.shouldPrompt)(parsed, process.stdin.isTTY ?? false)) {
+        plan = (0, setup_plan_js_1.resolvePlan)(parsed, await promptSetup());
+    }
+    const pillars = [plan.lint && "lint", plan.test && "test"]
+        .filter(Boolean)
+        .join(" + ");
+    console.log(`vigiles setup${strict ? " (strict)" : ""} — pillars: ${pillars}\n`);
+    // Detect project.
+    const detected = detectProject();
+    const harnesses = resolveHarnesses(parsed, detected);
+    printDetection(detected, harnesses);
+    // Files actually written, accumulated for an honest commit hint.
+    const written = [];
+    // Lint pillar — verify instruction-file references.
     let targets = [];
-    if (plan.verify) {
+    let needsMigration = [];
+    if (plan.lint) {
         console.log("");
-        targets = await setupPillar1(detected, parsed.target);
+        const p1 = await setupPillar1(detected, parsed.target, harnesses);
+        targets = p1.specTargets;
+        needsMigration = p1.needsMigration;
+        written.push(...p1.written);
     }
-    // Pillar 2 — test the harness.
+    // Test pillar — test the harness.
     if (plan.test) {
         console.log("");
-        scaffoldPillar2();
+        written.push(...scaffoldPillar2());
+    }
+    // Add/upgrade the vigiles dev dependency (both pillars import from it).
+    if (plan.lint || plan.test) {
+        written.push(...ensureVigilesDevDep());
     }
     // CI — the production Action (+ a harness job when Pillar 2 is on).
     if (plan.gha) {
         console.log("");
-        wireGha(plan);
+        written.push(...wireGha(plan));
+    }
+    // Plugin/skill install — per-harness (Claude marketplace / Codex direct).
+    if (plan.plugin) {
+        installPlugins(harnesses);
     }
-    // Claude Code plugin (hooks + skills).
-    const wroteSettings = plan.plugin ? installPlugin() : false;
     // Agent-specific guidance.
     if (targets.includes("AGENTS.md")) {
         console.log("\n  Codex / Copilot reads AGENTS.md directly — no hooks needed.");
@@ -1419,36 +1663,10 @@ async function setup(args) {
         if (!(0, node_fs_1.existsSync)(configPath)) {
             (0, node_fs_1.writeFileSync)(configPath, JSON.stringify({ rules: { "require-spec": "error", "require-skill-spec": "error" } }, null, 2) + "\n");
             console.log("✓ Created .vigilesrc.json with strict rules");
+            written.push(".vigilesrc.json");
         }
     }
-    // Summary.
-    const specPathsList = targets.map((t) => `${t}.spec.ts`);
-    console.log("\n---\nSetup complete.\n");
-    const nextSteps = [];
-    if (specPathsList.length > 0) {
-        nextSteps.push(`Edit ${specPathsList.join(", ")} — add your conventions, then \`/strengthen\``);
-    }
-    if (plan.test) {
-        nextSteps.push("Edit vigiles.harness.mjs to test a real hook, then `npx vigiles test`");
-    }
-    if (!strict) {
-        nextSteps.push("When ready, enforce in CI: npx vigiles init --strict");
-    }
-    nextSteps.forEach((s, i) => {
-        console.log(`  ${String(i + 1)}. ${s}`);
-    });
-    const files = [
-        ...targets,
-        ...specPathsList,
-        ...(plan.verify ? [".vigiles/generated.d.ts", ".vigiles/schema.json"] : []),
-        ...(plan.test ? ["vigiles.harness.mjs"] : []),
-        ...(plan.gha ? [".github/workflows/vigiles.yml"] : []),
-        ...(wroteSettings ? [".claude/settings.json"] : []),
-        ...(strict ? [".vigilesrc.json"] : []),
-    ];
-    if (files.length > 0) {
-        console.log(`\n  Commit:\n    git add ${files.join(" ")} && git commit -m "Add vigiles"`);
-    }
+    printSetupSummary({ plan, strict, targets, needsMigration, written });
 }
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
@@ -1716,22 +1934,23 @@ function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
     console.log("Commands:");
-    console.log("  vigiles init [flags]           Setup project (--target=X.md, --strict, --no-gha)");
+    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
-    console.log("  vigiles audit [files...]       Verify, find gaps, suggest improvements");
+    console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N)");
     console.log("");
     console.log("Examples:");
     console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
     console.log("  vigiles compile              Compile all .spec.ts files");
-    console.log("  vigiles audit                Verify hashes + coverage + suggestions");
+    console.log("  vigiles lint                 Verify references, hashes, coverage + suggestions");
     console.log("");
     console.log("Plumbing:");
     console.log("  vigiles generate-types [out]  Emit .d.ts from project state");
     console.log("  vigiles generate-types --check  Verify .d.ts is up to date");
     console.log("  vigiles generate-schema [out] Emit JSON Schema for vigiles: frontmatter");
     console.log("  vigiles generate-schema --check Verify schema.json is up to date");
+    console.log("  vigiles --version             Print the version number");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
         process.exit(1);
@@ -2025,7 +2244,7 @@ function refsHookCommand() {
         issues.map((m) => `  - ${m}`).join("\n") +
         `\nExpress references as marks (\`enforce()\` / \`file()\` / \`cmd()\` / a ` +
         `\`vigiles:symbol\` span / an inline \`<!-- vigiles:enforce -->\` comment) so ` +
-        `\`vigiles audit\` can check them — or add \`<!-- vigiles:ignore -->\` if it ` +
+        `\`vigiles lint\` can check them — or add \`<!-- vigiles:ignore -->\` if it ` +
         `is prose, not a reference.`;
     process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
@@ -2037,6 +2256,12 @@ function refsHookCommand() {
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
+    // `--version` / `-v` / `version` prints the version number, not the help
+    // banner — so `npx vigiles --version` reports e.g. `3.0.0`.
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(getVersion());
+        return;
+    }
     const restArgs = args.slice(1).filter((a) => !a.startsWith("--"));
     // Shared flags (--max-rules, --catalog-only) override the loaded config so
     // every GitHub Action input maps to a real CLI flag. See src/cli-flags.ts.
@@ -2075,8 +2300,8 @@ async function main() {
             }
             break;
         }
-        case "audit": {
-            // audit = verify + discover + guidance count
+        case "lint": {
+            // lint = verify references + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
             const report = await audit(restArgs, flags, config);
             annotateAuditForGitHub(report, flags);