claude-setup 1.1.6 → 1.1.8

package/README.md

@@ -1,161 +1,142 @@
 # claude-setup
 
-Setup layer for Claude Code. Reads your project, writes command files, Claude Code does the rest.
+Your project already has the answers — `claude-setup` reads them and configures Claude Code so you don't have to.
 
-**The CLI has zero intelligence.** All reasoning is delegated to Claude Code via the command files.
+One command. No manual config. Works on **Windows, macOS, Linux, and WSL**.
 
-## Install
+## Get started
 
 ```bash
-npx claude-setup init
+npx claude-setup
 ```
 
-Then open Claude Code and run `/stack-init`.
+Pick `1` (init). Then open Claude Code and run:
 
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `init` | Full project setup — detects empty projects, generates atomic setup steps |
-| `add` | Add capabilities — MCP servers, skills, hooks, plugins in one go |
-| `sync` | Update setup after project changes — diff-based, not full re-scan |
-| `status` | Dashboard — project info, setup files, snapshots, token usage |
-| `doctor` | Validate everything — OS format, hooks, env vars, stale skills |
-| `remove` | Remove capabilities cleanly with dangling reference detection |
-| `restore` | Jump to any snapshot — restore files to a previous state |
-| `compare` | Diff two snapshots — find exactly where something changed |
-| `export` | Save your setup as a reusable template |
-
-### Flags
-
-```bash
-npx claude-setup init --dry-run            # Preview without writing
-npx claude-setup init --template my.json   # Apply a saved template
-npx claude-setup sync --dry-run            # Show changes without writing
-npx claude-setup sync --budget 3000        # Override token budget
-npx claude-setup doctor --verbose          # Include passing checks
-npx claude-setup doctor --fix              # Auto-fix issues
-npx claude-setup doctor --test-hooks       # Run every hook in sandbox
+```
+/stack-init
 ```
 
-## How it works
+That's it. Claude Code now knows your stack, your services, your conventions.
 
-1. **CLI collects** — reads project files with strict token cost controls
-2. **CLI writes** — generates markdown instructions into `.claude/commands/`
-3. **Claude Code executes** — you run `/stack-init`, `/stack-sync`, etc.
+## What happens during init
 
-## What it creates
+`claude-setup` scans your project files — `package.json`, `docker-compose.yml`, `.env.example`, source code — and generates everything Claude Code needs:
 
-| File | Purpose |
-|------|---------|
-| `CLAUDE.md` | Project-specific context for Claude Code |
-| `.mcp.json` | MCP server connections (only if evidenced by project files) |
-| `.claude/settings.json` | Hooks in correct Claude Code format |
-| `.claude/skills/` | Reusable patterns with frontmatter |
-| `.claude/commands/` | Project-specific slash commands |
-| `.github/workflows/` | CI workflows (only with confirmation) |
+| Generated | What it does |
+|-----------|-------------|
+| **CLAUDE.md** | Project context — stack, structure, commands, conventions |
+| **.mcp.json** | MCP server connections — auto-detected from your dependencies |
+| **settings.json** | Hooks — auto-format, token tracking, build triggers |
+| **skills/** | Reusable patterns for your workflow |
+| **commands/** | Slash commands that work inside Claude Code |
 
-## Snapshots
+Every line comes from evidence in your project files. No guessing.
 
-Every `init` and `sync` creates a snapshot node — a checkpoint on a timeline. Snapshots store the content of changed files only.
+### MCP servers are auto-configured
 
-```
-init ──→ sync#1 ──→ sync#2 ──→ sync#3 (current)
-              │                    │
-              │                    └─ bug introduced here
-              └─ jump back here
-```
+`claude-setup` detects your databases and services automatically:
 
-- `npx claude-setup restore` — pick any snapshot and restore files to that state
-- `npx claude-setup compare` — diff any two snapshots to find what changed
-- Jumping does **not** delete other snapshots — all are preserved
+- Finds PostgreSQL, MongoDB, Redis, MySQL from your deps, docker-compose, or env files
+- Checks if the service is installed locally (`psql`, `mongosh`, `redis-cli`)
+- Uses the right connection URL — no broken `${VARNAME}` that fails silently
+- Formats commands for your OS (`cmd /c npx` on Windows, `npx` everywhere else)
 
-## Templates
+## After init
 
-Save your setup and reuse it across projects.
+These slash commands work inside Claude Code:
 
-```bash
-# Export current setup
-npx claude-setup export
-# → creates my-template.claude-template.json
+| Command | What it does |
+|---------|-------------|
+| `/stack-sync` | Detect file changes, update your setup |
+| `/stack-add` | Add a capability — searches 400+ marketplace plugins first |
+| `/stack-status` | Show project state, snapshots, token usage |
+| `/stack-doctor` | Validate environment, auto-fix issues |
+| `/stack-restore` | Time-travel to any snapshot |
+| `/stack-remove` | Remove a capability cleanly |
 
