claude-setup 1.1.1 → 1.1.3

package/README.md

@@ -1,45 +1,96 @@
-# claude-setup
-
-Setup layer for Claude Code. Reads your project, writes command files, Claude Code does the rest.
-
-## Install
-
-```bash
-npx claude-setup init
-```
-
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `npx claude-setup init` | Full project setup — new or existing |
-| `npx claude-setup add` | Add a multi-file capability |
-| `npx claude-setup sync` | Update setup after project changes |
-| `npx claude-setup status` | Show current setup |
-| `npx claude-setup doctor` | Validate environment |
-| `npx claude-setup remove` | Remove a capability cleanly |
-
-## How it works
-
-1. **CLI collects** — reads project files (configs, source samples) with strict cost controls
-2. **CLI writes command files** — assembles markdown instructions into `.claude/commands/`
-3. **Claude Code executes** — you run `/stack-init` (or `/stack-sync`, etc.) in Claude Code
-
-The CLI has zero intelligence. All reasoning is delegated to Claude Code via the command files.
-
-## Three project states
-
-- **Empty project** — Claude Code asks 3 discovery questions, then sets up a tailored environment
-- **In development** — reads existing files, writes setup that references actual code patterns
-- **Production** — same as development; merge rules protect existing Claude config (append only, never rewrite)
-
-## What it creates
-
-- `CLAUDE.md` — project-specific context for Claude Code
-- `.mcp.json` — MCP server connections (only if evidenced by project files)
-- `.claude/settings.json` — hooks (only if warranted)
-- `.claude/skills/` — reusable patterns (only if recurring)
-- `.claude/commands/` — project-specific slash commands
-- `.github/workflows/` — CI workflows (only if `.github/` exists)
-
-
+# claude-setup
+
+Setup layer for Claude Code. Reads your project, writes command files, Claude Code does the rest.
+
+**The CLI has zero intelligence.** All reasoning is delegated to Claude Code via the command files. The CLI reads files. Claude Code decides.
+
+## Install & Quick Start
+
+```bash
+npx claude-setup init
+```
+
+Then open Claude Code and run `/stack-init`.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npx claude-setup init` | Full project setup — new or existing. Detects empty projects automatically. |
+| `npx claude-setup add` | Add a multi-file capability (MCP + hooks + skills together) |
+| `npx claude-setup sync` | Update setup after project changes (uses diff, not full re-scan) |
+| `npx claude-setup status` | Show current setup state — OS, servers, hooks, staleness |
+| `npx claude-setup doctor` | Validate environment — OS/MCP format, hook quoting, env vars, stale skills |
+| `npx claude-setup remove` | Remove a capability cleanly with dangling reference detection |
+
+### Flags
+
+```bash
+npx claude-setup init --dry-run    # Preview without writing
+npx claude-setup sync --dry-run    # Show changes without writing
+npx claude-setup doctor --verbose  # Include passing checks in output
+```
+
+## How it works
+
+1. **CLI collects** — reads project files (configs, source samples) with strict token cost controls
+2. **CLI writes command files** — assembles markdown instructions into `.claude/commands/`
+3. **Claude Code executes** — you run `/stack-init` (or `/stack-sync`, etc.) in Claude Code
+
+## Three project states
+
+- **Empty project** — Claude Code asks 3 discovery questions, then sets up a tailored environment
+- **In development** — reads existing files, writes setup that references actual code patterns
+- **Production** — same as development; merge rules protect existing Claude config (append only, never rewrite)
+
+## What it creates
+
+- `CLAUDE.md` — project-specific context for Claude Code
+- `.mcp.json` — MCP server connections (only if evidenced by project files, OS-correct format)
+- `.claude/settings.json` — hooks (only if warranted, OS-correct shell format)
+- `.claude/skills/` — reusable patterns (only if recurring, with `applies-when` frontmatter)
+- `.claude/commands/` — project-specific slash commands
+- `.github/workflows/` — CI workflows (only if `.github/` exists)
+
+
+
+## Configuration
+
+Create `.claude-setup.json` in your project root to customize:
+
+```json
+{
+  "maxSourceFiles": 15,
+  "maxDepth": 6,
+  "maxFileSizeKB": 80,
+  "tokenBudget": {
+    "init": 12000,
+    "sync": 6000,
+    "add": 3000,
+    "remove": 2000
+  },
+  "digestMode": true,
+  "extraBlockedDirs": ["my-custom-dir"],
+  "sourceDirs": ["src", "lib"]
+}
+```
+
+## Digest mode
+
+When `digestMode` is enabled (default), the CLI extracts compact signal instead of dumping raw file content:
+
+- **Config files found** — just names, not content
+- **Dependencies** — extracted from any package manifest
+- **Scripts** — available commands/tasks
+- **Env vars** — names from `.env.example`
+- **Directory tree** — compact structure (3 levels deep)
+- **Source signatures** — imports, exports, declarations (not full content)
+
+## OS detection
+
+The CLI detects your OS and ensures command files tell Claude Code to use the correct format:
+
+- **Windows**: `{ "command": "cmd", "args": ["/c", "npx", "<package>"] }`
+- **macOS/Linux**: `{ "command": "npx", "args": ["<package>"] }`
+
+`doctor` checks for mismatches and reports them as critical issues.

package/dist/builder.js

@@ -2,6 +2,7 @@ import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { loadConfig } from "./config.js";
+import { detectOS, VERIFIED_MCP_PACKAGES } from "./os.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
 function estimateTokens(content) {
@@ -63,6 +64,9 @@ function formatSourceContext(source) {
 }
 // --- Template variable building ---
 function buildVars(collected, state) {
+    const skippedList = collected.skipped.length > 0
+        ? collected.skipped.map(s => `- ${s.path} — ${s.reason}`).join("\n")
+        : "";
     return {
         VERSION: getVersion(),
         DATE: new Date().toISOString().split("T")[0],
@@ -81,11 +85,14 @@ function buildVars(collected, state) {
         COMMANDS_LIST: formatList(state.commands),
         WORKFLOWS_LIST: formatList(state.workflows),
         HAS_GITHUB_DIR: state.hasGithubDir ? "yes" : "no",
+        SKIPPED_LIST: skippedList,
+        DETECTED_OS: detectOS(),
     };
 }
 function buildFlags(_collected, state) {
     return {
         HAS_SOURCE: _collected.source.length > 0,
+        HAS_SKIPPED: _collected.skipped.length > 0,
         HAS_CLAUDE_MD: state.claudeMd.exists,
         HAS_MCP_JSON: state.mcpJson.exists,
         HAS_SETTINGS: state.settings.exists,
@@ -162,9 +169,10 @@ export function buildAtomicSteps(collected, state) {
     const version = getVersion();
     const date = new Date().toISOString().split("T")[0];
     const vars = buildVars(collected, state);
+    const os = detectOS();
     const header = `<!-- claude-setup ${version} ${date} -->\n`;
-    const check = `Check if target already has this content. If yes: print "SKIPPED" and stop. Write only what's missing.\n\n`;
-    // Shared context block — written once to a reference file, not duplicated
+    const preamble = `Before writing: check if what you are about to write already exists in the target file (current content provided below if it exists). If already up to date: print "SKIPPED — already up to date" and stop. Write only what is genuinely missing.\n\nRead /stack-0-context for full project info.\n\n`;
+    // Shared context block — written once, referenced by all steps
     const sharedContext = header +
         `## Project\n\n${vars.PROJECT_CONTEXT}\n\n` +
         `{{#if HAS_SOURCE}}## Source samples\n\n${vars.SOURCE_CONTEXT}\n{{/if}}`;
