start-vibing-stacks 2.22.0 → 2.24.0

package/README.md

@@ -6,7 +6,7 @@ Multi-stack AI workflow for **Claude Code** & **Cursor**. One command installs a
 npx start-vibing-stacks
 ```
 
-> Latest: **v2.12.0** — `security-auditor` rewritten as stack-aware adversarial auditor with VETO power; `documenter` rewritten with search-optimized memory layer (YAML frontmatter + `_index.json` sidecar); `research-web` MCP-first; CI on Node 22.
+> Latest: **v2.24.0** — `migrate` is now smart and complete. Versioned hooks (`// @sv-version`), versioned commands, idempotent `settings.json` patcher, runtime dirs auto-creation, `.gitignore` update — all reachable via `npx start-vibing-stacks migrate --apply`. New `--force-hooks` flag overwrites legacy hooks (no `@sv-version`) with timestamped `.bak` backup. v2.23.0 → multi-instance coordination layer.
 
 ---
 
@@ -16,8 +16,8 @@ npx start-vibing-stacks
 |---|---|---|
 | Agents | **7** universal | `research-web` (MCP-first) · `documenter` (memory layer) · `domain-updater` · `commit-manager` · `tester` · `claude-md-compactor` (compaction) · **`security-auditor` (VETO)** |
 | Skills | **22** shared + **7–14** stack-specific + **2–7** frontend | Versioned (`version:` frontmatter), upgradable via `migrate` |
-| Hooks | `stop-validator` · `final-check` · `user-prompt-submit` | Block completion on git/docs/secrets/code-quality issues |
-| Commands | `/feature` · `/fix` · `/research` · `/validate` | Slash commands |
+| Hooks | `session-start` · `user-prompt-submit` · `pre-tool-use` · `post-tool-use` · `stop-validator` · `final-check` | Multi-instance coordination + git/docs/secrets/code-quality gates |
+| Commands | `/feature` · `/fix` · `/research` · `/validate` · `/peers` | Slash commands |
 | Workflows | `ci.yml` + `security.yml` per stack | Copied to `.github/workflows/` when target is empty |
 | Configs | `active-project.json` · `domain-mapping.json` · `security-rules.json` · `standards-review.json` | Drives every agent's stack detection |
 
@@ -82,24 +82,71 @@ your-project/
 │   │   │   ├── _index.json                    # machine-readable, regenerated by documenter
 │   │   │   └── domains/                       # one file per domain (≤ 8 KB each)
 │   │   └── <other skills>/
-│   ├── hooks/                                 # stop-validator, final-check, prompt-submit
-│   ├── commands/                              # /feature, /fix, /research, /validate
+│   ├── hooks/                                 # session-start, pre/post-tool-use, stop-validator, final-check, prompt-submit, peers (CLI)
+│   ├── commands/                              # /feature, /fix, /research, /validate, /peers
+│   ├── state/                                 # multi-instance coordination (gitignored, runtime-managed)
 │   └── config/                                # active-project, domain-mapping, security-rules, ...
 └── .github/workflows/                         # ci.yml + security.yml (if dir was empty)
 ```
 
 ---
 
+## Multiple Claude instances in the same folder
+
+When two or more Claude Code sessions run in the same project, the installed hooks coordinate automatically through `.claude/state/` (gitignored, per-host).
+
+What you get:
+
+- **Auto-discovery** — `SessionStart` registers each session, captures the same title that appears in `claude --resume`, and tells you who else is around.
+- **File-edit collision shield** — `PreToolUse` BLOCKS Edit/Write on a file a peer is actively editing (heartbeat <60s, touched <5min ago). Idle peers (60s–30min) downgrade to a warning; stale peers are ignored.
+- **Cross-instance messaging** — `peers notify <id-prefix> "msg"` queues a message that surfaces in the OTHER instance at its next prompt. The user-prompt-submit hook drains the inbox automatically.
+
+### `/peers` CLI
+
+```bash
+# Inside Claude:
+/peers                  # delegates to the script
+
+# Or from any terminal:
+npx tsx .claude/hooks/peers.ts list
+npx tsx .claude/hooks/peers.ts notify a1b2c3d4 "I just committed auth changes"
+npx tsx .claude/hooks/peers.ts locks --minutes 10
+npx tsx .claude/hooks/peers.ts cleanup
+```
+
+### Heartbeat thresholds
+
+| Last activity | State    | Effect                                                   |
+| ------------- | -------- | -------------------------------------------------------- |
+| < 60s         | active   | Counts for collision detection; BLOCKS conflicting edits |
+| 60s – 30min   | idle     | Surfaced as a warning; edits NOT blocked                 |
+| > 30min       | stale    | Auto-archived                                            |
+| > 24h         | removed  | Deleted                                                  |
+
+Single-host coordination only. It does **not** replace `git` for cross-machine collaboration; it prevents two live sessions on the same laptop from stepping on the same uncommitted file.
+
+---
+
 ## CLI
 
 ```bash
