claude-setup 1.1.1 → 1.1.3

package/dist/doctor.js

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from "fs";
 import { execSync } from "child_process";
+import { join } from "path";
 import { readManifest } from "./manifest.js";
 import { readState } from "./state.js";
+import { detectOS } from "./os.js";
+import { c, statusLine, section } from "./output.js";
 function tryExec(cmd) {
     try {
         return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
@@ -20,53 +23,347 @@ function readIfExists(filePath) {
         return null;
     }
 }
-function line(icon, label, detail) {
-    console.log(`  ${icon} ${label}${detail ? ` — ${detail}` : ""}`);
+function safeJsonParse(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
 }
-export async function runDoctor() {
+export async function runDoctor(verbose = false) {
+    const os = detectOS();
     const manifest = await readManifest();
     const state = await readState();
-    console.log("claude-setup doctor\n");
-    // Claude Code installed?
+    const counts = { critical: 0, warnings: 0, healthy: 0 };
+    console.log(`${c.bold("claude-setup doctor")} — ${new Date().toISOString().split("T")[0]} | OS: ${os}\n`);
+    // --- Check 1: Claude Code version ---
+    section("Environment");
     const cv = tryExec("claude --version");
-    line(cv ? "✅" : "❌", "Claude Code", cv?.trim() ?? "not found");
-    // Manifest?
+    if (cv) {
+        statusLine("✅", "Claude Code", cv.trim());
+        counts.healthy++;
+    }
+    else {
+        statusLine("🔴", "Claude Code", c.red("not found in PATH"));
+        counts.critical++;
+    }
+    // --- Check 2: Manifest integrity ---
     const lastRun = manifest?.runs.at(-1);
-    line(manifest ? "✅" : "⚠️ ", ".claude/claude-setup.json", manifest ? `last: ${lastRun?.command} at ${lastRun?.at}` : "not found — run: npx claude-setup init");
-    // Files from last run still on disk?
-    if (lastRun?.filesRead.length) {
-        console.log("\nFiles from last run (sample):");
-        for (const f of lastRun.filesRead.slice(0, 8)) {
-            line(existsSync(f) ? "✅" : "⚠️ ", f, existsSync(f) ? "" : "not found on disk");
+    if (manifest) {
+        const staleCheck = lastRun ? checkStaleness(lastRun.at) : null;
+        const detail = lastRun
+            ? `last: ${lastRun.command} at ${lastRun.at}${staleCheck ? ` ${staleCheck}` : ""}`
+            : "empty runs array";
+        statusLine("✅", "Manifest", detail);
+        counts.healthy++;
+    }
+    else {
+        statusLine("⚠️ ", "Manifest", c.yellow("not found — run: npx claude-setup init"));
+        counts.warnings++;
+    }
+    // --- Check 2b: Out-of-band edit detection ---
+    if (lastRun) {
+        const { createHash } = await import("crypto");
+        const oobFiles = [
+            { label: "CLAUDE.md", path: join(process.cwd(), "CLAUDE.md"), snapshotKey: "CLAUDE.md" },
+            { label: ".mcp.json", path: join(process.cwd(), ".mcp.json"), snapshotKey: ".mcp.json" },
+            { label: "settings.json", path: join(process.cwd(), ".claude", "settings.json"), snapshotKey: ".claude/settings.json" },
+        ];
+        for (const mf of oobFiles) {
+            if (!existsSync(mf.path))
+                continue;
+            const content = readFileSync(mf.path, "utf8");
+            const currentHash = createHash("sha256").update(content).digest("hex");
+            const snapshotHash = lastRun.snapshot[mf.snapshotKey];
+            if (snapshotHash && currentHash !== snapshotHash) {
+                statusLine("⚠️ ", mf.label, c.yellow("modified outside the CLI since last run — run sync to re-snapshot"));
+                counts.warnings++;
+            }
         }
     }
-    // Env vars in .mcp.json present in env template?
+    // --- Check 3: OS/MCP format mismatch ---
+    if (state.mcpJson.content) {
+        section("MCP servers");
+        const mcp = safeJsonParse(state.mcpJson.content);
+        if (mcp && typeof mcp.mcpServers === "object" && mcp.mcpServers !== null) {
+            const servers = mcp.mcpServers;
+            for (const [name, config] of Object.entries(servers)) {
+                const cmd = config.command;
+                if (!cmd) {
+                    statusLine("⚠️ ", name, c.yellow("no command field"));
+                    counts.warnings++;
+                    continue;
+                }
+                if (os === "Windows" && cmd === "npx") {
+                    statusLine("🔴", name, c.red(`BROKEN: Windows can't execute npx directly — use cmd /c npx`));
+                    counts.critical++;
+                }
+                else if (os !== "Windows" && cmd === "cmd") {
+                    statusLine("⚠️ ", name, c.yellow(`UNNECESSARY: cmd wrapper not needed on ${os}`));
+                    counts.warnings++;
+                }
+                else {
+                    statusLine("✅", name, `valid, OS-format correct (${cmd})`);
+                    counts.healthy++;
+                }
+                // Check for missing -y flag in npx args
+                const args = config.args;
+                if (args) {
+                    const npxIndex = args.indexOf("npx");
+                    if (npxIndex >= 0 && args[npxIndex + 1] !== "-y") {
+                        statusLine("⚠️ ", name, c.yellow(`npx without -y flag — installs may hang`));
+                        counts.warnings++;
+                    }
+                    // Check for hardcoded connection strings in args
+                    for (const arg of args) {
+                        if (/^(postgresql|postgres|mysql|mongodb|redis|amqp):\/\//.test(arg)) {
+                            statusLine("🔴", name, c.red(`HARDCODED connection string in args — move to env: { "DATABASE_URL": "\${DATABASE_URL}" }`));
+                            counts.critical++;
+                            break;
+                        }
+                    }
+                }
+            }
+            // Check for channel-type servers
+            const channelNames = ["telegram", "discord", "fakechat"];
+            for (const [name] of Object.entries(servers)) {
+                if (channelNames.includes(name.toLowerCase())) {
+                    statusLine("⚠️ ", `${name} (CHANNEL)`, c.yellow(`channel server detected — .mcp.json alone does not activate delivery. ` +
+                        `Launch with: claude --channels plugin:${name.toLowerCase()}@claude-plugins-official`));
+                    counts.warnings++;
+                }
+            }
+        }
+        else if (mcp) {
+            // Check for flat structure (some .mcp.json files use flat keys)
+            if (verbose)
+                statusLine("⚠️ ", ".mcp.json", "no mcpServers key found");
+        }
+    }
+    else if (verbose) {
+        section("MCP servers");
+        statusLine("⏭ ", ".mcp.json", "does not exist");
+    }
+    // --- Check 4: Hook quoting bugs ---
+    if (state.settings.content) {
+        section("Hooks");
+        const settings = safeJsonParse(state.settings.content);
+        if (settings) {
+            const hookCategories = [
+                "PreToolUse", "PostToolUse", "PostToolUseFailure",
+                "Stop", "SessionStart"
+            ];
+            // Bug 6: Check for model override
+            if (settings["model"]) {
+                statusLine("⚠️ ", "MODEL OVERRIDE", c.yellow(`"model": "${settings["model"]}" in settings.json forces this model on every session. Remove it if not intentional.`));
+                counts.warnings++;
+            }
+            // Check for invalid hook event names
+            const validHookNames = new Set(hookCategories);
+            for (const key of Object.keys(settings)) {
+                if (key === "permissions" || key === "model" || key === "env" || key === "allowedTools")
+                    continue;
+                if (Array.isArray(settings[key]) && !validHookNames.has(key)) {
+                    statusLine("🔴", `"${key}"`, c.red(`INVALID hook event name. Valid names: ${hookCategories.join(", ")}`));
+                    counts.critical++;
+                }
+            }
+            let foundHooks = false;
+            for (const category of hookCategories) {
+                const hooks = settings[category];
+                if (!hooks || !Array.isArray(hooks))
+                    continue;
+                for (const hook of hooks) {
+                    if (typeof hook !== "object" || !hook)
+                        continue;
+                    const h = hook;
+                    const hookCmd = h.command;
+                    const args = h.args;
+                    if (!hookCmd || !args)
+                        continue;
+                    foundHooks = true;
+                    // Check for bash -c quoting bugs
+                    if (hookCmd === "bash" && args[0] === "-c" && args[1]) {
+                        const shellStr = args[1];
+                        const quotingIssue = checkBashQuoting(shellStr);
+                        if (quotingIssue) {
+                            statusLine("🔴", `${category} hook`, c.red(`quoting bug: ${quotingIssue}`));
+                            counts.critical++;
+                        }
+                        else {
+                            statusLine("✅", `${category} hook`, "quoting clean");
+                            counts.healthy++;
+                        }
+                    }
+                    else {
+                        statusLine("✅", `${category} hook`, "valid");
+                        counts.healthy++;
+                    }
+                }
+            }
+            if (!foundHooks && verbose) {
+                statusLine("⏭ ", "Hooks", "none configured");
+            }
+        }
+    }
+    else if (verbose) {
+        section("Hooks");
+        statusLine("⏭ ", "settings.json", "does not exist");
+    }
+    // --- Check 5: Env var coverage ---
     if (state.mcpJson.content) {
         const refs = [...state.mcpJson.content.matchAll(/\$\{?([A-Z_][A-Z0-9_]+)\}?/g)]
             .map(m => m[1]);
         const unique = [...new Set(refs)];
         if (unique.length) {
-            const template = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? "";
-            console.log("\nMCP environment variables:");
+            const template = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? readIfExists(".env.template") ?? "";
+            section("Env vars");
             for (const v of unique) {
-                line(template.includes(v) ? "✅" : "⚠️ ", v, template.includes(v) ? "found in env template" : "missing from .env.example");
+                if (template.includes(v)) {
+                    statusLine("✅", `\${${v}}`, "found in env template");
+                    counts.healthy++;
+                }
+                else {
+                    statusLine("⚠️ ", `\${${v}}`, c.yellow("used in .mcp.json but missing from .env.example"));
+                    counts.warnings++;
+                }
             }
         }
     }
-    // Workflow secrets
+    // --- Check 6: Workflow secret coverage ---
     if (state.workflows.length) {
         const secrets = new Set();
         for (const wf of state.workflows) {
             const content = readIfExists(wf) ?? "";
-            for (const m of content.matchAll(/\$\{\{\s*secrets\.([A-Z_]+)\s*\}\}/g)) {
+            for (const m of content.matchAll(/\$\{\{\s*secrets\.([A-Z_][A-Z0-9_]*)\s*\}\}/g)) {
                 secrets.add(m[1]);
             }
         }
         if (secrets.size) {
-            console.log("\nWorkflow secrets (add to GitHub Settings → Secrets):");
-            for (const s of secrets)
-                console.log(`  ⚠️  ${s}`);
+            section("Workflow secrets");
+            const readme = readIfExists("README.md") ?? "";
+            const envTemplate = readIfExists(".env.example") ?? readIfExists(".env.sample") ?? "";
+            for (const s of secrets) {
+                if (readme.includes(s) || envTemplate.includes(s)) {
+                    statusLine("✅", s, "documented");
+                    counts.healthy++;
+                }
+                else {
+                    statusLine("⚠️ ", s, c.yellow("needs GitHub Settings → Secrets"));
+                    counts.warnings++;
+                }
+            }
         }
     }
-    console.log("\n✅ Done.");
+    // --- Check 7: Stale skill paths ---
+    if (state.skills.length) {
+        section("Skills");
+        for (const skillPath of state.skills) {
+            const content = readIfExists(skillPath);
+            if (!content) {
+                statusLine("⚠️ ", skillPath, c.yellow("skill file not readable"));
+                counts.warnings++;
+                continue;
+            }
+            // Extract file/dir references from skill content
+            const pathRefs = extractPathReferences(content);
+            const staleRefs = pathRefs.filter(ref => !existsSync(ref) && !existsSync(join(process.cwd(), ref)));
+            if (staleRefs.length) {
+                statusLine("⚠️ ", skillPath, c.yellow(`stale paths: ${staleRefs.join(", ")}`));
+                counts.warnings++;
+            }
+            else {
+                statusLine("✅", skillPath, "valid");
+                counts.healthy++;
+            }
+        }
+    }
+    else if (verbose) {
+        section("Skills");
+        statusLine("⏭ ", "Skills", "none installed");
+    }
+    // --- Check 8: Files from last run still on disk ---
+    // Filter __digest__ — it's a virtual key, not a real file
+    if (lastRun?.filesRead.length && verbose) {
+        section("Files from last run");
+        const realFiles = lastRun.filesRead.filter(f => f !== "__digest__" && f !== ".env");
+        for (const f of realFiles.slice(0, 8)) {
+            if (existsSync(f)) {
+                statusLine("✅", f, "");
+                counts.healthy++;
+            }
+            else {
+                statusLine("⚠️ ", f, c.yellow("not found on disk"));
+                counts.warnings++;
+            }
+        }
+        if (realFiles.length > 8) {
+            console.log(c.dim(`  ... +${realFiles.length - 8} more`));
+        }
+    }
+    // --- Summary ---
+    console.log("");
+    section("Summary");
+    if (counts.critical > 0)
+        console.log(`  🔴 ${c.red(`${counts.critical} critical`)} (will break Claude Code)`);
+    if (counts.warnings > 0)
+        console.log(`  ⚠️  ${c.yellow(`${counts.warnings} warning(s)`)} (degraded behavior)`);
+    console.log(`  ✅ ${c.green(`${counts.healthy} healthy`)}`);
+    if (counts.critical > 0) {
+        console.log(`\n${c.red("Fix critical issues first.")} Run ${c.cyan("npx claude-setup sync")} after fixing.`);
+    }
+    else {
+        console.log(`\n${c.green("✅ Done.")}`);
+    }
+}
+// --- Helpers ---
+function checkStaleness(lastRunDate) {
+    try {
+        const last = new Date(lastRunDate).getTime();
+        const now = Date.now();
+        const daysSince = Math.floor((now - last) / (1000 * 60 * 60 * 24));
+        if (daysSince > 7)
+            return c.yellow(`(${daysSince} days ago — may be stale)`);
+    }
+    catch { /* invalid date */ }
+    return null;
+}
+function checkBashQuoting(shellStr) {
+    // Check for unescaped double quotes inside the command string
+    // The -c "..." outer string must never contain a bare " character
+    let inSingleQuote = false;
+    let prevChar = "";
+    for (let i = 0; i < shellStr.length; i++) {
+        const ch = shellStr[i];
+        if (ch === "'" && prevChar !== "\\") {
+            inSingleQuote = !inSingleQuote;
+        }
+        // Unescaped double quote inside single-quoted context is a problem
+        // when the outer wrapper is double quotes
+        if (ch === '"' && !inSingleQuote && prevChar !== "\\") {
+            // Check for patterns like ["'] which mix quote types
+            if (i > 0 && shellStr[i - 1] === "[") {
+                return `mixed quotes in character class at position ${i}: ...${shellStr.slice(Math.max(0, i - 10), i + 10)}...`;
+            }
+        }
+        prevChar = ch;
+    }
+    // Check for unmatched brackets in grep patterns
+    const bracketCount = (shellStr.match(/\[/g) || []).length;
+    const closeBracketCount = (shellStr.match(/\]/g) || []).length;
+    if (bracketCount !== closeBracketCount) {
+        return "unmatched brackets in pattern";
+    }
+    return null;
+}
+function extractPathReferences(skillContent) {
+    const paths = [];
+    // Match file/directory references in skill content
+    // Look for patterns like src/, lib/, *.ts references
+    const pathPatterns = skillContent.matchAll(/(?:^|\s)((?:src|lib|app|cmd|bin|pkg|internal|api|core|test|tests|spec)\/[\w/.\\-]*)/gm);
+    for (const m of pathPatterns) {
+        paths.push(m[1].trim());
+    }
+    return paths;
 }

package/dist/index.js

@@ -5,20 +5,42 @@ import { runInit } from "./commands/init.js";
 import { runAdd } from "./commands/add.js";
 import { runSync } from "./commands/sync.js";
 import { runStatus } from "./commands/status.js";
-import { runDoctor } from "./commands/doctor.js";
+import { runDoctorCommand } from "./commands/doctor.js";
 import { runRemove } from "./commands/remove.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
 const program = new Command();
 program
     .name("claude-setup")
-    .description("Setup layer for Claude Code")
+    .description("Setup layer for Claude Code — reads your project, writes command files, Claude Code does the rest")
     .version(pkg.version);
-program.command("init").description("Full project setup — new or existing").action(runInit);
-program.command("add").description("Add a multi-file capability").action(runAdd);
-program.command("sync").description("Update setup after project changes").action(runSync);
-program.command("status").description("Show current setup (instant)").action(runStatus);
-program.command("doctor").description("Validate environment").action(runDoctor);
-program.command("remove").description("Remove a capability cleanly").action(runRemove);
-program.action(runInit);
+program
+    .command("init")
+    .description("Full project setup — new or existing")
+    .option("--dry-run", "Preview what would be written without writing")
+    .action((opts) => runInit({ dryRun: opts.dryRun }));
+program
+    .command("add")
+    .description("Add a multi-file capability")
+    .action(runAdd);
+program
+    .command("sync")
+    .description("Update setup after project changes")
+    .option("--dry-run", "Preview changes without writing")
+    .action((opts) => runSync({ dryRun: opts.dryRun }));
+program
+    .command("status")
+    .description("Show current setup state (instant, no file reads)")
+    .action(runStatus);
+program
+    .command("doctor")
+    .description("Validate environment — OS, MCP, hooks, env vars, skills")
+    .option("-v, --verbose", "Show passing checks too")
+    .action((opts) => runDoctorCommand({ verbose: opts.verbose }));
+program
+    .command("remove")
+    .description("Remove a capability cleanly")
+    .action(runRemove);
+// Default action when no command given
+program.action(() => runInit({}));
 program.parse();

package/dist/manifest.js

@@ -47,6 +47,18 @@ export async function updateManifest(command, collected, opts = {}) {
     for (const { path, content } of collected.source) {
         snapshot[path] = sha256(content);
     }
+    // Also snapshot CLI-managed files for out-of-band edit detection
+    const managedFiles = [
+        { key: "CLAUDE.md", path: join(cwd, "CLAUDE.md") },
+        { key: ".mcp.json", path: join(cwd, ".mcp.json") },
+        { key: ".claude/settings.json", path: join(cwd, ".claude", "settings.json") },
+    ];
+    for (const mf of managedFiles) {
+        if (existsSync(mf.path)) {
+            const content = readFileSync(mf.path, "utf8");
+            snapshot[mf.key] = sha256(content);
+        }
+    }
     const filesRead = [
         ...Object.keys(collected.configs),
         ...collected.source.map(s => s.path),

package/dist/os.d.ts

@@ -0,0 +1,25 @@
+export type DetectedOS = "Windows" | "macOS" | "Linux";
+/**
+ * Detect OS once per session. Order per spec:
+ * 1. COMSPEC set → Windows
+ * 2. OS === "Windows_NT" → Windows
+ * 3. process.platform === "win32" → Windows
+ * 4. uname() === "Darwin" → macOS
+ * 5. default → Linux
+ */
+export declare function detectOS(): DetectedOS;
+/**
+ * Verified MCP package names — ONLY use these.
+ * If a service is not in this map, do not guess a package name.
+ */
+export declare const VERIFIED_MCP_PACKAGES: Record<string, string>;
+/** MCP command format per OS — always includes -y to prevent npx install hangs */
+export declare function mcpCommandFormat(os: DetectedOS, pkg: string): {
+    command: string;
+    args: string[];
+};
+/** Hook shell format per OS */
+export declare function hookShellFormat(os: DetectedOS, cmd: string): {
+    command: string;
+    args: string[];
+};

package/dist/os.js

@@ -0,0 +1,52 @@
+import { execSync } from "child_process";
+/**
+ * Detect OS once per session. Order per spec:
+ * 1. COMSPEC set → Windows
+ * 2. OS === "Windows_NT" → Windows
+ * 3. process.platform === "win32" → Windows
+ * 4. uname() === "Darwin" → macOS
+ * 5. default → Linux
+ */
+export function detectOS() {
+    if (process.env.COMSPEC)
+        return "Windows";
+    if (process.env.OS === "Windows_NT")
+        return "Windows";
+    if (process.platform === "win32")
+        return "Windows";
+    try {
+        const uname = execSync("uname", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        if (uname === "Darwin")
+            return "macOS";
+    }
+    catch { /* not unix — unlikely to reach here */ }
+    return "Linux";
+}
+/**
+ * Verified MCP package names — ONLY use these.
+ * If a service is not in this map, do not guess a package name.
+ */
+export const VERIFIED_MCP_PACKAGES = {
+    playwright: "@playwright/mcp@latest",
+    postgres: "@modelcontextprotocol/server-postgres",
+    filesystem: "@modelcontextprotocol/server-filesystem",
+    memory: "@modelcontextprotocol/server-memory",
+    github: "@modelcontextprotocol/server-github",
+    brave: "@modelcontextprotocol/server-brave-search",
+    puppeteer: "@modelcontextprotocol/server-puppeteer",
+    slack: "@modelcontextprotocol/server-slack",
+};
+/** MCP command format per OS — always includes -y to prevent npx install hangs */
+export function mcpCommandFormat(os, pkg) {
+    if (os === "Windows") {
+        return { command: "cmd", args: ["/c", "npx", "-y", pkg] };
+    }
+    return { command: "npx", args: ["-y", pkg] };
+}
+/** Hook shell format per OS */
+export function hookShellFormat(os, cmd) {
+    if (os === "Windows") {
+        return { command: "cmd", args: ["/c", cmd] };
+    }
+    return { command: "bash", args: ["-c", cmd] };
+}

package/dist/output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Terminal output helpers — no dependencies.
+ * Raw ANSI codes. Falls back gracefully if NO_COLOR or piped.
+ */
+export declare const c: {
+    bold: (t: string) => string;
+    dim: (t: string) => string;
+    red: (t: string) => string;
+    green: (t: string) => string;
+    yellow: (t: string) => string;
+    blue: (t: string) => string;
+    cyan: (t: string) => string;
+    gray: (t: string) => string;
+};
+/** Print a status line: icon + label + optional detail */
+export declare function statusLine(icon: string, label: string, detail?: string): void;
+/** Print a section header */
+export declare function section(title: string): void;

package/dist/output.js

@@ -0,0 +1,40 @@
+/**
+ * Terminal output helpers — no dependencies.
+ * Raw ANSI codes. Falls back gracefully if NO_COLOR or piped.
+ */
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const codes = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+};
+function wrap(code, text) {
+    if (!supportsColor)
+        return text;
+    return `${code}${text}${codes.reset}`;
+}
+export const c = {
+    bold: (t) => wrap(codes.bold, t),
+    dim: (t) => wrap(codes.dim, t),
+    red: (t) => wrap(codes.red, t),
+    green: (t) => wrap(codes.green, t),
+    yellow: (t) => wrap(codes.yellow, t),
+    blue: (t) => wrap(codes.blue, t),
+    cyan: (t) => wrap(codes.cyan, t),
+    gray: (t) => wrap(codes.gray, t),
+};
+/** Print a status line: icon + label + optional detail */
+export function statusLine(icon, label, detail) {
+    const detailStr = detail ? ` — ${detail}` : "";
+    console.log(`  ${icon} ${label}${detailStr}`);
+}
+/** Print a section header */
+export function section(title) {
+    console.log(`\n${c.bold(title)}`);
+}

package/dist/state.js

@@ -9,9 +9,13 @@ export async function readState(cwd = process.cwd()) {
     const claudeMd = readIfExists(claudeMdPath);
     const mcpJson = readIfExists(mcpJsonPath);
     const settings = readIfExists(settingsPath);
+    // Scan all three skill patterns and deduplicate (Bug 4 fix)
     let skills = [];
     try {
-        skills = await glob(".claude/skills/*/SKILL.md", { cwd, posix: true });
+        const structured = await glob(".claude/skills/*/SKILL.md", { cwd, posix: true });
+        const flat = await glob(".claude/skills/*.md", { cwd, posix: true });
+        const nested = await glob(".claude/skills/**/*.md", { cwd, posix: true });
+        skills = [...new Set([...structured, ...flat, ...nested])];
     }
     catch { /* no skills */ }
     let commands = [];

package/package.json

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

package/templates/add.md

@@ -5,7 +5,7 @@ Add to Claude Code setup: "{{USER_INPUT}}"
 ## Project context
 {{PROJECT_CONTEXT}}
 
-## Current setup
+## Current setup — read before writing anything
 
 {{#if HAS_CLAUDE_MD}}
 ### CLAUDE.md
@@ -25,9 +25,13 @@ Add to Claude Code setup: "{{USER_INPUT}}"
 Skills: {{SKILLS_LIST}} | Commands: {{COMMANDS_LIST}}
 
 ## Rules
-- Read current content before writing. Merge/append only.
-- If request mentions something not in project files: ask first.
+- Read current content above before writing. Merge/append only.
+- If request mentions something not evidenced in project files: ask first.
+- OS detected: {{DETECTED_OS}}. Use correct command format for MCP/hooks:
+  - Windows: `{ "command": "cmd", "args": ["/c", "npx", "<pkg>"] }`
+  - macOS/Linux: `{ "command": "npx", "args": ["<pkg>"] }`
+- All env var refs use `${VARNAME}` syntax. Document new vars in .env.example.
 
 ## Output — one line per file
 Updated: ✅ [path] — [what and why]
-Skipped: ⏭ [path] — [why]
+Skipped: ⏭ [path] — [why not needed for this request]