@@ -174,57 +182,243 @@ export function buildAtomicSteps(collected, state) {
             filename: "stack-0-context.md",
             content: sharedContextProcessed,
         },
+        // --- Step 1: CLAUDE.md ---
         {
             filename: "stack-1-claude-md.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: CLAUDE.md\n` +
+            content: header + preamble +
+                `## Target: CLAUDE.md\n\n` +
                 (state.claudeMd.exists
-                    ? `Current content (append only, never rewrite):\n${vars.CLAUDE_MD_CONTENT}\n\n`
-                    : `Does not exist. Create it.\n\n`) +
-                `Write CLAUDE.md specific to this project. Reference actual paths and patterns. No generic boilerplate.`,
+                    ? `### Current content — APPEND ONLY, never rewrite, never remove:\n${vars.CLAUDE_MD_CONTENT}\n\n`
+                    : `Does not exist — create it.\n\n`) +
+                `### What to write\n` +
+                `CLAUDE.md is the most valuable artifact. Make it specific to THIS project:\n` +
+                `- **Purpose**: one sentence describing what this project does\n` +
+                `- **Runtime**: language, framework, key dependencies from /stack-0-context\n` +
+                `- **Key dirs**: reference actual directory paths from the project tree\n` +
+                `- **Run/test/build commands**: extract from scripts in /stack-0-context\n` +
+                `- **Non-obvious conventions**: patterns you see in the source samples\n\n` +
+                `### Rules\n` +
+                `- Every line must reference something you actually saw in /stack-0-context\n` +
+                `- No generic boilerplate. Two different projects must produce two different CLAUDE.md files\n` +
+                `- If it exists above: read it fully, add only what is genuinely missing\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ CLAUDE.md — [one clause: what you wrote and why]\n` +
+                `Skipped: ⏭ CLAUDE.md — [why not needed]\n`,
         },
