claude-setup 1.1.5 → 1.1.6

package/dist/builder.d.ts

@@ -15,6 +15,12 @@ export interface FileDiff {
     deleted: string[];
 }
 export declare function buildSyncCommand(diff: FileDiff, collected: CollectedFiles, state: ExistingState): string;
+/**
+ * Bootstrap stack-sync.md — installed by init so /stack-sync works immediately.
+ * When run, it tells Claude to invoke npx claude-setup sync first (which
+ * regenerates this file with the real diff), then re-read and process it.
+ */
+export declare function buildBootstrapSync(): string;
 export declare function buildRemoveCommand(input: string, state: ExistingState): string;
 export interface AtomicStep {
     filename: string;

package/dist/builder.js

@@ -171,6 +171,35 @@ export function buildSyncCommand(diff, collected, state) {
         DELETED_FILES: deletedStr,
     }, "sync");
 }
+/**
+ * Bootstrap stack-sync.md — installed by init so /stack-sync works immediately.
+ * When run, it tells Claude to invoke npx claude-setup sync first (which
+ * regenerates this file with the real diff), then re-read and process it.
+ */
+export function buildBootstrapSync() {
+    return `<!-- stack-sync: self-refreshing sync command. Last generated: ${new Date().toISOString().split("T")[0]} -->
+
+> **Step 1 — always do this first:** Run \`npx claude-setup sync\` to refresh this file with the latest diff.
+> - If it outputs "No changes since…" → respond "Stack already in sync." and STOP.
+> - Otherwise → re-read \`.claude/commands/stack-sync.md\` (Step 2), then process the diff below (Step 3).
+
+## Changes since last setup
+
+### Added files
+(none — run \`npx claude-setup sync\` to populate)
+
+### Modified files
+(none)
+
+### Deleted files
+(none)
+
+## Your job
+
+For EACH changed file: does this change have any implication for the Claude Code setup?
+Update ONLY what the change demands. Do NOT rewrite files — surgical edits only.
+`;
+}
 export function buildRemoveCommand(input, state) {
     const emptyCollected = { configs: {}, source: [], skipped: [] };
     return applyTemplate("remove.md", emptyCollected, state, { USER_INPUT: input }, "remove");

package/dist/commands/init.js

@@ -3,7 +3,7 @@ import { join } from "path";
 import { collectProjectFiles, isEmptyProject } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
-import { buildEmptyProjectCommand, buildAtomicSteps, buildOrchestratorCommand, } from "../builder.js";
+import { buildEmptyProjectCommand, buildAtomicSteps, buildOrchestratorCommand, buildBootstrapSync, } from "../builder.js";
 import { createSnapshot, collectFilesForSnapshot } from "../snapshot.js";
 import { estimateTokens, estimateCost, formatCost, getTokenHookScript, formatRealCostSummary } from "../tokens.js";
 import { c, section } from "../output.js";
@@ -79,12 +79,12 @@ export async function runInit(opts = {}) {
         }
         ensureDir(".claude/commands");
         writeFileSync(".claude/commands/stack-init.md", content, "utf8");
+        writeFileSync(".claude/commands/stack-sync.md", buildBootstrapSync(), "utf8");
         await updateManifest("init", collected, { estimatedTokens: tokens, estimatedCost: cost });
         installTokenHook();
-        // Feature A: Create initial snapshot node
+        // Create initial snapshot — collectFilesForSnapshot scans all .claude/ automatically
         const cwd = process.cwd();
-        const allPaths = [...Object.keys(collected.configs), ...collected.source.map(s => s.path)];
-        const snapshotFiles = collectFilesForSnapshot(cwd, allPaths);
+        const snapshotFiles = collectFilesForSnapshot(cwd, Object.keys(collected.configs));
         createSnapshot(cwd, "init", snapshotFiles, { summary: "initial setup (empty project)" });
         console.log(`
 ${c.green("✅")} New project detected.
@@ -98,7 +98,6 @@ Claude Code will ask 3 questions, then set up your environment.
         const realSummary1 = formatRealCostSummary(cwd);
         if (realSummary1) {
             console.log(realSummary1);
-            console.log(`  ${c.dim(`This command estimate: ~${tokens.toLocaleString()} input tokens (${formatCost(cost)})`)}`);
         }
         else {
             console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`${formatCost(cost)}`)})`);
@@ -131,12 +130,12 @@ Claude Code will ask 3 questions, then set up your environment.
         writeFileSync(join(".claude/commands", step.filename), step.content, "utf8");
     }
     writeFileSync(".claude/commands/stack-init.md", orchestrator, "utf8");
+    writeFileSync(".claude/commands/stack-sync.md", buildBootstrapSync(), "utf8");
     await updateManifest("init", collected, { estimatedTokens: tokens, estimatedCost: cost });
     installTokenHook();
