claude-setup 1.1.4 → 1.1.5

package/dist/builder.js

@@ -240,6 +240,11 @@ export function buildAtomicSteps(collected, state) {
                 `\`⚠️ UNKNOWN PACKAGE — [service] MCP server not added: package name unverified. Find it at https://github.com/modelcontextprotocol/servers\`\n` +
                 `Do not add a placeholder. Do not guess.\n\n` +
                 `### OS-correct format (detected: ${os})\n` +
+                `**Preferred: use CLI to add (writes to .mcp.json automatically):**\n` +
+                (os === "Windows"
+                    ? `\`\`\`\nclaude mcp add --scope project --transport stdio <name> -- cmd /c npx -y <package>\n\`\`\`\n`
+                    : `\`\`\`\nclaude mcp add --scope project --transport stdio <name> -- npx -y <package>\n\`\`\`\n`) +
+                `**Or write .mcp.json directly:**\n` +
                 (os === "Windows"
                     ? `Use: \`{ "command": "cmd", "args": ["/c", "npx", "-y", "<package>"] }\`\n`
                     : `Use: \`{ "command": "npx", "args": ["-y", "<package>"] }\`\n`) +
@@ -270,6 +275,13 @@ export function buildAtomicSteps(collected, state) {
                     ? `\`{ "command": "cmd", "args": ["/c", "bun", "run", "\${CLAUDE_PLUGIN_ROOT}/servers/telegram"], "env": { "TELEGRAM_BOT_TOKEN": "\${TELEGRAM_BOT_TOKEN}" } }\`\n`
                     : `\`{ "command": "bun", "args": ["run", "\${CLAUDE_PLUGIN_ROOT}/servers/telegram"], "env": { "TELEGRAM_BOT_TOKEN": "\${TELEGRAM_BOT_TOKEN}" } }\`\n`) +
                 `After adding, flag: \`⚠️ CHANNEL ACTIVATION REQUIRED — launch with: claude --channels plugin:telegram@claude-plugins-official\`\n\n` +
+                `### Self-correction fallback\n` +
+                `If MCP configuration fails or produces warnings:\n` +
+                `1. Read the official MCP documentation: https://modelcontextprotocol.io/introduction\n` +
+                `2. Verify the package name against the MCP servers registry: https://github.com/modelcontextprotocol/servers\n` +
+                `3. Check the server's README for required env vars and correct args format\n` +
+                `4. Re-run \`npx claude-setup doctor\` to validate the fix\n` +
+                `Do NOT leave broken MCP configuration in place — either fix it or remove the entry.\n\n` +
                 `### Output\n` +
                 `Created/Updated: ✅ .mcp.json — [what server and evidence source]\n` +
                 `Skipped: ⏭ .mcp.json — checked [files], found [nothing], no action\n`,

package/dist/commands/add.js

@@ -4,7 +4,7 @@ import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildAddCommand } from "../builder.js";
-import { estimateTokens, estimateCost } from "../tokens.js";
+import { estimateTokens, estimateCost, formatCost } from "../tokens.js";
 import { c, section } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
@@ -59,6 +59,6 @@ capabilities that need documentation, MCP servers, skills, and hooks together.
     });
     console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-add")}`);
     section("Token cost");