+        // --- Step 2: .mcp.json ---
         {
             filename: "stack-2-mcp.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .mcp.json\n` +
+            content: header + preamble +
+                `## Target: .mcp.json\n\n` +
                 (state.mcpJson.exists
-                    ? `Current (merge only, never remove):\n${vars.MCP_JSON_CONTENT}\n\n`
-                    : `Does not exist. Create only if services are evidenced.\n\n`) +
-                `No evidence = no server. Valid JSON only.`,
+                    ? `### Current content — MERGE ONLY, never remove existing entries:\n${vars.MCP_JSON_CONTENT}\n\n`
+                    : `Does not exist.\n\n`) +
+                `### When to create/update\n` +
+                `Add an MCP server ONLY if you find evidence in /stack-0-context:\n` +
+                `- Import statement referencing an external service\n` +
+                `- docker-compose service (database, cache, queue)\n` +
+                `- Env var name in .env.example matching a known service pattern\n` +
+                `- Explicit dependency on an MCP-compatible package\n\n` +
+                `No evidence = no server. Do not invent services.\n\n` +
+                `### Verified MCP package names — ONLY use these\n` +
+                `\`\`\`\n` +
+                Object.entries(VERIFIED_MCP_PACKAGES).map(([k, v]) => `${k.padEnd(12)} → ${v}`).join("\n") +
+                `\n\`\`\`\n` +
+                `If the service is not in this list, print:\n` +
+                `\`⚠️ 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` +
+                (os === "Windows"
+                    ? `Use: \`{ "command": "cmd", "args": ["/c", "npx", "-y", "<package>"] }\`\n`
+                    : `Use: \`{ "command": "npx", "args": ["-y", "<package>"] }\`\n`) +
+                `Always include \`-y\` in npx args to prevent install hangs.\n` +
+                `\n### Connection strings — NEVER hardcode\n` +
+                `Wrong: \`"args": [..., "postgresql://localhost:5432/db"]\`\n` +
+                `Right: \`"env": { "DATABASE_URL": "\${DATABASE_URL}" }\`\n` +
+                `All credentials and connection strings must go in \`env\` using \`\${VARNAME}\` syntax.\n` +
+                `After adding any server with env vars, flag them:\n` +
+                `\`⚠️ Add DATABASE_URL to .env.example and populate before starting Claude Code\`\n\n` +
+                `\n### Rules\n` +
+                `- All env var refs use \`\${VARNAME}\` syntax — never literal values\n` +
+                `- Produce valid JSON only\n` +
+                `- If creating: document every new env var in .env.example\n\n` +
+                `### Channels (Telegram, Discord) — special MCP servers\n` +
+                `Channels are MCP servers that push events INTO a session. They require:\n` +
+                `- Claude Code v2.1.80+\n` +
+                `- claude.ai login (not API key / Console)\n` +
+                `- Bun runtime installed\n` +
+                `- \`--channels\` flag at EVERY session launch\n\n` +
+                `Verified channel plugins:\n` +
+                `\`\`\`\n` +
+                `Telegram → plugin:telegram@claude-plugins-official\n` +
+                `Discord  → plugin:discord@claude-plugins-official\n` +
+                `\`\`\`\n\n` +
+                `If adding a channel-type server, bot tokens must NEVER be hardcoded:\n` +
+                (os === "Windows"
+                    ? `\`{ "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` +
+                `### Output\n` +
+                `Created/Updated: ✅ .mcp.json — [what server and evidence source]\n` +
+                `Skipped: ⏭ .mcp.json — checked [files], found [nothing], no action\n`,
         },