-# Apply to a new project
-npx claude-setup init --template my-template.claude-template.json
+### `/stack-add` searches the marketplace for you
 
-# Apply from a URL
-npx claude-setup init --template https://example.com/template.json
-```
+Say what you want — it searches 400+ community plugins and 13 official Anthropic plugins, downloads and installs matching skills automatically. No manual steps.
 
-Templates capture CLAUDE.md, MCP servers, hooks, skills, and commands. On import:
-- Existing content is kept, new content is merged
-- MCP commands are auto-adapted for the target OS
-- Skills and commands with the same name are skipped
+```
+/stack-add
+> "E2E testing and Stripe integration"
+```
 
-## Token Cost Tracking
+### `/stack-sync` shows what changed
 
-Every command shows estimated token usage and cost across all Claude models.
+Every sync creates a snapshot and shows a color-coded diff:
 
 ```
-Token cost
-  ~2,450 input tokens (Opus $0.0368 | Sonnet $0.0074 | Haiku $0.0006)
+Changes since 2026-03-28T14:32:01.904Z:
+  +2 added  ~3 modified  -1 deleted
+
+  Added files:
+    + src/api/payments.ts (48 lines)
+    + src/api/webhooks.ts (32 lines)
+
+  Modified files:
+    ~ package.json (+3 lines, -1 lines)
+    ~ src/index.ts (+8 lines, -2 lines)
 ```
 
-Status shows cumulative stats, per-command averages, and cost trends. Use `--budget` on sync to override the token limit for a single run.
+Claude Code sees the actual line-level changes and updates your setup surgically.
 
-## Doctor
+## Snapshots
 
-Validates your entire setup and reports issues by severity.
+Every init and sync saves a full snapshot. You can jump to any point in time:
 
-```bash
-npx claude-setup doctor           # Check everything
-npx claude-setup doctor --fix     # Auto-fix what's possible
-npx claude-setup doctor --test-hooks  # Run each hook, report pass/fail
+```
+/stack-restore
 ```
 
-What `--fix` can repair:
-- Remove accidental model overrides from settings.json
-- Convert MCP commands to the correct OS format
-- Add missing `-y` flags to npx calls
-- Re-snapshot files modified outside the CLI
-
-What `--test-hooks` checks per hook:
-- Command exists on the system
-- Command executes without error
-- Exit code and stderr
-- Execution time and timeout detection
-- Matcher regex validity
+```
+init ──> sync#1 ──> sync#2 ──> sync#3 (you are here)
+              |
+              └── jump back here anytime
+```
 
-## Marketplace
+Snapshots are never deleted. Go back, go forward, freely.
 
-The `add` command integrates with [claude-code-plugins-plus-skills](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) — 340+ plugins and 1,367+ skills across 20 categories.
+## All CLI commands
 
 ```bash
-npx claude-setup add
-# → "Stripe and frontend skills"
-# → generates stack-add.md with marketplace search + install instructions
+npx claude-setup                         # Interactive menu
+npx claude-setup init                    # Full project setup
+npx claude-setup sync                    # Checkpoint + update
+npx claude-setup add "postgres and testing"  # Add capabilities
+npx claude-setup status                  # Dashboard
+npx claude-setup doctor                  # Validate everything
+npx claude-setup doctor --fix            # Auto-fix issues
+npx claude-setup restore                 # Time-travel
+npx claude-setup compare                 # Diff two snapshots
+npx claude-setup remove "redis"          # Remove cleanly
+npx claude-setup export                  # Save as template
+npx claude-setup init --template file    # Apply a template
 ```
 
 ## Configuration
 
-Auto-generated on first run. Edit `.claude-setup.json` to customize:
+Auto-generated on first run. Edit `.claude-setup.json` if needed:
 
 ```json
 {
   "maxSourceFiles": 15,
   "maxDepth": 6,
-  "maxFileSizeKB": 80,
-  "tokenBudget": {
-    "init": 12000,
-    "sync": 6000,
-    "add": 3000,
-    "remove": 2000
-  },
-  "digestMode": true,
-  "extraBlockedDirs": [],
-  "sourceDirs": []
+  "tokenBudget": { "init": 12000, "sync": 6000, "add": 3000 },
+  "digestMode": true
 }
 ```
 