-    // Feature A: Create initial snapshot node
+    // Create initial snapshot — collectFilesForSnapshot scans all .claude/ automatically
     const cwd = process.cwd();
-    const allPaths = [...Object.keys(collected.configs), ...collected.source.map(s => s.path)];
-    const snapshotFiles = collectFilesForSnapshot(cwd, allPaths);
+    const snapshotFiles = collectFilesForSnapshot(cwd, Object.keys(collected.configs));
     createSnapshot(cwd, "init", snapshotFiles, {
         summary: `${steps.length - 1} atomic steps generated`,
     });
@@ -150,7 +149,6 @@ Runs ${steps.length - 1} atomic steps. If one fails, re-run only that step.
     const realSummary2 = formatRealCostSummary(cwd);
     if (realSummary2) {
         console.log(realSummary2);
-        console.log(`  ${c.dim(`This command estimate: ~${tokens.toLocaleString()} input tokens (${formatCost(cost)})`)}`);
     }
     else {
         console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`${formatCost(cost)}`)})`);

package/dist/commands/restore.js

@@ -10,6 +10,97 @@ async function promptFreeText(question) {
         });
     });
 }
+async function promptSelectSnapshot(items) {
+    const allItems = [
+        ...items,
+        { id: "__custom__", label: c.dim("Type snapshot ID manually…") },
+        { id: "__cancel__", label: c.dim("Cancel") },
+    ];
+    // Non-TTY fallback: numbered list
+    if (!process.stdin.isTTY) {
+        for (let i = 0; i < allItems.length; i++) {
+            console.log(`  [${i + 1}] ${allItems[i].label}`);
+        }
+        const raw = await promptFreeText("\nEnter number (or 'cancel'):");
+        if (!raw || raw === "cancel")
+            return null;
+        const num = parseInt(raw, 10);
+        if (!isNaN(num) && num >= 1 && num <= allItems.length) {
+            const val = allItems[num - 1].id;
+            if (val === "__cancel__")
+                return null;
+            if (val === "__custom__")
+                return (await promptFreeText("Enter snapshot ID:")) || null;
+            return val;
+        }
+        return raw;
+    }
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        let lineCount = 0;
+        const clearLines = () => {
+            if (lineCount > 0)
+                process.stdout.write(`\x1b[${lineCount}A\x1b[0J`);
+        };
+        const render = () => {
+            clearLines();
+            const lines = [];
+            for (let i = 0; i < allItems.length; i++) {
+                const isSelected = i === selectedIndex;
+                const marker = isSelected ? c.cyan("❯") : " ";
+                const text = isSelected ? c.bold(allItems[i].label) : allItems[i].label;
+                lines.push(`  ${marker} ${text}`);
+            }
+            lines.push(``);
+            lines.push(`  ${c.dim("↑/↓ navigate · Enter select · Ctrl+C cancel")}`);
+            process.stdout.write(lines.join("\n") + "\n");
+            lineCount = lines.length;
+        };
+        let onKey;
+        const cleanup = () => {
+            process.stdin.removeListener("data", onKey);
+            try {
+                process.stdin.setRawMode(false);
+            }
+            catch { }
+            process.stdin.pause();
+        };
+        onKey = (key) => {
+            if (key === "\u0003") {
+                cleanup();
+                process.stdout.write("\n");
+                process.exit(0);
+            }
+            else if (key === "\u001b[A" || key === "\u001bOA") {
+                selectedIndex = Math.max(0, selectedIndex - 1);
+                render();
+            }
+            else if (key === "\u001b[B" || key === "\u001bOB") {
+                selectedIndex = Math.min(allItems.length - 1, selectedIndex + 1);
+                render();
+            }
+            else if (key === "\r" || key === "\n") {
+                const chosen = allItems[selectedIndex];
+                cleanup();
+                process.stdout.write("\n");
+                if (chosen.id === "__cancel__") {
+                    resolve(null);
+                }
+                else if (chosen.id === "__custom__") {
+                    promptFreeText("Enter snapshot ID:").then(id => resolve(id || null));
+                }
+                else {
+                    resolve(chosen.id);
+                }
+            }
+        };
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", onKey);
+        render();
+    });
+}
 export async function runRestore() {
     const cwd = process.cwd();
     const timeline = readTimeline(cwd);
@@ -19,23 +110,49 @@ export async function runRestore() {
     }
     // Display timeline
     section("Snapshot timeline");
-    console.log("");
-    const restoredTo = timeline.restoredTo;
+    console.log(`  ${c.dim("All snapshots are always preserved — you can go back or forward freely.")}\n`);
+    const restoredIdx = timeline.restoredTo
+        ? timeline.nodes.findIndex(n => n.id === timeline.restoredTo)
+        : timeline.nodes.length - 1;
+    const latestIdx = timeline.nodes.length - 1;
     for (let i = 0; i < timeline.nodes.length; i++) {
         const node = timeline.nodes[i];
         const date = new Date(node.timestamp).toLocaleString();
-        const isLatest = i === timeline.nodes.length - 1;
-        const isRestored = restoredTo === node.id && !isLatest;
-        const current = isLatest ? ` ${c.green("← current")}` : isRestored ? ` ${c.cyan("← restored here")}` : "";
-        const connector = i < timeline.nodes.length - 1 ? "──→" : "   ";
+        const isLatest = i === latestIdx;
+        const isHere = i === restoredIdx && timeline.restoredTo;
+        let marker = "";
+        let prefix = "  ";
+        if (isHere && !isLatest) {
+            marker = `  ${c.cyan("◀ you are here")}`;
+            prefix = c.cyan("▶ ");
+        }
+        else if (isLatest && !timeline.restoredTo) {
+            marker = `  ${c.green("◀ you are here")}`;
+            prefix = c.green("▶ ");
+        }
+        else if (i > restoredIdx) {
+            marker = `  ${c.dim("(future — reachable)")}`;
+            prefix = c.dim("  ");
+        }
         const inputStr = node.input ? ` "${node.input}"` : "";
-        console.log(`  ${c.cyan(node.id)}  ${node.command}${inputStr}  ${c.dim(date)}  ${node.summary}${current}`);
+        console.log(`  ${prefix}${c.cyan(node.id)}  ${node.command}${inputStr}  ${c.dim(date)}  ${node.summary}${marker}`);
         if (i < timeline.nodes.length - 1)
-            console.log(`  ${c.dim(connector)}`);
+            console.log(`  ${c.dim("  ──→")}`);
     }
     console.log("");
-    const input = await promptFreeText("Enter snapshot ID to restore (or 'cancel'):");
-    if (!input || input === "cancel") {
+    const items = timeline.nodes.map((node, i) => {
+        const date = new Date(node.timestamp).toLocaleString();
+        const isLatest = i === latestIdx;
+        const isHere = i === restoredIdx && timeline.restoredTo;
+        const tag = isHere && !isLatest ? ` ${c.cyan("← you are here")}`
+            : isLatest && !timeline.restoredTo ? ` ${c.green("← you are here")}`
+                : i > restoredIdx ? ` ${c.dim("(future)")}`
+                    : "";
+        return { id: node.id, label: `${node.id}  ${node.command}  ${c.dim(date)}  ${node.summary}${tag}` };
+    });
+    console.log("Select a snapshot to restore to:\n");
+    const input = await promptSelectSnapshot(items);
+    if (!input) {
         console.log("Cancelled.");
         return;
     }
@@ -45,7 +162,7 @@ export async function runRestore() {
         return;
     }
     console.log(`\nRestoring to snapshot ${c.cyan(node.id)} (${new Date(node.timestamp).toLocaleString()})...`);
-    console.log(`${c.dim("Other snapshots are preserved — you can jump forward or back at any time.")}\n`);
+    console.log(`${c.dim("Config files will be rewritten to their state at this snapshot. Other files are untouched.")}\n`);
     const result = restoreSnapshot(cwd, input, timeline);
     updateRestoredNode(cwd, input);
     if (result.restored.length) {
@@ -54,6 +171,12 @@ export async function runRestore() {
             console.log(`  ${c.green("✅")} ${f}`);
         }
     }
+    if (result.deleted.length) {
+        section(`Removed (added after this snapshot — ${result.deleted.length} files)`);
+        for (const f of result.deleted) {
+            console.log(`  ${c.red("🗑")}  ${f}`);
+        }
+    }
     if (result.failed.length) {
         section("Failed to restore");
         for (const f of result.failed) {
@@ -61,36 +184,45 @@ export async function runRestore() {
         }
     }
     if (result.stale.length) {
-        section("Files not in this snapshot (may be stale)");
-        console.log(`  ${c.dim("These files exist now but were not part of the restored snapshot:")}`);
+        section("Could not delete (permission error)");
+        console.log(`  ${c.dim("These files exist but couldn't be removed — delete manually:")}`);
         for (const f of result.stale) {
             console.log(`  ${c.yellow("⚠️")}  ${f}`);
         }
-        console.log(`  ${c.dim("To fully reset, delete these manually or run sync to update the snapshot.")}`);
     }
-    if (result.restored.length === 0 && result.stale.length === 0) {
-        console.log(`\n${c.yellow("⚠️")}  This snapshot captured 0 files — the project was empty at that point.`);
-        console.log(`   Files added since this snapshot have been left in place.`);
+    if (result.restored.length === 0 && result.deleted.length === 0) {
+        console.log(`\n${c.yellow("⚠️")}  This snapshot captured 0 files — nothing to restore.`);
     }
     else {
-        console.log(`\n${c.green("✅")} Restored ${result.restored.length} file(s) to snapshot ${c.cyan(node.id)}.`);
+        const parts = [];
+        if (result.restored.length)
+            parts.push(`${result.restored.length} restored`);
+        if (result.deleted.length)
+            parts.push(`${result.deleted.length} removed`);
+        console.log(`\n${c.green("✅")} ${parts.join(", ")} → project is now at snapshot ${c.cyan(node.id)}.`);
     }
-    // Re-read and display updated timeline showing the restored position
+    // Re-read and display updated timeline
     const updatedTimeline = readTimeline(cwd);
+    const updatedRestoredIdx = updatedTimeline.restoredTo
+        ? updatedTimeline.nodes.findIndex(n => n.id === updatedTimeline.restoredTo)
+        : updatedTimeline.nodes.length - 1;
     console.log("");
-    section("Updated timeline");
+    section("Timeline — you can restore to any node at any time");
     console.log("");
     for (let i = 0; i < updatedTimeline.nodes.length; i++) {
         const n = updatedTimeline.nodes[i];
         const date = new Date(n.timestamp).toLocaleString();
-        const isRestored = updatedTimeline.restoredTo === n.id;
-        const marker = isRestored ? ` ${c.cyan("← restored here")}` : "";
-        const connector = i < updatedTimeline.nodes.length - 1 ? "──→" : "   ";
+        const isHere = i === updatedRestoredIdx;
+        const isFuture = i > updatedRestoredIdx;
+        const marker = isHere ? `  ${c.cyan("◀ you are here")}` : isFuture ? `  ${c.dim("(future — reachable)")}` : "";
+        const prefix = isHere ? c.cyan("▶ ") : isFuture ? c.dim("  ") : "  ";
         const inputStr = n.input ? ` "${n.input}"` : "";
-        console.log(`  ${c.cyan(n.id)}  ${n.command}${inputStr}  ${c.dim(date)}  ${n.summary}${marker}`);
+        console.log(`  ${prefix}${c.cyan(n.id)}  ${n.command}${inputStr}  ${c.dim(date)}  ${n.summary}${marker}`);
         if (i < updatedTimeline.nodes.length - 1)
-            console.log(`  ${c.dim(connector)}`);
+            console.log(`  ${c.dim("  ──→")}`);
     }
-    console.log(`\nTimeline position updated → snapshot ${c.cyan(node.id)}`);
-    console.log(`Run ${c.cyan("npx claude-setup sync")} to capture the current state as a new node.\n`);
+    console.log(``);
+    console.log(`  ${c.green("▶")} Run ${c.cyan("claude")} in this directory to start working from this point.`);
+    console.log(`  ${c.dim("Run npx claude-setup sync to save the current state as a new snapshot.")}`);
+    console.log(``);
 }

package/dist/commands/sync.js

@@ -187,9 +187,10 @@ export async function runSync(opts = {}) {
             }
         }
     }
-    if (!diff.added.length && !diff.changed.length && !diff.deleted.length && !oobDetected) {
+    const hasChanges = diff.added.length > 0 || diff.changed.length > 0 || diff.deleted.length > 0 || oobDetected;
+    if (!hasChanges) {
         console.log(`${c.green("✅")} No changes since ${c.dim(lastRun.at)}. Setup is current.`);
-        return;
+        // Still regenerate the command file so /stack-sync self-refresh always gets an up-to-date "no changes" state
     }
     const state = await readState();
     const content = buildSyncCommand(diff, collected, state);
@@ -228,43 +229,43 @@ export async function runSync(opts = {}) {
     writeFileSync(".claude/commands/stack-sync.md", content, "utf8");
     await updateManifest("sync", collected, { estimatedTokens: tokens, estimatedCost: cost });
     installTokenHook();
-    // Feature A: Create snapshot node
+    // Create snapshot node — collectFilesForSnapshot scans all .claude/ automatically
     const allPaths = [
         ...Object.keys(collected.configs),
         ...collected.source.map(s => s.path),
-        ...claudeInternalFiles.map(f => f.path),
     ];
     const snapshotFiles = collectFilesForSnapshot(cwd, allPaths);
-    const changeCount = diff.added.length + diff.changed.length + diff.deleted.length;
     createSnapshot(cwd, "sync", snapshotFiles, {
         summary: `+${diff.added.length} added, ~${diff.changed.length} modified, -${diff.deleted.length} deleted`,
     });
-    console.log(`
+    if (hasChanges) {
+        console.log(`
 Changes since ${c.dim(lastRun.at)}:
   ${c.green(`+${diff.added.length}`)} added  ${c.yellow(`~${diff.changed.length}`)} modified  ${c.red(`-${diff.deleted.length}`)} deleted
 
-${c.green("✅")} Ready. Open Claude Code and run:
-   ${c.cyan("/stack-sync")}
-  `);
-    // Token cost display
-    section("Token cost");
-    const realSummary = formatRealCostSummary(cwd);
-    if (realSummary) {
-        console.log(realSummary);
-        console.log(`  ${c.dim(`This command estimate: ~${tokens.toLocaleString()} input tokens (${formatCost(cost)})`)}`);
-    }
-    else {
-        console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`${formatCost(cost)}`)})`);
-        console.log(`  ${c.dim("Estimates only — real costs tracked after first Claude Code session")}`);
+${c.green("✅")} Run ${c.cyan("/stack-sync")} in Claude Code to apply.
+    `);
     }