+        // --- Step 3: .claude/settings.json ---
         {
             filename: "stack-3-settings.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .claude/settings.json\n` +
+            content: header + preamble +
+                `## Target: .claude/settings.json\n\n` +
                 (state.settings.exists
-                    ? `Current (merge only, never remove hooks):\n${vars.SETTINGS_CONTENT}\n\n`
-                    : `Does not exist. Create only if hooks earn their cost.\n\n`) +
-                `Every hook runs on every action. Only add if clearly justified.`,
+                    ? `### Current content — MERGE ONLY, never remove existing hooks:\n${vars.SETTINGS_CONTENT}\n\n`
+                    : `Does not exist.\n\n`) +
+                `### When to create/update\n` +
+                `Add a hook ONLY if it runs on a pattern that repeats every session AND the cost is justified.\n` +
+                `Every hook adds overhead on every Claude Code action. Only add if clearly earned.\n\n` +
+                `### OS-correct hook format (detected: ${os})\n` +
+                (os === "Windows"
+                    ? `Use: \`{ "command": "cmd", "args": ["/c", "<command>"] }\`\n`
+                    : `Use: \`{ "command": "bash", "args": ["-c", "<command>"] }\`\n` +
+                        `**Bash quoting rule**: never use bare \`"\` inside \`-c "..."\` — use \`\\x22\` instead.\n` +
+                        `Replace \`'\` with \`\\x27\`, \`$\` in character classes with \`\\x24\`.\n`) +
+                `\n### Valid hook event names — use ONLY these\n` +
+                `\`PreToolUse\`, \`PostToolUse\`, \`PostToolUseFailure\`, \`Stop\`, \`SessionStart\`\n` +
+                `If unsure which event name to use: do not write the hook. Print:\n` +
+                `\`SKIPPED — hook event name uncertain. Valid names: PreToolUse, PostToolUse, PostToolUseFailure, Stop, SessionStart\`\n\n` +
+                `### Rules\n` +
+                `- **NEVER write a "model" key into settings.json** — it overrides the user's model selection silently\n` +
+                `- If it exists above: audit quoting of existing hooks first, fix broken ones\n` +
+                `- Only add hooks for patterns that genuinely recur for this project type\n` +
+                `- Produce valid JSON only\n\n` +
+                `### Output\n` +
+                `Created/Updated: ✅ settings.json — [hook name and justification]\n` +
+                `Skipped: ⏭ settings.json — [why no hooks warranted]\n`,
         },
+        // --- Step 4: .claude/skills/ ---
         {
             filename: "stack-4-skills.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .claude/skills/\nInstalled: ${vars.SKILLS_LIST}\n\n` +
-                `Only for recurring patterns. Use applies-when frontmatter. Empty is fine.`,
+            content: header + preamble +
+                `## Target: .claude/skills/\n` +
+                `Installed: ${vars.SKILLS_LIST}\n\n` +
+                `### When to create\n` +
+                `Create a skill ONLY if:\n` +
+                `- A recurring multi-step project-specific pattern exists in /stack-0-context\n` +
+                `- It is NOT something Claude already knows (standard patterns don't need skills)\n` +
+                `- It will save time across multiple Claude Code sessions\n\n` +
+                `### Rules\n` +
+                `- Use \`applies-when:\` frontmatter so skills load only when relevant, not every message\n` +
+                `- If a similar skill already exists above: extend it, don't create a parallel one\n` +
+                `- Empty is valid — no skills is better than useless skills\n\n` +
+                `### Output\n` +
+                `Created: ✅ .claude/skills/[name] — [what pattern it captures]\n` +
+                `Skipped: ⏭ skills — checked [patterns], found [nothing project-specific]\n`,
         },