-npx start-vibing-stacks                  # setup or resume current project
-npx start-vibing-stacks migrate          # show outdated/missing skills
-npx start-vibing-stacks migrate --apply  # update outdated skills/agents
+npx start-vibing-stacks                                # setup or resume current project
+npx start-vibing-stacks migrate                        # dry run: skills + agents + hooks + commands + settings.json + runtime dirs
+npx start-vibing-stacks migrate --apply                # apply (idempotent; preserves customizations)
+npx start-vibing-stacks migrate --apply --force-hooks  # also overwrite legacy hooks (no @sv-version) — creates .bak
 
 # flags: --force --no-claude --no-mcp --no-install --help --version
 ```
 
+`migrate` is the safe upgrade path between releases. Each release gets:
+- **Hooks** versioned via `// @sv-version: x.y.z` header — semver-compared against installed.
+- **Commands** versioned via frontmatter `version:` — same as skills/agents.
+- **`settings.json#hooks`** — idempotent deep-merge: missing event blocks (`SessionStart`, `PreToolUse`, `PostToolUse`, `SessionEnd`) are appended; existing entries (including yours) are preserved.
+- **Runtime artefacts** — `.claude/state/{sessions,inbox,file-touches}/_archive` auto-created; `_state.README.md` staged.
+- **`.gitignore`** — `.claude/state/` appended if not already covered.
+
+Legacy hooks without `@sv-version` (anything older than v2.24.0) are reported as `needs-update-legacy` and skipped by default. Pass `--force-hooks` to overwrite them — each gets a timestamped `.bak`.
+
 Global install: `npm i -g start-vibing-stacks` → `svs` (alias).
 
 ---

package/dist/index.js