-    // Optimization hints
-    const runs = manifest.runs.map(r => ({ command: r.command, estimatedTokens: r.estimatedTokens }));
-    const hints = generateHints(runs, tokens, config.tokenBudget.sync);
-    if (hints.length) {
-        section("Optimization hints");
-        for (const hint of hints) {
-            console.log(`  ${c.yellow("💡")} ${hint}`);
+    if (hasChanges) {
+        // Token cost display
+        section("Token cost");
+        const realSummary = formatRealCostSummary(cwd);
+        if (realSummary) {
+            console.log(realSummary);
+        }
+        else {
+            console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`${formatCost(cost)}`)})`);
+            console.log(`  ${c.dim("Estimates only — real costs tracked after first Claude Code session")}`);
         }
+        // Optimization hints
+        const runs = manifest.runs.map(r => ({ command: r.command, estimatedTokens: r.estimatedTokens }));
+        const hints = generateHints(runs, tokens, config.tokenBudget.sync);
+        if (hints.length) {
+            section("Optimization hints");
+            for (const hint of hints) {
+                console.log(`  ${c.yellow("💡")} ${hint}`);
+            }
+        }
+        console.log("");
     }
-    console.log("");
 }

package/dist/doctor.js

@@ -375,9 +375,14 @@ export async function runDoctor(verbose = false, fix = false, testHooks = false)
                         counts.warnings++;
                     }
                     else if (result.status === "error") {
+                        const stderr = result.stderr ?? "";
+                        const isFileMissing = stderr.includes("Cannot find module") || stderr.includes("MODULE_NOT_FOUND");
+                        const hint = isFileMissing
+                            ? `\n      Hint: hook file not found — run ${c.cyan("npx claude-setup init")} to reinstall it.`
+                            : "";
                         statusLine("⚠️ ", label, c.yellow(`FAIL (exit ${result.exitCode}, ${result.timeMs}ms)\n` +
-                            `      Command: ${hook.command.slice(0, 50)}\n` +
-                            `      ${result.stderr ? `stderr: ${result.stderr.slice(0, 100)}` : ""}`));
+                            `      Command: ${hook.command.slice(0, 60)}\n` +
+                            `      ${stderr ? `stderr: ${stderr.slice(0, 200)}` : ""}${hint}`));
                         counts.warnings++;
                     }
                     else if (result.status === "permission") {
@@ -409,13 +414,13 @@ export async function runDoctor(verbose = false, fix = false, testHooks = false)
                     counts.healthy++;
                 }
                 else if (isInTemplate) {
-                    statusLine("🔴", `\${${v}}`, c.red(`NOT SET — MCP server will fail at runtime.\n` +
+                    statusLine("🔴", `\${${v}}`, c.red(`NOT SET — MCP server will fail at runtime and won't appear in /mcp.\n` +
                         `      Documented in .env.example but not loaded into environment.\n` +
                         `      Fix: set ${v} in your shell or .env file, then restart Claude Code.`));
                     counts.critical++;
                 }
                 else {
-                    statusLine("🔴", `\${${v}}`, c.red(`NOT SET — MCP server will fail at runtime.\n` +
+                    statusLine("🔴", `\${${v}}`, c.red(`NOT SET — MCP server will fail at runtime and won't appear in /mcp.\n` +
                         `      Missing from both environment and .env.example.\n` +
                         `      Fix: add ${v} to .env.example and set its value in your shell or .env file.`));
                     counts.critical++;

package/dist/snapshot.d.ts

@@ -19,6 +19,7 @@ export interface SnapshotNode {
     input?: string;
     changedFiles: string[];
     summary: string;
+    fullSnapshot?: boolean;
 }
 export interface SnapshotTimeline {
     nodes: SnapshotNode[];
@@ -41,9 +42,14 @@ export declare function createSnapshot(cwd: string, command: string, changedFile
     summary?: string;
 }): SnapshotNode;
 /**
- * Build the cumulative file state at a given node by accumulating
- * all files from node 0 through the target node. Later nodes override
- * earlier ones (last-write-wins), giving the full state at that point.
+ * Build the complete file state at a given node.
+ *
+ * Full snapshots (fullSnapshot: true) store the entire project state — used directly.
+ * Legacy delta snapshots accumulate from node 0 to target (last-write-wins).
+ *
+ * Why the distinction matters: with delta snapshots, if a file was deleted between A→B,
+ * it would wrongly appear in cumulative state at B (still present from A). Full snapshots
+ * avoid this because the target node's data IS the complete truth at that point.
  */
 export declare function buildCumulativeState(cwd: string, nodeId: string, timeline: SnapshotTimeline): Record<string, string> | null;
 /**
@@ -56,6 +62,7 @@ export declare function buildCumulativeState(cwd: string, nodeId: string, timeli
 export declare function restoreSnapshot(cwd: string, nodeId: string, timeline?: SnapshotTimeline): {
     restored: string[];
     failed: string[];
+    deleted: string[];
     stale: string[];
 };
 /**
@@ -76,10 +83,11 @@ export declare function compareSnapshots(cwd: string, nodeIdA: string, nodeIdB:
     identical: string[];
 };
 /**
- * Collect current file contents for snapshot.
- * Reads tracked files + CLI-managed files from disk.
+ * Collect ALL project files for snapshot — full git-like coverage.
+ * Respects .gitignore + hard exclusions (node_modules, .git, binaries, .env).
+ * The trackedPaths param is kept for API compat but ignored.
  */
-export declare function collectFilesForSnapshot(cwd: string, trackedPaths: string[]): Array<{
+export declare function collectFilesForSnapshot(cwd: string, _trackedPaths: string[]): Array<{
     path: string;
     content: string;
 }>;

package/dist/snapshot.js

@@ -12,8 +12,8 @@
  *
  * Zero API calls. All local filesystem operations.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
-import { join, dirname } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync, statSync } from "fs";
+import { join, dirname, extname } from "path";
 import { createHash } from "crypto";
 const SNAPSHOTS_DIR = ".claude/snapshots";
 const TIMELINE_FILE = "timeline.json";
@@ -85,6 +85,7 @@ export function createSnapshot(cwd, command, changedFiles, opts = {}) {
         ...(opts.input ? { input: opts.input } : {}),
         changedFiles: changedFiles.map(f => f.path),
         summary: opts.summary ?? `${changedFiles.length} file(s) captured`,
+        fullSnapshot: true,
     };
     timeline.nodes.push(node);
     writeTimeline(cwd, timeline);
@@ -92,14 +93,26 @@ export function createSnapshot(cwd, command, changedFiles, opts = {}) {
     return node;
 }
 /**
- * Build the cumulative file state at a given node by accumulating
- * all files from node 0 through the target node. Later nodes override
- * earlier ones (last-write-wins), giving the full state at that point.
+ * Build the complete file state at a given node.
+ *
+ * Full snapshots (fullSnapshot: true) store the entire project state — used directly.
+ * Legacy delta snapshots accumulate from node 0 to target (last-write-wins).
+ *
+ * Why the distinction matters: with delta snapshots, if a file was deleted between A→B,
+ * it would wrongly appear in cumulative state at B (still present from A). Full snapshots
+ * avoid this because the target node's data IS the complete truth at that point.
  */
 export function buildCumulativeState(cwd, nodeId, timeline) {
     const targetIndex = timeline.nodes.findIndex(n => n.id === nodeId);
     if (targetIndex < 0)
         return null;
+    const targetNode = timeline.nodes[targetIndex];
+    // Full snapshot: the node's own data is already the complete project state
+    if (targetNode.fullSnapshot) {
+        const data = readNodeData(cwd, nodeId);
+        return data ? { ...data.files } : null;
+    }
+    // Legacy delta snapshot: accumulate from beginning to target
     const cumulative = {};
     for (let i = 0; i <= targetIndex; i++) {
         const data = readNodeData(cwd, timeline.nodes[i].id);
@@ -119,12 +132,11 @@ export function buildCumulativeState(cwd, nodeId, timeline) {
  * Does NOT delete other nodes — all nodes are preserved (like git).
  */
 export function restoreSnapshot(cwd, nodeId, timeline) {
-    // If no timeline provided, read it
     const tl = timeline ?? readTimeline(cwd);
-    // Build cumulative state up to this node
     const cumulativeFiles = buildCumulativeState(cwd, nodeId, tl);
     if (!cumulativeFiles)
-        return { restored: [], failed: [nodeId], stale: [] };
+        return { restored: [], failed: [nodeId], deleted: [], stale: [] };
+    // Step 1: Write all snapshot files to disk
     const restored = [];
     const failed = [];
     for (const [filePath, content] of Object.entries(cumulativeFiles)) {
@@ -140,29 +152,28 @@ export function restoreSnapshot(cwd, nodeId, timeline) {
             failed.push(filePath);
         }
     }
-    // Detect files that exist now but weren't in the cumulative state
-    // These are files added in later snapshots that may be stale
+    // Step 2: Scan the project NOW (using the just-restored .gitignore)
+    // and delete any file that isn't part of the snapshot.
+    // This makes restore a true time machine — the directory looks exactly
+    // like it did at this snapshot.
+    const rules = loadGitignoreRules(cwd); // uses restored .gitignore if it was snapshotted
+    const currentFiles = [];
+    scanProject(cwd, "", rules, currentFiles);
+    const deleted = [];
     const stale = [];
-    const targetIndex = tl.nodes.findIndex(n => n.id === nodeId);
-    if (targetIndex >= 0) {
-        const laterNodes = tl.nodes.slice(targetIndex + 1);
-        const allLaterFiles = new Set();
-        for (const node of laterNodes) {
-            const nodeData = readNodeData(cwd, node.id);
-            if (nodeData) {
-                for (const fp of Object.keys(nodeData.files)) {
-                    allLaterFiles.add(fp);
-                }
-            }
+    for (const f of currentFiles) {
+        if (cumulativeFiles[f.path])
+            continue; // in snapshot — already restored
+        // Not in snapshot → delete
+        try {
+            unlinkSync(join(cwd, f.path));
+            deleted.push(f.path);
         }
-        // Files in later snapshots but NOT in cumulative state at target
-        for (const filePath of allLaterFiles) {
-            if (!cumulativeFiles[filePath] && existsSync(join(cwd, filePath))) {
-                stale.push(filePath);
-            }
+        catch {
+            stale.push(f.path); // couldn't delete (permissions etc.)
         }
     }
-    return { restored, failed, stale };
+    return { restored, failed, deleted, stale };
 }
 /**
  * Record the last restored node in the timeline (for display purposes).
@@ -211,40 +222,164 @@ export function compareSnapshots(cwd, nodeIdA, nodeIdB) {
     }
     return { onlyInA, onlyInB, changed, identical };
 }
-/**
- * Collect current file contents for snapshot.
- * Reads tracked files + CLI-managed files from disk.
- */
-export function collectFilesForSnapshot(cwd, trackedPaths) {
-    const files = [];
-    const seen = new Set();
-    for (const filePath of trackedPaths) {
-        if (filePath === "__digest__" || filePath === ".env")
-            continue;
-        if (seen.has(filePath))
-            continue;
-        const fullPath = join(cwd, filePath);
-        if (!existsSync(fullPath))
-            continue;
-        try {
-            files.push({ path: filePath, content: readFileSync(fullPath, "utf8") });
-            seen.add(filePath);
+// ── Full-project file scanner (git-like coverage) ──────────────────────
+const MAX_FILE_BYTES = 1024 * 1024; // 1 MB per file
+/** Directory names always excluded (regardless of location in tree) */
+const EXCLUDE_DIRS = new Set([
+    ".git", "node_modules",
+    "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", ".remix",
+    "__pycache__", "target", ".gradle", ".mvn", "vendor",
+    "coverage", ".nyc_output", ".c8",
+    ".cache", ".parcel-cache", ".turbo", ".vercel", ".netlify",
+    "tmp", "temp", ".tmp",
+]);
+/** Relative paths always excluded */
+const EXCLUDE_REL = new Set([
+    ".claude/snapshots",
+    ".claude/token-usage.json",
+    ".claude/claude-setup.json",
+]);
+/** Filenames always excluded (sensitive or OS noise) */
+const EXCLUDE_NAMES = new Set([
+    ".env", ".DS_Store", "Thumbs.db", "desktop.ini",
+]);
+/** Binary file extensions — skip */
+const BINARY_EXT = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".ico", ".avif",
+    ".pdf",
+    ".zip", ".tar", ".gz", ".bz2", ".7z", ".rar", ".xz",
+    ".exe", ".dll", ".so", ".dylib", ".bin",
+    ".wasm",
+    ".woff", ".woff2", ".ttf", ".otf", ".eot",
+    ".mp3", ".mp4", ".wav", ".ogg", ".flac", ".avi", ".mov", ".mkv",
+    ".class", ".jar", ".war",
+    ".pyc", ".pyo", ".pyd",
+    ".o", ".a", ".lib",
+    ".db", ".sqlite", ".sqlite3",
+]);
+function parseGitignoreLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    let pattern = trimmed;
+    const negated = pattern.startsWith("!");
+    if (negated)
+        pattern = pattern.slice(1);
+    const anchored = pattern.startsWith("/");
+    if (anchored)
+        pattern = pattern.slice(1);
+    const dirOnly = pattern.endsWith("/");
+    if (dirOnly)
+        pattern = pattern.slice(0, -1);
+    // Convert glob to regex
+    let regexStr = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*" && pattern[i + 1] === "*") {
+            if (pattern[i + 2] === "/") {
+                regexStr += "(?:.+/)?";
+                i += 2;
+            }
+            else {
+                regexStr += ".*";
+                i++;
+            }
+        }
+        else if (ch === "*") {
+            regexStr += "[^/]*";
+        }
+        else if (ch === "?") {
+            regexStr += "[^/]";
+        }
+        else if (".+^${}()|[]\\".includes(ch)) {
+            regexStr += "\\" + ch;
+        }
+        else {
+            regexStr += ch;
         }
-        catch { /* skip unreadable */ }
     }
-    // Also capture CLI-managed files if not already included
-    const managed = ["CLAUDE.md", ".mcp.json", ".claude/settings.json"];
-    for (const m of managed) {
-        if (seen.has(m))
-            continue;
-        const fullPath = join(cwd, m);
-        if (!existsSync(fullPath))
+    const full = (anchored || pattern.includes("/"))
+        ? `^${regexStr}(?:/.*)?$`
+        : `(?:^|/)${regexStr}(?:/.*)?$`;
+    try {
+        return { negated, dirOnly, regex: new RegExp(full) };
+    }
+    catch {
+        return null;
+    }
+}
+function loadGitignoreRules(cwd) {
+    try {
+        return readFileSync(join(cwd, ".gitignore"), "utf8")
+            .split("\n").map(parseGitignoreLine)
+            .filter((r) => r !== null);
+    }
+    catch {
+        return [];
+    }
+}
+function matchesAnyRule(relPath, isDir, rules) {
+    let excluded = false;
+    for (const rule of rules) {
+        if (rule.dirOnly && !isDir)
             continue;
-        try {
-            files.push({ path: m, content: readFileSync(fullPath, "utf8") });
-            seen.add(m);
+        if (rule.regex.test(relPath))
+            excluded = !rule.negated;
+    }
+    return excluded;
+}
+function tryReadText(absPath) {
+    try {
+        const st = statSync(absPath);
+        if (!st.isFile() || st.size > MAX_FILE_BYTES)
+            return null;
+        const content = readFileSync(absPath, "utf8");
+        if (content.includes("\0"))
+            return null; // binary
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+function scanProject(cwd, relBase, rules, out) {
+    const abs = relBase ? join(cwd, relBase) : cwd;
+    try {
+        for (const entry of readdirSync(abs, { withFileTypes: true })) {
+            const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
+            const isDir = entry.isDirectory();
+            // Hard excludes
+            if (isDir && EXCLUDE_DIRS.has(entry.name))
+                continue;
+            if (EXCLUDE_REL.has(relPath) || relPath.startsWith(".claude/snapshots/"))
+                continue;
+            if (!isDir && EXCLUDE_NAMES.has(entry.name))
+                continue;
+            if (!isDir && BINARY_EXT.has(extname(entry.name).toLowerCase()))
+                continue;
+            // Gitignore
+            if (matchesAnyRule(relPath, isDir, rules))
+                continue;
+            if (isDir) {
+                scanProject(cwd, relPath, rules, out);
+            }
+            else {
+                const content = tryReadText(join(cwd, relPath));
+                if (content !== null)
+                    out.push({ path: relPath, content });
+            }
         }
-        catch { /* skip */ }
     }
-    return files;
+    catch { /* skip unreadable */ }
+}
+/**
+ * Collect ALL project files for snapshot — full git-like coverage.
+ * Respects .gitignore + hard exclusions (node_modules, .git, binaries, .env).
+ * The trackedPaths param is kept for API compat but ignored.
+ */
+export function collectFilesForSnapshot(cwd, _trackedPaths) {
+    const rules = loadGitignoreRules(cwd);
+    const out = [];
+    scanProject(cwd, "", rules, out);
+    return out;
 }

package/dist/tokens.js

@@ -292,8 +292,8 @@ export function readProjectSessions(projectCwd) {
         // Encode the CWD the way Claude Code does, then exact-match against project dirs.
         // This is the only reliable cross-platform approach — decoding is lossy when
         // folder names contain hyphens (e.g. "Claude-code-documentation").
-        //   Windows: C:\Users\ok\Desktop\my-app  →  C--Users-ok-Desktop-my-app
-        //   Unix:    /Users/ok/dev/my-app         →  -Users-ok-dev-my-app
+        //   Windows: C:\Users\alice\Desktop\my-app  →  C--Users-alice-Desktop-my-app
+        //   Unix:    /Users/alice/dev/my-app         →  -Users-alice-dev-my-app
         const encodedCwd = projectCwd
             .replace(/\\/g, "/") // normalize backslashes to forward slashes
             .replace(/:\//g, "--") // drive letter: C:/ → C--

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-setup",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Setup layer for Claude Code — reads your project, writes command files, Claude Code does the rest",
   "type": "module",
   "bin": {

package/templates/sync.md

@@ -1,5 +1,9 @@
 <!-- claude-setup sync {{DATE}} | last: {{LAST_RUN_DATE}} -->
 
+> **Step 1 — always do this first:** Run `npx claude-setup sync` to refresh this file with the latest diff.
+> - If it outputs "No changes since…" → respond "Stack already in sync." and STOP.
+> - Otherwise → re-read `.claude/commands/stack-sync.md` (Step 2), then process the diff below (Step 3).
+
 Project changed since last setup. Update ONLY what the changes demand.
 
 ## Changes since last setup