+        // --- Step 5: .claude/commands/ ---
         {
             filename: "stack-5-commands.md",
-            content: header + check +
-                `Read /stack-0-context for project info.\n\n` +
-                `## Target: .claude/commands/ (not stack-*.md)\nInstalled: ${vars.COMMANDS_LIST}\n\n` +
-                `Only useful commands for this project type. No duplicates.`,
+            content: header + preamble +
+                `## Target: .claude/commands/ (excluding stack-*.md — those are setup artifacts)\n` +
+                `Installed: ${vars.COMMANDS_LIST}\n\n` +
+                `### When to create\n` +
+                `Create a command ONLY for project-specific multi-step workflows a developer repeats.\n` +
+                `Do NOT create commands for things expressible as a single shell alias.\n\n` +
+                `### Smart environment detection\n` +
+                `Also scan for missing/incomplete environment setup:\n` +
+                `- \`.env.example\` exists but \`.env\` missing → suggest \`/setup-env\`\n` +
+                `- \`docker-compose.yml\` with \`depends_on\` → suggest \`/up\` with correct startup order\n` +
+                `- Database migration files (\`migrations/\`, \`prisma/schema.prisma\`, \`alembic/\`) → suggest \`/db:migrate\`, \`/db:rollback\`\n` +
+                `- \`package.json\` with \`"prepare"\` or \`"postinstall"\` hooks → suggest \`/install\`\n` +
+                `- \`Makefile\` with \`install\`, \`deps\`, \`bootstrap\` → fold into \`/init\`\n` +
+                `- README sections ("Environment Variables", "Database Setup") → each can become a command\n\n` +
+                `All suggestions must be built from actual project files — never assume fixed commands.\n` +
+                `Detect the real tooling (npm vs yarn vs pnpm, docker compose vs docker-compose) from project evidence.\n\n` +
+                `### REQUIRED: Scan for multi-step patterns before deciding\n` +
+                `You MUST actively scan these sources in /stack-0-context:\n` +
+                `- **Makefile targets**: multiple chained commands under one target\n` +
+                `- **package.json scripts**: chained commands with && or ;\n` +
+                `- **docker-compose.yml**: service dependencies implying a boot order\n` +
+                `- **Dockerfile**: multi-stage patterns implying a build sequence\n` +
+                `- **README.md / docs**: sections like "Getting Started", "How to run"\n` +
+                `- **Shell scripts** in /scripts or /bin\n` +
+                `- **.env.example**: many vars suggest a setup sequence\n\n` +
+                `### Pattern signatures to detect\n` +
+                `| Pattern found | Suggested command |\n` +
+                `|---------------|-------------------|\n` +
+                `| docker-compose down + volume removal + build + up | /clean-rebuild |\n` +
+                `| migrate + seed + start | /fresh-start |\n` +
+                `| build + test + deploy | /release |\n` +
+                `| lint + format + typecheck all separate | /check |\n` +
+                `| setup + install + configure in README or scripts | /init |\n` +
+                `| backup/restore scripts or pg_dump/mongodump | /db:backup, /db:restore |\n` +
+                `| test + test:watch + test:coverage | /test |\n` +
+                `| dev + start + debug in package.json | /dev |\n` +
+                `| >2 manual steps in README "how to run" | candidate for /start |\n\n` +
+                `For each pattern found, suggest to the user:\n` +
+                `\`\`\`\n` +
+                `## Suggested command: /[name]\n\n` +
+                `I found a multi-step pattern in [source]:\n` +
+                `  1. [step]\n` +
+                `  2. [step]\n\n` +
+                `Create .claude/commands/[name].md?\n` +
+                `\`\`\`\n\n` +
+                `### Rules\n` +
+                `- If existing commands cover the same workflow: skip\n` +
+                `- Commands should be specific to this project, not generic\n` +
+                `- Adapt exact commands from actual project files — never hardcode\n` +
+                `- Never skip with a blanket "no workflows found" without scanning all sources above\n\n` +
+                `### Output\n` +
+                `Created: ✅ .claude/commands/[name].md — [what workflow and why useful]\n` +
+                `Skipped: ⏭ commands — scanned [list each source checked and result]. Nothing warranted.\n`,
         },