-    console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)}`)})`);
+    console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`${formatCost(cost)}`)})`);
     console.log("");
 }

package/dist/commands/init.js

@@ -1,11 +1,11 @@
-import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs";
 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 { createSnapshot, collectFilesForSnapshot } from "../snapshot.js";
-import { estimateTokens, estimateCost } from "../tokens.js";
+import { estimateTokens, estimateCost, formatCost, getTokenHookScript, formatRealCostSummary } from "../tokens.js";
 import { c, section } from "../output.js";
 import { ensureConfig } from "../config.js";
 import { applyTemplate } from "./export.js";
@@ -13,6 +13,39 @@ function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
 }
+function installTokenHook(cwd = process.cwd()) {
+    // Write the hook script
+    const hooksDir = join(cwd, ".claude", "hooks");
+    if (!existsSync(hooksDir))
+        mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(join(hooksDir, "track-tokens.cjs"), getTokenHookScript(), "utf8");
+    // Merge Stop hook into settings.json
+    const settingsPath = join(cwd, ".claude", "settings.json");
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8") ?? "{}");
+        }
+        catch { }
+    }
+    const hookEntry = {
+        hooks: [{ type: "command", command: "node \".claude/hooks/track-tokens.cjs\"" }]
+    };
+    // Merge into settings.hooks.Stop
+    if (!settings.hooks)
+        settings.hooks = {};
+    const hooks = settings.hooks;
+    if (!Array.isArray(hooks.Stop))
+        hooks.Stop = [];
+    // Only add if not already present
+    const alreadyPresent = hooks.Stop.some(e => Array.isArray(e.hooks) && e.hooks.some((h) => typeof h.command === "string" && h.command.includes("track-tokens")));
+    if (!alreadyPresent) {
+        hooks.Stop.push(hookEntry);
+        if (!existsSync(join(cwd, ".claude")))
+            mkdirSync(join(cwd, ".claude"), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf8");
+    }
+}
 export async function runInit(opts = {}) {
     const dryRun = opts.dryRun ?? false;
     // Feature H: --template flag — apply a template instead of scanning
@@ -41,12 +74,13 @@ export async function runInit(opts = {}) {
             if (content.length > 500)
                 console.log(c.dim(`\n... +${content.length - 500} chars`));
             section("Token cost estimate");
-            console.log(`  ~${tokens.toLocaleString()} input tokens (Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)})`);
+            console.log(`  ~${tokens.toLocaleString()} input tokens (${formatCost(cost)})`);
             return;
         }
         ensureDir(".claude/commands");
         writeFileSync(".claude/commands/stack-init.md", content, "utf8");
         await updateManifest("init", collected, { estimatedTokens: tokens, estimatedCost: cost });
+        installTokenHook();
         // Feature A: Create initial snapshot node
         const cwd = process.cwd();
         const allPaths = [...Object.keys(collected.configs), ...collected.source.map(s => s.path)];
@@ -61,7 +95,15 @@ Open Claude Code and run:
 Claude Code will ask 3 questions, then set up your environment.
     `);
         section("Token cost");
-        console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)}`)})`);
+        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)}`)})`);
+            console.log(`  ${c.dim("Estimates only — real costs tracked after first Claude Code session")}`);
+        }
         console.log("");
         return;
     }
@@ -81,7 +123,7 @@ Claude Code will ask 3 questions, then set up your environment.
         console.log(`  .claude/commands/stack-init.md (orchestrator)`);
         console.log(`\n${c.dim(`Total: ~${tokens.toLocaleString()} tokens across ${steps.length} files`)}`);
         section("Token cost estimate");
-        console.log(`  ~${tokens.toLocaleString()} input tokens (Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)})`);
+        console.log(`  ~${tokens.toLocaleString()} input tokens (${formatCost(cost)})`);
         return;
     }
     ensureDir(".claude/commands");
@@ -90,6 +132,7 @@ Claude Code will ask 3 questions, then set up your environment.
     }
     writeFileSync(".claude/commands/stack-init.md", orchestrator, "utf8");
     await updateManifest("init", collected, { estimatedTokens: tokens, estimatedCost: cost });
+    installTokenHook();
     // Feature A: Create initial snapshot node
     const cwd = process.cwd();
     const allPaths = [...Object.keys(collected.configs), ...collected.source.map(s => s.path)];
@@ -104,6 +147,14 @@ ${c.green("✅")} Ready. Open Claude Code and run:
 Runs ${steps.length - 1} atomic steps. If one fails, re-run only that step.
   `);
     section("Token cost");
-    console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)}`)})`);
+    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)}`)})`);
+        console.log(`  ${c.dim("Estimates only — real costs tracked after first Claude Code session")}`);
+    }
     console.log("");
 }

package/dist/commands/remove.js

@@ -4,7 +4,7 @@ import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildRemoveCommand } from "../builder.js";
-import { estimateTokens, estimateCost } from "../tokens.js";
+import { estimateTokens, estimateCost, formatCost } from "../tokens.js";
 import { c, section } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
@@ -40,6 +40,6 @@ export async function runRemove() {
     });
     console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-remove")}`);
     section("Token cost");