+## Supported platforms
+
+| Platform | Status | MCP format |
+|----------|--------|-----------|
+| Windows | Full support | `cmd /c npx -y <pkg>` |
+| macOS | Full support + Homebrew detection | `npx -y <pkg>` |
+| Linux | Full support | `npx -y <pkg>` |
+| WSL | Full support + Windows host access | `npx -y <pkg>` |
+
 ## License
 
 MIT

package/dist/builder.d.ts

@@ -11,6 +11,12 @@ export interface FileDiff {
     changed: Array<{
         path: string;
         current: string;
+        previous?: string;
+        lineDiff?: {
+            added: string[];
+            removed: string[];
+            summary: string;
+        };
     }>;
     deleted: string[];
 }

package/dist/builder.js

@@ -2,7 +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";
+import { detectOS, isUnixLike, VERIFIED_MCP_PACKAGES, buildServiceDiscoveryInstructions } from "./os.js";
 import { buildMarketplaceInstructions } from "./marketplace.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
@@ -91,6 +91,7 @@ function buildVars(collected, state) {
     };
 }
 function buildFlags(_collected, state) {
+    const os = detectOS();
     return {
         HAS_SOURCE: _collected.source.length > 0,
         HAS_SKIPPED: _collected.skipped.length > 0,
@@ -98,7 +99,10 @@ function buildFlags(_collected, state) {
         HAS_MCP_JSON: state.mcpJson.exists,
         HAS_SETTINGS: state.settings.exists,
         HAS_GITHUB_DIR: state.hasGithubDir,
-        IS_WINDOWS: detectOS() === "Windows",
+        IS_WINDOWS: os === "Windows", // WSL uses Unix-style commands, not cmd
+        IS_WSL: os === "WSL",
+        IS_MACOS: os === "macOS",
+        IS_UNIX_LIKE: isUnixLike(os),
     };
 }
 // --- Token budget enforcement ---
@@ -153,15 +157,43 @@ export function buildAddCommand(input, collected, state) {
     }, "add");
 }
 export function buildSyncCommand(diff, collected, state) {
-    // Compact diff format — paths + one-line summary, not full content
+    // Rich diff format — paths + line-level changes for modified files
     const addedStr = diff.added.length > 0
         ? diff.added.map(f => `- **${f.path}** (new) — ${f.content.split("\n").length} lines`).join("\n")
         : "(none)";
-    const modifiedStr = diff.changed.length > 0
-        ? diff.changed.map(f => `- **${f.path}** (modified)`).join("\n")
-        : "(none)";
+    // Modified files now include line-level diffs
+    let modifiedStr;
+    if (diff.changed.length > 0) {
+        const parts = [];
+        for (const f of diff.changed) {
+            const lines = [`- **${f.path}** (modified)`];
+            if (f.lineDiff) {
+                lines[0] += ` — ${f.lineDiff.summary}`;
+                if (f.lineDiff.removed.length > 0 || f.lineDiff.added.length > 0) {
+                    lines.push("  ```diff");
+                    for (const l of f.lineDiff.removed.slice(0, 8)) {
+                        lines.push(`  - ${l.trimEnd().slice(0, 120)}`);
+                    }
+                    for (const l of f.lineDiff.added.slice(0, 8)) {
+                        lines.push(`  + ${l.trimEnd().slice(0, 120)}`);
+                    }
+                    const totalShown = Math.min(f.lineDiff.removed.length, 8) + Math.min(f.lineDiff.added.length, 8);
+                    const total = f.lineDiff.removed.length + f.lineDiff.added.length;
+                    if (total > totalShown) {
+                        lines.push(`  # ... +${total - totalShown} more changes`);
+                    }
+                    lines.push("  ```");
+                }
+            }
+            parts.push(lines.join("\n"));
+        }
+        modifiedStr = parts.join("\n");
+    }
+    else {
+        modifiedStr = "(none)";
+    }
     const deletedStr = diff.deleted.length > 0
-        ? diff.deleted.map(f => `- ${f}`).join("\n")
+        ? diff.deleted.map(f => `- ~~${f}~~ (deleted)`).join("\n")
         : "(none)";
     const lastRun = state.manifest?.runs.at(-1);
     return applyTemplate("sync.md", collected, state, {
@@ -180,8 +212,12 @@ export function buildBootstrapSync() {
     return `<!-- stack-sync: self-refreshing sync command. Last generated: ${new Date().toISOString().split("T")[0]} -->
 
 > **Step 1 — always do this first:** Run \`npx claude-setup sync\` to refresh this file with the latest diff.
-> - If it outputs "No changes since…" → respond "Stack already in sync." and STOP.
-> - Otherwise → re-read \`.claude/commands/stack-sync.md\` (Step 2), then process the diff below (Step 3).
+> - If the output says **"No changes"** and shows "Setup is current" → respond "No changes detected since last sync. Everything is up to date." and STOP.
+> - If the output shows **changes** (any "+N added", "~N modified", or "-N deleted" with N > 0) → it means the file has been regenerated. Continue to Step 2.
+> **Step 2:** Re-read \`.claude/commands/stack-sync.md\` — it now contains the actual diff with line-level changes.
+> **Step 3:** Process every change listed. Update CLAUDE.md, .mcp.json, settings.json as needed. Surgical edits only.
+
+**IMPORTANT:** The sync command creates a snapshot AND regenerates this file. The "Run /stack-sync" message in the output is for YOU — it means this file is now ready to be re-read. Do NOT tell the user to run /stack-sync again.
 
 ## Changes since last setup
 
@@ -196,8 +232,7 @@ export function buildBootstrapSync() {
 
 ## Your job
 
-For EACH changed file: does this change have any implication for the Claude Code setup?
-Update ONLY what the change demands. Do NOT rewrite files — surgical edits only.
+For EACH changed file, update the Claude Code setup. New source files (routes, services, etc.) MUST be reflected in CLAUDE.md. Config changes may require .mcp.json or settings.json updates. Surgical edits only.
 `;
 }
 export function buildRemoveCommand(input, state) {
@@ -247,73 +282,94 @@ export function buildAtomicSteps(collected, state) {
         // --- Step 2: .mcp.json ---
         {
             filename: "stack-2-mcp.md",
-            content: header + preamble +
-                `## Target: .mcp.json\n\n` +
-                (state.mcpJson.exists
-                    ? `### 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 if you find ANY of these signals in /stack-0-context:\n` +
-                `- Import statement referencing an external service (e.g., pg, mysql2, mongoose, redis, stripe)\n` +
-                `- docker-compose service (database, cache, queue, message broker)\n` +
-                `- Env var name in .env.example matching a known service pattern (DATABASE_URL, REDIS_URL, STRIPE_KEY, etc.)\n` +
-                `- Explicit dependency on an MCP-compatible package\n` +
-                `- User mentioned external services during init questions\n\n` +
-                `If ANY evidence is found, create .mcp.json with the corresponding servers.\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` +
-                `**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`) +
-                `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` +
-                `### 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`,
+            content: (() => {
+                const serviceDiscovery = buildServiceDiscoveryInstructions(process.cwd());
+                return header + preamble +
+                    `## Target: .mcp.json\n\n` +
+                    (state.mcpJson.exists
+                        ? `### 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 if you find ANY of these signals in /stack-0-context:\n` +
+                    `- Import statement referencing an external service (e.g., pg, mysql2, mongoose, redis, stripe)\n` +
+                    `- docker-compose service (database, cache, queue, message broker)\n` +
+                    `- Env var name in .env.example matching a known service pattern (DATABASE_URL, REDIS_URL, STRIPE_KEY, etc.)\n` +
+                    `- Explicit dependency on an MCP-compatible package\n` +
+                    `- User mentioned external services during init questions\n\n` +
+                    `If ANY evidence is found, create .mcp.json with the corresponding servers.\n` +
+                    `No evidence = no server. Do not invent services.\n\n` +
+                    (serviceDiscovery ? serviceDiscovery + `\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}${os === "WSL" ? " — uses Unix-style commands, services reachable on localhost" : ""})\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`) +
+                    `Always include \`-y\` in npx args to prevent install hangs.\n` +
+                    (os === "WSL" ? `Note: WSL uses Unix-style npx — do NOT use \`cmd /c\` wrapper.\n` : ``) +
+                    (os === "macOS" ? `Note: On macOS, Homebrew services run on localhost by default. Check with \`brew services list\`.\n` : ``) +
+                    `\n` +
+                    `### Connection strings — smart auto-configuration\n` +
+                    `For each MCP server that needs a connection string:\n` +
+                    `1. **Check environment first:** If \`\${VARNAME}\` is set in the user's environment, use \`"env": { "VAR": "\${VAR}" }\`\n` +
+                    `2. **Detect local service:** Run the OS-appropriate check command to see if the service is installed locally\n` +
+                    (os === "Windows"
+                        ? `   - PostgreSQL: \`where psql 2>nul\`\n   - MongoDB: \`where mongosh 2>nul\`\n   - Redis: \`where redis-cli 2>nul\`\n   - MySQL: \`where mysql 2>nul\`\n`
+                        : os === "macOS"
+                            ? `   - PostgreSQL: \`command -v psql || brew list postgresql 2>/dev/null\`\n   - MongoDB: \`command -v mongosh || brew list mongodb-community 2>/dev/null\`\n   - Redis: \`command -v redis-cli || brew list redis 2>/dev/null\`\n   - MySQL: \`command -v mysql || brew list mysql 2>/dev/null\`\n`
+                            : `   - PostgreSQL: \`command -v psql\`\n   - MongoDB: \`command -v mongosh\`\n   - Redis: \`command -v redis-cli\`\n   - MySQL: \`command -v mysql\`\n`) +
+                    `3. **If local service found and env var NOT set:** Use the well-known default URL directly in the env block:\n` +
+                    `   - PostgreSQL: \`postgresql://localhost:5432/postgres\`\n` +
+                    `   - MongoDB: \`mongodb://localhost:27017\`\n` +
+                    `   - Redis: \`redis://localhost:6379\`\n` +
+                    `   - MySQL: \`mysql://root@localhost:3306\`\n` +
+                    `   AND document the var in .env.example with the default value\n` +
+                    `4. **If neither env var nor local service found:** Use \`\${VARNAME}\` syntax and flag:\n` +
+                    `   \`⚠️ Set VARNAME in your environment or .env file before starting Claude Code\`\n\n` +
+                    `**NEVER hardcode credentials.** Default localhost URLs are acceptable for dev environments.\n` +
+                    `After adding any server with env vars, always document them in .env.example.\n\n` +
+                    `### Rules\n` +
+                    `- Produce valid JSON only\n` +
+                    `- If creating: document every new env var in .env.example\n` +
+                    `- OS format must match detected OS: ${os}\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`) +
+                    (os === "WSL" ? `(WSL note: Bun must be installed inside WSL, not the Windows-side installation.)\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`;
+            })(),
         },
         // --- Step 3: .claude/settings.json ---
         {

package/dist/commands/add.d.ts

@@ -1 +1,3 @@
-export declare function runAdd(): Promise<void>;
+export declare function runAdd(opts?: {
+    input?: string;
+}): Promise<void>;

package/dist/commands/add.js

@@ -4,8 +4,8 @@ import { collectProjectFiles } from "../collect.js";
 import { readState } from "../state.js";
 import { updateManifest } from "../manifest.js";
 import { buildAddCommand } from "../builder.js";
-import { estimateTokens, estimateCost, formatCost } from "../tokens.js";
-import { c, section } from "../output.js";
+import { estimateTokens, estimateCost } from "../tokens.js";
+import { c } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -19,16 +19,13 @@ 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) ||
         /to claude\.md\s*$/i.test(input));
 }
-export async function runAdd() {
-    const userInput = await promptFreeText("What do you want to add to your Claude Code setup?");
+export async function runAdd(opts = {}) {
+    const userInput = opts.input ?? await promptFreeText("What do you want to add to your Claude Code setup?");
     if (!userInput) {
         console.log("No input provided.");
         return;
@@ -44,10 +41,8 @@ capabilities that need documentation, MCP servers, skills, and hooks together.
         return;
     }
     const state = await readState();
-    // add only needs config files — source files are irrelevant and waste tokens
     const collected = await collectProjectFiles(process.cwd(), "configOnly");
     const content = buildAddCommand(userInput, collected, state);
-    // Token tracking
     const tokens = estimateTokens(content);
     const cost = estimateCost(tokens);
     ensureDir(".claude/commands");
@@ -57,8 +52,5 @@ capabilities that need documentation, MCP servers, skills, and hooks together.
         estimatedTokens: tokens,
         estimatedCost: cost,
     });
-    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(`${formatCost(cost)}`)})`);
-    console.log("");
+    console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-add")}\n`);
 }