+        // --- Step 6: .github/workflows/ ---
         {
             filename: "stack-6-workflows.md",
-            content: header + check +
-                `## Target: .github/workflows/\n.github/ exists: ${vars.HAS_GITHUB_DIR}\nInstalled: ${vars.WORKFLOWS_LIST}\n\n` +
+            content: header +
+                `## Target: .github/workflows/\n` +
+                `.github/ exists: ${vars.HAS_GITHUB_DIR}\n` +
+                `Installed: ${vars.WORKFLOWS_LIST}\n\n` +
                 (state.hasGithubDir
-                    ? `Only warranted workflows. Don't touch existing ones.`
-                    : `Only create if clearly warranted.`),
+                    ? (`### What to do\n` +
+                        `Check /stack-0-context for CI evidence: tests dir, Dockerfile, CI-related scripts.\n` +
+                        `If evidence found, print EXACTLY:\n\n` +
+                        `\`\`\`\n` +
+                        `⚙️  CI/CD GATE — action required\n\n` +
+                        `Evidence found:\n` +
+                        `  [list each piece of evidence]\n\n` +
+                        `Two questions before I proceed:\n` +
+                        `  1. Set up CI/CD? (yes / no / later)\n` +
+                        `  2. Connected to a remote GitHub repo? (yes / no)\n\n` +
+                        `I will not write .github/workflows/ until you answer.\n` +
+                        `\`\`\`\n\n` +
+                        `### Rules\n` +
+                        `- NEVER create or modify workflows without explicit developer confirmation\n` +
+                        `- If existing workflows exist: do not touch them\n` +
+                        `- Secrets must use \`\${{ secrets.VARNAME }}\` syntax only\n`)
+                    : (`### .github/ does not exist — scan for CI/CD evidence before skipping\n\n` +
+                        `The absence of .github/ is an opportunity to suggest, not a reason to stop.\n\n` +
+                        `Scan /stack-0-context for CI/CD evidence:\n` +
+                        `- \`tests/\` or \`__tests__/\` or \`spec/\` directory → test pipeline candidate\n` +
+                        `- \`Dockerfile\` or \`docker-compose.yml\` → build + deploy pipeline candidate\n` +
+                        `- \`package.json\` with build/test/lint scripts → Node CI candidate\n` +
+                        `- \`Makefile\` with test/build/deploy targets → generic CI candidate\n` +
+                        `- \`pyproject.toml\` with test config → Python CI candidate\n` +
+                        `- README references to "deploy", "release", "staging", "production"\n\n` +
+                        `If evidence found, print EXACTLY:\n` +
+                        `\`\`\`\n` +
+                        `⚙️  WORKFLOW SUGGESTION — .github/ does not exist\n\n` +
+                        `Evidence that CI/CD would be useful:\n` +
+                        `  [list each piece of evidence and its source]\n\n` +
+                        `I can set up:\n` +
+                        `  1. CI pipeline     — run tests + build on every push\n` +
+                        `  2. Deploy pipeline — build image + push to registry on merge to main\n` +
+                        `  3. Both\n\n` +
+                        `Two questions before I create anything:\n` +
+                        `  1. Which of the above? (1 / 2 / 3 / none)\n` +
+                        `  2. Is this connected to a remote GitHub repository? (yes / no)\n` +
+                        `\`\`\`\n\n` +
+                        `If user confirms: create .github/workflows/ with workflows based on actual project commands.\n` +
+                        `All secrets must use \`\${{ secrets.VARNAME }}\` syntax — never hardcoded.\n` +
+                        `After writing, flag every secret: \`⚠️ Add [VARNAME] to GitHub Settings → Secrets\`\n\n` +
+                        `If NO evidence found:\n` +
+                        `Skipped: ⏭ .github/workflows/ — scanned: no tests dir, no Dockerfile, no build/deploy scripts, no deployment references. Nothing to automate.\n`)),
         },
     ];
     return steps;

package/dist/collect.js

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, statSync, readdirSync } from "fs";
 import { glob } from "glob";
 import { join, extname, basename, dirname } from "path";