-    console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)}`)})`);
+    console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`${formatCost(cost)}`)})`);
     console.log("");
 }

package/dist/commands/restore.js

@@ -1,4 +1,4 @@
-import { readTimeline, restoreSnapshot } from "../snapshot.js";
+import { readTimeline, restoreSnapshot, updateRestoredNode } from "../snapshot.js";
 import { c, section } from "../output.js";
 import { createInterface } from "readline";
 async function promptFreeText(question) {
@@ -20,10 +20,13 @@ export async function runRestore() {
     // Display timeline
     section("Snapshot timeline");
     console.log("");
+    const restoredTo = timeline.restoredTo;
     for (let i = 0; i < timeline.nodes.length; i++) {
         const node = timeline.nodes[i];
         const date = new Date(node.timestamp).toLocaleString();
-        const current = i === timeline.nodes.length - 1 ? ` ${c.green("← current")}` : "";
+        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 inputStr = node.input ? ` "${node.input}"` : "";
         console.log(`  ${c.cyan(node.id)}  ${node.command}${inputStr}  ${c.dim(date)}  ${node.summary}${current}`);
@@ -43,7 +46,8 @@ export async function runRestore() {
     }
     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`);
-    const result = restoreSnapshot(cwd, input);
+    const result = restoreSnapshot(cwd, input, timeline);
+    updateRestoredNode(cwd, input);
     if (result.restored.length) {
         section("Restored files");
         for (const f of result.restored) {
@@ -56,6 +60,37 @@ export async function runRestore() {
             console.log(`  ${c.red("🔴")} ${f}`);
         }
     }
-    console.log(`\n${c.green("✅")} Restored ${result.restored.length} file(s) to snapshot ${c.cyan(node.id)}.`);
-    console.log(`Run ${c.cyan("npx claude-setup sync")} to capture the current state as a new node.`);
+    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:")}`);
+        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.`);
+    }
+    else {
+        console.log(`\n${c.green("✅")} Restored ${result.restored.length} file(s) to snapshot ${c.cyan(node.id)}.`);
+    }
+    // Re-read and display updated timeline showing the restored position
+    const updatedTimeline = readTimeline(cwd);
+    console.log("");
+    section("Updated timeline");
+    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 inputStr = n.input ? ` "${n.input}"` : "";
+        console.log(`  ${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(`\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`);
 }

package/dist/commands/status.js

@@ -4,7 +4,7 @@ import { readManifest } from "../manifest.js";
 import { readState } from "../state.js";
 import { detectOS } from "../os.js";
 import { readTimeline } from "../snapshot.js";
-import { computeCumulativeStats, formatCost } from "../tokens.js";
+import { computeCumulativeStats, readRealTokenUsage, getProjectUsageSummary, readProjectSessions } from "../tokens.js";
 import { c, statusLine, section } from "../output.js";
 function safeJsonParse(content) {
     try {
@@ -89,33 +89,73 @@ export async function runStatus() {
         console.log(`  ${c.dim("Use")} ${c.cyan("npx claude-setup compare")} ${c.dim("to diff two snapshots")}`);
     }
     // --- Feature I: Token usage stats ---
-    const runsWithTokens = manifest.runs.filter(r => r.estimatedTokens !== undefined);
-    if (runsWithTokens.length > 0) {
-        section("Token usage");
-        const stats = computeCumulativeStats(manifest.runs);
-        console.log(`  Total tokens : ~${stats.totalTokens.toLocaleString()} across ${stats.runCount} run(s)`);
-        console.log(`  Total cost   : ${formatCost(stats.totalCost)}`);
-        // Average by command type
-        const avgEntries = Object.entries(stats.avgByCommand);
-        if (avgEntries.length > 0) {
-            console.log(`  Avg by type  :`);
-            for (const [cmd, avg] of avgEntries) {
-                console.log(`    ${cmd}: ~${avg.toLocaleString()} tokens/run`);
+    // Try JSONL transcripts first (ccusage-style, most accurate)
+    const projectSummary = getProjectUsageSummary(cwd);
+    if (projectSummary && projectSummary.totalTokens > 0) {
+        section("Token usage (real — from JSONL transcripts)");
+        console.log(`  Sessions tracked : ${projectSummary.sessions}`);
+        console.log(`  Total cost       : $${projectSummary.totalCost.toFixed(6)}`);
+        console.log(`  Input tokens     : ${projectSummary.inputTokens.toLocaleString()}`);
+        console.log(`  Output tokens    : ${projectSummary.outputTokens.toLocaleString()}`);
+        if (projectSummary.cacheCreateTokens > 0 || projectSummary.cacheReadTokens > 0) {
+            console.log(`  Cache write      : ${projectSummary.cacheCreateTokens.toLocaleString()}`);
+            console.log(`  Cache read       : ${projectSummary.cacheReadTokens.toLocaleString()}`);
+        }
+        console.log(`  Total tokens     : ${projectSummary.totalTokens.toLocaleString()}`);
+        if (projectSummary.models.length > 0) {
+            console.log(``);
+            console.log(`  Per model:`);
+            for (const m of projectSummary.models.sort((a, b) => b.cost - a.cost)) {
+                const shortName = m.model.replace(/^claude-/, "").replace(/-\d{8}$/, "");
+                console.log(`    ${shortName.padEnd(14)} ${m.totalTokens.toLocaleString().padStart(12)} tokens  $${m.cost.toFixed(6)}`);
+            }
+        }
+        // Show last 5 sessions
+        const sessions = readProjectSessions(cwd);
+        if (sessions.length > 0) {
+            console.log(``);
+            console.log(`  Recent sessions:`);
+            for (const s of sessions.slice(0, 5)) {
+                const date = s.timestamp ? new Date(s.timestamp).toLocaleString() : "unknown";
+                const primaryModel = s.models.sort((a, b) => b.cost - a.cost)[0]?.model ?? "unknown";
+                const shortModel = primaryModel.replace(/^claude-/, "").replace(/-\d{8}$/, "");
+                console.log(`    ${c.dim(date)}  ${shortModel}  ${s.totalTokens.toLocaleString()} tokens  $${s.totalCost.toFixed(6)}`);
             }
         }
-        // Cost trend (last 3 vs previous 3)
-        if (runsWithTokens.length >= 6) {
-            const recent3 = runsWithTokens.slice(-3);
-            const prev3 = runsWithTokens.slice(-6, -3);
-            const recentAvg = recent3.reduce((s, r) => s + (r.estimatedTokens ?? 0), 0) / 3;
-            const prevAvg = prev3.reduce((s, r) => s + (r.estimatedTokens ?? 0), 0) / 3;
-            const change = ((recentAvg - prevAvg) / prevAvg) * 100;
-            if (Math.abs(change) > 10) {
-                const trend = change > 0 ? c.yellow(`↑ +${change.toFixed(0)}%`) : c.green(`↓ ${change.toFixed(0)}%`);
-                console.log(`  Trend        : ${trend} (recent vs previous)`);
+    }
+    else {
+        // Fallback: Stop hook data
+        const realUsage = readRealTokenUsage(cwd);
+        if (realUsage.length > 0) {
+            section("Token usage (real — from Stop hook)");
+            const last5 = realUsage.slice(-5).reverse();
+            let totalCost = 0;
+            for (const r of realUsage)
+                totalCost += r.cost;
+            console.log(`  Sessions tracked : ${realUsage.length}`);
+            console.log(`  Total real cost  : $${totalCost.toFixed(6)}`);
+            console.log(``);
+            console.log(`  Recent sessions:`);
+            for (const r of last5) {
+                const date = new Date(r.timestamp).toLocaleString();
+                const tokens = r.inputTokens + r.outputTokens + r.cacheCreate + r.cacheRead;
+                console.log(`  ${c.dim(date)}  ${r.model.split('-').slice(1, 3).join('-')}  ${tokens.toLocaleString()} tokens  $${r.cost.toFixed(6)}`);
             }
-            else {
-                console.log(`  Trend        : ${c.green("→ stable")}`);
+        }
+        else {
+            // Fall back to estimates from manifest
+            const runsWithTokens = manifest.runs.filter(r => r.estimatedTokens !== undefined);
+            if (runsWithTokens.length > 0) {
+                section("Token usage (estimated — real data available after first Claude Code session)");
+                const stats = computeCumulativeStats(manifest.runs);
+                console.log(`  Total est. tokens: ~${stats.totalTokens.toLocaleString()} across ${stats.runCount} run(s)`);
+                const avgEntries = Object.entries(stats.avgByCommand);
+                if (avgEntries.length > 0) {
+                    console.log(`  Avg by type  :`);
+                    for (const [cmd, avg] of avgEntries) {
+                        console.log(`    ${cmd}: ~${avg.toLocaleString()} tokens/run`);
+                    }
+                }
             }
         }
     }

package/dist/commands/sync.js

@@ -1,17 +1,51 @@
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from "fs";
 import { join } from "path";
+import { glob } from "glob";
 import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { readManifest, sha256, updateManifest } from "../manifest.js";
 import { buildSyncCommand } from "../builder.js";
 import { createSnapshot, collectFilesForSnapshot } from "../snapshot.js";
-import { estimateTokens, estimateCost, formatTokenReport, buildTokenEstimate, generateHints } from "../tokens.js";
+import { estimateTokens, estimateCost, formatCost, formatTokenReport, buildTokenEstimate, generateHints, getTokenHookScript, formatRealCostSummary } from "../tokens.js";
 import { loadConfig } from "../config.js";
 import { c, section } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
 }
+function installTokenHook(cwd = process.cwd()) {
+    // Write the hook script
+    const hooksDir = join(cwd, ".claude", "hooks");
+    if (!existsSync(hooksDir))
+        mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(join(hooksDir, "track-tokens.cjs"), getTokenHookScript(), "utf8");
+    // Merge Stop hook into settings.json
+    const settingsPath = join(cwd, ".claude", "settings.json");
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8") ?? "{}");
+        }
+        catch { }
+    }
+    const hookEntry = {
+        hooks: [{ type: "command", command: "node \".claude/hooks/track-tokens.cjs\"" }]
+    };
+    // Merge into settings.hooks.Stop
+    if (!settings.hooks)
+        settings.hooks = {};
+    const hooks = settings.hooks;
+    if (!Array.isArray(hooks.Stop))
+        hooks.Stop = [];
+    // Only add if not already present
+    const alreadyPresent = hooks.Stop.some(e => Array.isArray(e.hooks) && e.hooks.some((h) => typeof h.command === "string" && h.command.includes("track-tokens")));
+    if (!alreadyPresent) {
+        hooks.Stop.push(hookEntry);
+        if (!existsSync(join(cwd, ".claude")))
+            mkdirSync(join(cwd, ".claude"), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf8");
+    }
+}
 function truncate(content, maxChars) {
     if (content.length <= maxChars)
         return content;
@@ -72,6 +106,23 @@ function computeDiff(snapshot, collected, cwd) {
     }
     return { added, changed, deleted };
 }
+async function collectClaudeInternalFiles(cwd) {
+    const files = [];
+    try {
+        const skillFiles = await glob(".claude/skills/**/*.md", { cwd, posix: true });
+        const allCmds = await glob(".claude/commands/*.md", { cwd, posix: true });
+        const commandFiles = allCmds.filter(f => !f.split("/").pop().startsWith("stack-"));
+        for (const f of [...skillFiles, ...commandFiles]) {
+            try {
+                const content = readFileSync(join(cwd, f), "utf8");
+                files.push({ path: f, content });
+            }
+            catch { /* skip unreadable */ }
+        }
+    }
+    catch { /* skip */ }
+    return files;
+}
 export async function runSync(opts = {}) {
     const dryRun = opts.dryRun ?? false;
     const manifest = await readManifest();
@@ -112,6 +163,30 @@ export async function runSync(opts = {}) {
         console.log("");
     const collected = await collectProjectFiles(cwd, "normal");
     const diff = computeDiff(lastRun.snapshot, collected, cwd);
+    // Bug 3 fix: Also detect changes inside .claude/ (skills, commands)
+    const claudeInternalFiles = await collectClaudeInternalFiles(cwd);
+    for (const f of claudeInternalFiles) {
+        const hash = sha256(f.content);
+        if (!lastRun.snapshot[f.path]) {
+            diff.added.push({ path: f.path, content: truncate(f.content, 2000) });
+        }
+        else if (lastRun.snapshot[f.path] !== hash) {
+            diff.changed.push({ path: f.path, current: truncate(f.content, 2000) });
+        }
+    }
+    // Also detect deleted .claude/ files (were in snapshot but no longer exist)
+    for (const path of Object.keys(lastRun.snapshot)) {
+        if ((path.startsWith(".claude/skills/") || (path.startsWith(".claude/commands/") && !path.split("/").pop().startsWith("stack-"))) && !path.includes("__digest__")) {
+            const alreadyInDiff = diff.added.some(f => f.path === path) ||
+                diff.changed.some(f => f.path === path) ||
+                diff.deleted.includes(path);
+            if (!alreadyInDiff && !claudeInternalFiles.some(f => f.path === path)) {
+                if (!existsSync(join(cwd, path))) {
+                    diff.deleted.push(path);
+                }
+            }
+        }
+    }
     if (!diff.added.length && !diff.changed.length && !diff.deleted.length && !oobDetected) {
         console.log(`${c.green("✅")} No changes since ${c.dim(lastRun.at)}. Setup is current.`);
         return;
@@ -145,13 +220,19 @@ export async function runSync(opts = {}) {
         console.log(formatTokenReport(estimate));
         return;
     }
+    // Add .claude/ internal files to snapshot
+    for (const f of claudeInternalFiles) {
+        collected.configs[f.path] = f.content;
+    }
     ensureDir(".claude/commands");
     writeFileSync(".claude/commands/stack-sync.md", content, "utf8");
     await updateManifest("sync", collected, { estimatedTokens: tokens, estimatedCost: cost });
+    installTokenHook();
     // Feature A: Create snapshot node
     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;
@@ -167,7 +248,15 @@ ${c.green("✅")} Ready. Open Claude Code and run:
   `);
     // Token cost display
     section("Token cost");
-    console.log(`  ~${tokens.toLocaleString()} input tokens (${c.dim(`Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)}`)})`);
+    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")}`);
+    }
     // Optimization hints
     const runs = manifest.runs.map(r => ({ command: r.command, estimatedTokens: r.estimatedTokens }));
     const hints = generateHints(runs, tokens, config.tokenBudget.sync);

package/dist/doctor.js

@@ -116,6 +116,7 @@ export async function runDoctor(verbose = false, fix = false, testHooks = false)
     // --- Check 3: OS/MCP format mismatch ---
     if (state.mcpJson.content) {
         section("MCP servers");
+        const mcpWarningsBefore = counts.warnings + counts.critical;
         const mcp = safeJsonParse(state.mcpJson.content);
         if (mcp && typeof mcp.mcpServers === "object" && mcp.mcpServers !== null) {
             const servers = mcp.mcpServers;
@@ -182,6 +183,12 @@ export async function runDoctor(verbose = false, fix = false, testHooks = false)
                         }
                     }
                 }
+                // Check if server has no env vars but uses npx (might fail on first run due to npm download)
+                if (!config.env && (cmd === "npx" || (cmd === "cmd" && config.args?.includes("npx")))) {
+                    if (verbose) {
+                        statusLine("💡", name, c.dim("uses npx — will download package on first run (requires internet)"));
+                    }
+                }
             }
             // Check for channel-type servers
             const channelNames = ["telegram", "discord", "fakechat"];
@@ -203,6 +210,12 @@ export async function runDoctor(verbose = false, fix = false, testHooks = false)
             if (verbose)
                 statusLine("⚠️ ", ".mcp.json", "no mcpServers key found");
         }
+        if (counts.warnings + counts.critical > mcpWarningsBefore) {
+            console.log(`\n  ${c.dim("MCP self-correction:")}`);
+            console.log(`  • ${c.cyan("npx claude-setup doctor --fix")} — auto-fix OS format and -y flag`);
+            console.log(`  • Set missing env vars, then re-run ${c.cyan("npx claude-setup doctor")}`);
+            console.log(`  • Verify server packages: https://github.com/modelcontextprotocol/servers`);
+        }
     }
     else if (verbose) {
         section("MCP servers");
@@ -389,13 +402,23 @@ export async function runDoctor(verbose = false, fix = false, testHooks = false)
             const template = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? readIfExists(".env.template") ?? "";
             section("Env vars");
             for (const v of unique) {
-                if (template.includes(v)) {
-                    statusLine("✅", `\${${v}}`, "found in env template");
+                const isActuallySet = process.env[v] !== undefined && process.env[v] !== "";
+                const isInTemplate = template.includes(v);
+                if (isActuallySet) {
+                    statusLine("✅", `\${${v}}`, "set in environment");
                     counts.healthy++;
                 }
+                else if (isInTemplate) {
+                    statusLine("🔴", `\${${v}}`, c.red(`NOT SET — MCP server will fail at runtime.\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.yellow("used in .mcp.json but missing from .env.example"));
-                    counts.warnings++;
+                    statusLine("🔴", `\${${v}}`, c.red(`NOT SET — MCP server will fail at runtime.\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/marketplace.d.ts

@@ -6,6 +6,19 @@
  */
 export declare const MARKETPLACE_REPO = "jeremylongshore/claude-code-plugins-plus-skills";
 export declare const MARKETPLACE_CATALOG_URL = "https://raw.githubusercontent.com/jeremylongshore/claude-code-plugins-plus-skills/main/.claude-plugin/marketplace.extended.json";
+/** Additional marketplace sources for broader coverage */
+export declare const ADDITIONAL_MARKETPLACE_SOURCES: readonly [{
+    readonly name: "claude-plugins-official";
+    readonly description: "Official Anthropic plugins (GitHub, Slack, Linear, Notion, etc.)";
+    readonly installPrefix: "claude-plugins-official";
+    readonly note: "No marketplace add needed — available by default";
+}, {
+    readonly name: "awesome-claude-code";
+    readonly description: "Community collection of Claude Code skills and workflows";
+    readonly catalogUrl: "https://raw.githubusercontent.com/hesreallyhim/awesome-claude-code/main/catalog.json";
+    readonly installPrefix: null;
+    readonly note: "Browse and manually install skills";
+}];
 /** The 20 skill categories in the marketplace */
 export declare const SKILL_CATEGORIES: readonly ["01-code-quality", "02-testing", "03-security", "04-devops", "05-api-development", "06-database", "07-frontend", "08-backend", "09-mobile", "10-data-science", "11-documentation", "12-project-management", "13-communication", "14-research", "15-content-creation", "16-business", "17-finance", "18-visual-content", "19-legal", "20-productivity"];
 /** SaaS packs available in the marketplace */
@@ -17,5 +30,5 @@ export declare function classifyRequest(input: string): {
     categories: string[];
     saasMatches: string[];
 };
-/** Generate marketplace search instructions for the add template */
+/** Generate fully-automated marketplace search and install instructions */
 export declare function buildMarketplaceInstructions(input: string): string;