@@ -33,6 +33,7 @@ const FLAGS = {
     help: args.includes('--help') || args.includes('-h'),
     version: args.includes('--version') || args.includes('-v'),
     apply: args.includes('--apply'),
+    forceHooks: args.includes('--force-hooks'),
 };
 if (FLAGS.version) {
     console.log(PKG_VERSION);
@@ -52,6 +53,7 @@ if (FLAGS.help) {
   ${chalk.bold('Options:')}
     --force           Overwrite existing configuration (default command)
     --apply           Apply updates (migrate command)
+    --force-hooks     Overwrite legacy hooks without @sv-version (migrate; creates .bak)
     --no-claude       Skip Claude Code installation
     --no-mcp          Skip MCP server selection
     --no-install      Skip dependency installation
@@ -68,7 +70,7 @@ if (FLAGS.help) {
 // Subcommand: migrate
 if (SUBCOMMAND === 'migrate') {
     const { runMigrate } = await import('./migrate.js');
-    await runMigrate(process.cwd(), { apply: FLAGS.apply });
+    await runMigrate(process.cwd(), { apply: FLAGS.apply, forceHooks: FLAGS.forceHooks });
     process.exit(0);
 }
 const AVAILABLE_STACKS = [

package/dist/migrate.d.ts

@@ -1,27 +1,49 @@
 /**
- * Start Vibing Stacks — Migrate
+ * Start Vibing Stacks — Migrate (v2 — smart, idempotent, settings-aware)
  *
- * Compares the SKILL.md / agent / hook versions installed in .claude/
- * against the bundled stacks/<stack>/ and stacks/_shared/ versions.
+ * Compares installed vs bundled versions for skills, agents, hooks AND commands.
+ * Also reconciles runtime artefacts that earlier migrate versions ignored:
  *
- * Reports outdated, missing, and modified items. Optionally upgrades.
- *
- * Skill version contract:
- *   YAML frontmatter at top of SKILL.md must include `version: X.Y.Z`.
- *   No frontmatter = treated as "v0" / pre-versioning.
+ *  - hooks: parsed via `// @sv-version: x.y.z` header. Legacy installs (no tag)
+ *    are skipped with a "needs-update-legacy" warning unless `--force-hooks` is
+ *    passed (which makes a `.bak` copy before overwriting).
+ *  - commands: same `version:` frontmatter contract as skills/agents.
+ *  - .claude/settings.json — patched idempotently to ensure the bundled hook
+ *    chain (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop /
+ *    SessionEnd) is wired. Existing entries are preserved; only missing entries
+ *    are appended. Atomic write (.tmp + rename).
+ *  - .claude/state/ — runtime layout for multi-instance coordination is
+ *    auto-created and the `_state.README.md` is staged as `.claude/state/README.md`.
+ *  - .gitignore — `.claude/state/` is appended if not already covered.
  */
+type Status = 'missing' | 'outdated' | 'current' | 'ahead' | 'modified-no-version' | 'needs-update-legacy';
 export interface MigrateItem {
-    kind: 'skill' | 'agent' | 'hook';
+    kind: 'skill' | 'agent' | 'hook' | 'command';
     name: string;
     source: string;
     target: string;
     bundledVersion: string;
     installedVersion: string | null;
-    status: 'missing' | 'outdated' | 'current' | 'ahead' | 'modified-no-version';
+    status: Status;
 }
 export interface MigrateOptions {
     apply: boolean;
-    scope?: 'skills' | 'agents' | 'hooks' | 'all';
+    scope?: 'skills' | 'agents' | 'hooks' | 'commands' | 'all';
+    forceHooks?: boolean;
 }
 export declare function planMigration(projectDir: string, opts: MigrateOptions): MigrateItem[];
+interface SettingsPatchReport {
+    added: string[];
+    alreadyPresent: string[];
+    fileExisted: boolean;
+    error?: string;
+}
+export declare function patchSettings(projectDir: string, dryRun: boolean): SettingsPatchReport;
+interface RuntimeReport {
+    created: string[];
+    copied: string[];
+    gitignoreUpdated: boolean;
+}
+export declare function ensureRuntimeArtefacts(projectDir: string, dryRun: boolean): RuntimeReport;
 export declare function runMigrate(projectDir: string, opts: MigrateOptions): Promise<void>;
+export {};

package/dist/migrate.js

@@ -1,18 +1,25 @@
 /**
- * Start Vibing Stacks — Migrate
+ * Start Vibing Stacks — Migrate (v2 — smart, idempotent, settings-aware)
  *
- * Compares the SKILL.md / agent / hook versions installed in .claude/
- * against the bundled stacks/<stack>/ and stacks/_shared/ versions.
+ * Compares installed vs bundled versions for skills, agents, hooks AND commands.
+ * Also reconciles runtime artefacts that earlier migrate versions ignored:
  *
- * Reports outdated, missing, and modified items. Optionally upgrades.
- *
- * Skill version contract:
- *   YAML frontmatter at top of SKILL.md must include `version: X.Y.Z`.
- *   No frontmatter = treated as "v0" / pre-versioning.
+ *  - hooks: parsed via `// @sv-version: x.y.z` header. Legacy installs (no tag)
+ *    are skipped with a "needs-update-legacy" warning unless `--force-hooks` is
+ *    passed (which makes a `.bak` copy before overwriting).
+ *  - commands: same `version:` frontmatter contract as skills/agents.
+ *  - .claude/settings.json — patched idempotently to ensure the bundled hook
+ *    chain (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop /
+ *    SessionEnd) is wired. Existing entries are preserved; only missing entries
+ *    are appended. Atomic write (.tmp + rename).
+ *  - .claude/state/ — runtime layout for multi-instance coordination is
+ *    auto-created and the `_state.README.md` is staged as `.claude/state/README.md`.
+ *  - .gitignore — `.claude/state/` is appended if not already covered.
  */
-import { existsSync, readFileSync, copyFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, statSync, readdirSync, renameSync, } from 'fs';
 import { join, relative, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { randomBytes } from 'crypto';
 import * as semver from 'semver';
 import * as ui from './ui.js';
 const __m_filename = fileURLToPath(import.meta.url);
@@ -20,7 +27,8 @@ const __m_dirname = dirname(__m_filename);
 const CLI_ROOT = resolve(__m_dirname, '..');
 const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
 const VERSION_RE = /^version:\s*["']?([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?)["']?\s*$/m;
-function parseVersion(file) {
+const SV_VERSION_RE = /\/\/\s*@sv-version:\s*([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?)/;
+function parseFrontmatterVersion(file) {
     if (!existsSync(file))
         return null;
     try {
@@ -35,7 +43,19 @@ function parseVersion(file) {
         return null;
     }
 }
-function statusOf(bundled, installed) {
+function parseHookVersion(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const content = readFileSync(file, 'utf8').slice(0, 1024);
+        const m = SV_VERSION_RE.exec(content);
+        return m?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function statusFromSemver(bundled, installed) {
     if (installed === null)
         return 'modified-no-version';
     const cmp = semver.compare(installed, bundled);
@@ -62,11 +82,11 @@ function listSubdirs(dir) {
         return [];
     }
 }
-function listFiles(dir, suffix) {
+function listFiles(dir, suffixes) {
     if (!existsSync(dir))
         return [];
     try {
-        return readdirSync(dir).filter(n => n.endsWith(suffix));
+        return readdirSync(dir).filter(n => suffixes.some(s => n.endsWith(s)) && !n.startsWith('_state.README'));
     }
     catch {
         return [];
@@ -90,11 +110,16 @@ function listSkillSources(stack, frontendSkillsDir) {
 }
 function listAgentSources() {
     const dir = join(CLI_ROOT, 'stacks', '_shared', 'agents');
-    return listFiles(dir, '.md').map(n => ({ source: join(dir, n), name: n }));
+    return listFiles(dir, ['.md']).map(n => ({ source: join(dir, n), name: n }));
 }
 function listHookSources() {
     const dir = join(CLI_ROOT, 'stacks', '_shared', 'hooks');
-    return listFiles(dir, '.ts').map(n => ({ source: join(dir, n), name: n }));
+    // Track .ts and .sh files (runnable hooks + shared lib). _state.README.md is handled separately.
+    return listFiles(dir, ['.ts', '.sh']).map(n => ({ source: join(dir, n), name: n }));
+}
+function listCommandSources() {
+    const dir = join(CLI_ROOT, 'stacks', '_shared', 'commands');
+    return listFiles(dir, ['.md']).map(n => ({ source: join(dir, n), name: n }));
 }
 function loadProjectConfig(projectDir) {
     const path = join(projectDir, '.claude', 'config', 'active-project.json');
@@ -118,53 +143,210 @@ export function planMigration(projectDir, opts) {
     if (scope === 'all' || scope === 'skills') {
         for (const { source, name } of listSkillSources(config.stack, config.frontendSkillsDir)) {
             const target = join(projectDir, '.claude', 'skills', name, 'SKILL.md');
-            const bundledVersion = parseVersion(source);
+            const bundledVersion = parseFrontmatterVersion(source);
             if (!bundledVersion)
                 continue;
-            const installedVersion = parseVersion(target);
-            const status = !existsSync(target)
-                ? 'missing'
-                : statusOf(bundledVersion, installedVersion);
+            const installedVersion = parseFrontmatterVersion(target);
+            const status = !existsSync(target) ? 'missing' : statusFromSemver(bundledVersion, installedVersion);
             items.push({ kind: 'skill', name, source, target, bundledVersion, installedVersion, status });
         }
     }
     if (scope === 'all' || scope === 'agents') {
         for (const { source, name } of listAgentSources()) {
             const target = join(projectDir, '.claude', 'agents', name);
-            const bundledVersion = parseVersion(source);
+            const bundledVersion = parseFrontmatterVersion(source);
             if (!bundledVersion)
                 continue;
-            const installedVersion = parseVersion(target);
-            const status = !existsSync(target)
-                ? 'missing'
-                : statusOf(bundledVersion, installedVersion);
+            const installedVersion = parseFrontmatterVersion(target);
+            const status = !existsSync(target) ? 'missing' : statusFromSemver(bundledVersion, installedVersion);
             items.push({ kind: 'agent', name, source, target, bundledVersion, installedVersion, status });
         }
     }
     if (scope === 'all' || scope === 'hooks') {
         for (const { source, name } of listHookSources()) {
             const target = join(projectDir, '.claude', 'hooks', name);
-            const bundledVersion = '0.0.0';
-            const installedVersion = existsSync(target) ? '0.0.0' : null;
-            const status = !existsSync(target) ? 'missing' : 'current';
+            const bundledVersion = parseHookVersion(source) ?? '0.0.0';
+            const installedVersion = parseHookVersion(target);
+            let status;
+            if (!existsSync(target)) {
+                status = 'missing';
+            }
+            else if (installedVersion === null) {
+                status = bundledVersion === '0.0.0' ? 'current' : 'needs-update-legacy';
+            }
+            else {
+                status = statusFromSemver(bundledVersion, installedVersion);
+            }
             items.push({ kind: 'hook', name, source, target, bundledVersion, installedVersion, status });
         }
     }
+    if (scope === 'all' || scope === 'commands') {
+        for (const { source, name } of listCommandSources()) {
+            const target = join(projectDir, '.claude', 'commands', name);
+            const bundledVersion = parseFrontmatterVersion(source);
+            if (!bundledVersion)
+                continue;
+            const installedVersion = parseFrontmatterVersion(target);
+            const status = !existsSync(target) ? 'missing' : statusFromSemver(bundledVersion, installedVersion);
+            items.push({ kind: 'command', name, source, target, bundledVersion, installedVersion, status });
+        }
+    }
     return items;
 }
-function applyOne(item) {
+function backup(target) {
+    if (!existsSync(target))
+        return null;
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const dest = `${target}.${stamp}.bak`;
+    try {
+        copyFileSync(target, dest);
+        return dest;
+    }
+    catch {
+        return null;
+    }
+}
+function applyOne(item, opts) {
     mkdirSync(dirname(item.target), { recursive: true });
+    if (item.status === 'needs-update-legacy') {
+        if (!opts.forceHooks)
+            return { applied: false };
+        const backupPath = backup(item.target);
+        copyFileSync(item.source, item.target);
+        return { applied: true, backupPath };
+    }
     copyFileSync(item.source, item.target);
+    return { applied: true };
+}
+const REQUIRED_HOOK_BLOCKS = {
+    SessionStart: {
+        hooks: [
+            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.ts"', timeout: 10 },
+        ],
+    },
+    UserPromptSubmit: {
+        matcher: '',
+        hooks: [
+            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/user-prompt-submit.ts"', timeout: 10 },
+        ],
+    },
+    PreToolUse: {
+        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+        hooks: [
+            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.ts"', timeout: 5 },
+        ],
+    },
+    PostToolUse: {
+        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+        hooks: [
+            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use.ts"', timeout: 5 },
+        ],
+    },
+    Stop: {
+        hooks: [
+            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"', timeout: 30 },
+        ],
+    },
+    SessionEnd: {
+        hooks: [
+            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"', timeout: 10 },
+        ],
+    },
+};
+function commandSubstring(cmd) {
+    const m = cmd.match(/\.claude\/hooks\/([A-Za-z0-9._-]+\.(?:ts|sh|js|mjs))/);
+    return m?.[1] ?? cmd;
+}
+function writeFileAtomic(target, content) {
+    const tmp = `${target}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, target);
+}
+export function patchSettings(projectDir, dryRun) {
+    const path = join(projectDir, '.claude', 'settings.json');
+    const report = { added: [], alreadyPresent: [], fileExisted: existsSync(path) };
+    let settings = {};
+    if (existsSync(path)) {
+        try {
+            settings = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (err) {
+            report.error = `settings.json is not valid JSON (${err.message}) — skipping patch.`;
+            return report;
+        }
+    }
+    settings.hooks = settings.hooks || {};
+    for (const [event, requiredBlock] of Object.entries(REQUIRED_HOOK_BLOCKS)) {
+        const existingBlocks = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+        const requiredScript = commandSubstring(requiredBlock.hooks[0].command);
+        const alreadyHas = existingBlocks.some(b => (b.hooks || []).some(h => commandSubstring(h.command).includes(requiredScript)));
+        if (alreadyHas) {
+            report.alreadyPresent.push(event);
+            continue;
+        }
+        if (!dryRun) {
+            settings.hooks[event] = [...existingBlocks, requiredBlock];
+        }
+        report.added.push(event);
+    }
+    if (!dryRun && report.added.length > 0 && !report.error) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileAtomic(path, JSON.stringify(settings, null, '\t'));
+    }
+    return report;
 }
+export function ensureRuntimeArtefacts(projectDir, dryRun) {
+    const report = { created: [], copied: [], gitignoreUpdated: false };
+    const stateRoot = join(projectDir, '.claude', 'state');
+    const dirs = [
+        join(stateRoot, 'sessions', '_archive'),
+        join(stateRoot, 'inbox'),
+        join(stateRoot, 'file-touches', '_archive'),
+    ];
+    for (const d of dirs) {
+        if (!existsSync(d)) {
+            if (!dryRun)
+                mkdirSync(d, { recursive: true });
+            report.created.push(relative(projectDir, d));
+        }
+    }
+    const readmeSrc = join(CLI_ROOT, 'stacks', '_shared', 'hooks', '_state.README.md');
+    const readmeDest = join(stateRoot, 'README.md');
+    if (existsSync(readmeSrc) && !existsSync(readmeDest)) {
+        if (!dryRun) {
+            mkdirSync(dirname(readmeDest), { recursive: true });
+            copyFileSync(readmeSrc, readmeDest);
+        }
+        report.copied.push(relative(projectDir, readmeDest));
+    }
+    const giPath = join(projectDir, '.gitignore');
+    if (existsSync(giPath)) {
+        const gi = readFileSync(giPath, 'utf8');
+        const covered = /^\.claude\/state\/?$/m.test(gi) || /^\.claude\/?$/m.test(gi);
+        if (!covered) {
+            if (!dryRun) {
+                const next = gi.trimEnd() +
+                    '\n\n# Claude Code multi-instance coordination state (runtime, per-host)\n.claude/state/\n';
+                writeFileSync(giPath, next);
+            }
+            report.gitignoreUpdated = true;
+        }
+    }
+    return report;
+}
+/* ---------------------------------------------------------------------------
+ * CLI runner
+ * -------------------------------------------------------------------------*/
 export async function runMigrate(projectDir, opts) {
     ui.header('🔄 Start Vibing — Migrate');
     const items = planMigration(projectDir, opts);
-    if (items.length === 0) {
-        ui.info('Nothing to migrate.');
-        return;
-    }
     const grouped = {
-        missing: [], outdated: [], current: [], ahead: [], 'modified-no-version': [],
+        missing: [],
+        outdated: [],
+        current: [],
+        ahead: [],
+        'modified-no-version': [],
+        'needs-update-legacy': [],
     };
     for (const it of items)
         grouped[it.status].push(it);
@@ -174,44 +356,117 @@ export async function runMigrate(projectDir, opts) {
         console.log(`\n  ${label} (${list.length}):`);
         for (const it of list.slice(0, 30)) {
             const v = it.installedVersion ?? '–';
-            console.log(`    ${it.kind.padEnd(5)} ${it.name.padEnd(32)} installed=${v.padEnd(8)} bundled=${it.bundledVersion}`);
+            console.log(`    ${it.kind.padEnd(7)} ${it.name.padEnd(32)} installed=${v.padEnd(8)} bundled=${it.bundledVersion}`);
         }
         if (list.length > 30)
             console.log(`    ... and ${list.length - 30} more`);
     };
     summary('MISSING', grouped.missing);
     summary('OUTDATED', grouped.outdated);
+    summary('NEEDS UPDATE — legacy hooks (no @sv-version tag)', grouped['needs-update-legacy']);
     summary('AHEAD (installed newer than bundled — kept)', grouped.ahead);
     summary('UNVERSIONED (manual review)', grouped['modified-no-version']);
     summary('CURRENT', grouped.current);
-    const upgradable = [...grouped.missing, ...grouped.outdated];
-    if (upgradable.length === 0) {
+    // Settings.json + runtime — preview always, regardless of items.
+    const settingsPreview = patchSettings(projectDir, true);
+    const runtimePreview = ensureRuntimeArtefacts(projectDir, true);
+    if (settingsPreview.added.length > 0) {
+        console.log('\n  SETTINGS.JSON — will add hook entries:');
+        for (const ev of settingsPreview.added)
+            console.log(`    + ${ev}`);
+    }
+    if (settingsPreview.error) {
+        console.log(`\n  SETTINGS.JSON — ${settingsPreview.error}`);
+    }
+    if (runtimePreview.created.length > 0) {
+        console.log('\n  RUNTIME — will create dirs:');
+        for (const d of runtimePreview.created)
+            console.log(`    + ${d}`);
+    }
+    if (runtimePreview.copied.length > 0) {
+        console.log('\n  RUNTIME — will copy:');
+        for (const f of runtimePreview.copied)
+            console.log(`    + ${f}`);
+    }
+    if (runtimePreview.gitignoreUpdated) {
+        console.log('\n  GITIGNORE — will append `.claude/state/`');
+    }
+    const upgradable = [
+        ...grouped.missing,
+        ...grouped.outdated,
+        ...(opts.forceHooks ? grouped['needs-update-legacy'] : []),
+    ];
+    const nothingFile = upgradable.length === 0;
+    const nothingSettings = settingsPreview.added.length === 0;
+    const nothingRuntime = runtimePreview.created.length === 0 && runtimePreview.copied.length === 0 && !runtimePreview.gitignoreUpdated;
+    if (nothingFile && nothingSettings && nothingRuntime) {
         console.log('');
         ui.success('Everything up to date.');
         return;
     }
     if (!opts.apply) {
         console.log('');
-        ui.info(`Run with --apply to install/update ${upgradable.length} item(s).`);
+        const todo = [];
+        if (upgradable.length > 0)
+            todo.push(`${upgradable.length} file(s)`);
+        if (settingsPreview.added.length > 0)
+            todo.push(`${settingsPreview.added.length} settings entry(ies)`);
+        if (!nothingRuntime)
+            todo.push('runtime artefacts');
+        ui.info(`Run with --apply to update: ${todo.join(' + ')}.`);
+        if (grouped['needs-update-legacy'].length > 0 && !opts.forceHooks) {
+            ui.info(`${grouped['needs-update-legacy'].length} legacy hook(s) without @sv-version detected. ` +
+                `Use --force-hooks to update them with a .bak backup.`);
+        }
         return;
     }
     console.log('');
+    let updated = 0;
+    let legacyUpdated = 0;
     for (const it of upgradable) {
         try {
-            applyOne(it);
-            ui.success(`updated ${it.kind} ${it.name} (${it.installedVersion ?? '–'} → ${it.bundledVersion})`);
+            const r = applyOne(it, opts);
+            if (!r.applied)
+                continue;
+            updated++;
+            if (it.status === 'needs-update-legacy')
+                legacyUpdated++;
+            const bak = r.backupPath ? ` (backup: ${relative(projectDir, r.backupPath)})` : '';
+            ui.success(`updated ${it.kind} ${it.name} (${it.installedVersion ?? '–'} → ${it.bundledVersion})${bak}`);
         }
         catch (err) {
             ui.warn(`failed ${it.kind} ${it.name}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Apply settings + runtime.
+    const settingsApply = patchSettings(projectDir, false);
+    const runtimeApply = ensureRuntimeArtefacts(projectDir, false);
+    for (const ev of settingsApply.added)
+        ui.success(`settings.json: wired ${ev}`);
+    if (settingsApply.error)
+        ui.warn(settingsApply.error);
+    for (const d of runtimeApply.created)
+        ui.success(`runtime: created ${d}`);
+    for (const f of runtimeApply.copied)
+        ui.success(`runtime: copied ${f}`);
+    if (runtimeApply.gitignoreUpdated)
+        ui.success('gitignore: appended .claude/state/');
     console.log('');
-    ui.success(`Migration complete: ${upgradable.length} item(s) updated.`);
+    ui.success(`Migration complete: ${updated} file(s), ${settingsApply.added.length} settings entry(ies)` +
+        (legacyUpdated > 0 ? `, ${legacyUpdated} legacy hook(s) overwritten with backup` : ''));
     if (grouped['modified-no-version'].length > 0) {
         console.log('');
-        ui.warn(`${grouped['modified-no-version'].length} unversioned local item(s) skipped — review manually.`);
+        ui.warn(`${grouped['modified-no-version'].length} unversioned local skill/agent/command(s) skipped — review manually.`);
         for (const it of grouped['modified-no-version'].slice(0, 10)) {
             console.log(`    ${relative(projectDir, it.target)}`);
         }
     }
+    if (grouped['needs-update-legacy'].length > 0 && !opts.forceHooks) {
+        console.log('');
+        ui.warn(`${grouped['needs-update-legacy'].length} legacy hook(s) without @sv-version were skipped. ` +
+            `Re-run with --force-hooks to update them (each gets a .bak backup).`);
+        for (const it of grouped['needs-update-legacy'].slice(0, 10)) {
+            console.log(`    ${relative(projectDir, it.target)}`);
+        }
+    }
 }