-import { loadConfig } from "./config.js";
+import { loadConfig, applyTruncation } from "./config.js";
 // --- Blocklists ---
 const BLOCKED_DIRS = new Set([
     "node_modules", "vendor", ".venv", "venv", "env", "__pypackages__",
@@ -22,7 +22,7 @@ const BLOCKED_EXTENSIONS = new Set([
 ]);
 const BLOCKED_FILES = new Set([
     "go.sum", "poetry.lock", "Pipfile.lock", "composer.lock",
-    ".DS_Store", "Thumbs.db", "package-lock.json",
+    ".DS_Store", "Thumbs.db",
 ]);
 const SOURCE_EXTENSIONS = new Set([
     ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
@@ -35,7 +35,8 @@ const ENTRY_DIRS = [".", "src", "app", "cmd", "bin"];
 const PRIMARY_SOURCE_DIRS = ["src", "app", "lib", "core", "pkg", "internal", "api", "cmd"];
 // Config files the CLI knows how to find — but NOT what they mean
 const KNOWN_CONFIG_FILES = [
-    "package.json", "pyproject.toml", "setup.py", "requirements.txt", "Pipfile",
+    "package.json", "package-lock.json", "pyproject.toml", "setup.py",
+    "requirements.txt", "Pipfile",
     "go.mod", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts",
     "composer.json", "Gemfile", "turbo.json", "nx.json", "pnpm-workspace.yaml",
     "lerna.json", ".env.example", ".env.sample", ".env.template",
@@ -441,18 +442,52 @@ function truncateSource(content) {
 }
 // --- Legacy raw config collection ---
 async function collectRawConfigs(cwd, configs, skipped) {
+    const config = loadConfig(cwd);
     for (const name of KNOWN_CONFIG_FILES) {
         const p = join(cwd, name);
         if (existsSync(p)) {
             try {
-                const content = readFileSync(p, "utf8");
-                configs[name] = content.length > 4000 ? content.slice(0, 4000) + "\n[... truncated]" : content;
+                const raw = readFileSync(p, "utf8");
+                // Dynamic truncation — driven by config, not hardcoded
+                configs[name] = applyTruncation(name, raw, config);
             }
             catch {
                 skipped.push({ path: name, reason: "could not read" });
             }
         }
     }
+    // Scan for *.config.{js,ts,mjs} at root level — truncation from config
+    try {
+        for (const ext of ["js", "ts", "mjs"]) {
+            const matches = await glob(`*.config.${ext}`, { cwd, nodir: true });
+            for (const match of matches) {
+                if (configs[match])
+                    continue;
+                const p = join(cwd, match);
+                try {
+                    const content = readFileSync(p, "utf8");
+                    configs[match] = applyTruncation(match, content, config);
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    catch { /* skip */ }
+    // Scan for *.csproj at root level
+    try {
+        const csprojFiles = await glob("*.csproj", { cwd, nodir: true });
+        for (const match of csprojFiles) {
+            if (configs[match])
+                continue;
+            const p = join(cwd, match);
+            try {
+                const content = readFileSync(p, "utf8");
+                configs[match] = applyTruncation(match, content, config);
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* skip */ }
 }
 // --- Source file discovery ---
 async function findSourceFiles(cwd, maxDepth, blocked) {

package/dist/commands/add.js

@@ -4,6 +4,7 @@ import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildAddCommand } from "../builder.js";
+import { c } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -18,6 +19,8 @@ async function promptFreeText(question) {
     });
 }
 // Conservative — only redirect when unambiguously single-file
+// False negatives (multi-step for single-file request) are fine
+// False positives (redirecting a genuinely multi-file request) are bad
 function isSingleFileOperation(input) {
     return (/to \.mcp\.json\s*$/i.test(input) ||
         /to settings\.json\s*$/i.test(input) ||
@@ -30,12 +33,12 @@ export async function runAdd() {
         return;
     }
     if (isSingleFileOperation(userInput)) {
-        console.log(`
-For single changes, Claude Code is faster:
-  Just tell it: "${userInput}"
-
-Use claude-setup add when the change spans multiple files —
-capabilities that need documentation, MCP servers, skills, and hooks together.
+        console.log(`
+For single changes, Claude Code is faster:
+  Just tell it: "${userInput}"
+
+Use ${c.cyan("claude-setup add")} when the change spans multiple files —
+capabilities that need documentation, MCP servers, skills, and hooks together.
     `);
         return;
     }
@@ -46,5 +49,5 @@ capabilities that need documentation, MCP servers, skills, and hooks together.
     ensureDir(".claude/commands");
     writeFileSync(".claude/commands/stack-add.md", content, "utf8");
     await updateManifest("add", collected, { input: userInput });
-    console.log(`\n✅ Ready. Open Claude Code and run:\n   /stack-add\n`);
+    console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-add")}\n`);
 }

package/dist/commands/doctor.d.ts

@@ -1 +1,5 @@
-export { runDoctor } from "../doctor.js";
+import { runDoctor } from "../doctor.js";
+export { runDoctor };
+export declare function runDoctorCommand(opts?: {
+    verbose?: boolean;
+}): Promise<void>;

package/dist/commands/doctor.js

@@ -1 +1,5 @@
-export { runDoctor } from "../doctor.js";
+import { runDoctor } from "../doctor.js";
+export { runDoctor };
+export async function runDoctorCommand(opts = {}) {
+    return runDoctor(opts.verbose ?? false);
+}

package/dist/commands/init.d.ts

@@ -1 +1,3 @@
-export declare function runInit(): Promise<void>;
+export declare function runInit(opts?: {
+    dryRun?: boolean;
+}): Promise<void>;