claude-setup 1.1.2 → 1.1.4

package/README.md

@@ -2,9 +2,9 @@
 
 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.
+**The CLI has zero intelligence.** All reasoning is delegated to Claude Code via the command files.
 
-## Install & Quick Start
+## Install
 
 ```bash
 npx claude-setup init
@@ -16,70 +16,128 @@ Then open Claude Code and run `/stack-init`.
 
 | 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 |
+| `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 sync --dry-run    # Show changes without writing
-npx claude-setup doctor --verbose  # Include passing checks in output
+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
 ```
 
 ## 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
+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.
 
-## Three project states
+## What it creates
 
-- **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)
+| 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) |
 
-## What it creates
+## Snapshots
+
+Every `init` and `sync` creates a snapshot node — a checkpoint on a timeline. Snapshots store the content of changed files only.
+
+```
+init ──→ sync#1 ──→ sync#2 ──→ sync#3 (current)
+              │                    │
+              │                    └─ bug introduced here
+              └─ jump back here
+```
+
+- `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
+
+## Templates
 
-- `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)
-
-## Token cost controls
-
-Every byte injected into command files costs tokens. The CLI enforces:
-
-| Control | Default |
-|---------|---------|
-| Init token budget | 12,000 |
-| Sync token budget | 6,000 |
-| Add token budget | 3,000 |
-| Remove token budget | 2,000 |
-| Max source files sampled | 15 |
-| Max file size | 80KB |
-| Max depth | 6 levels |
-
-### File-specific truncation
-
-| File | Strategy |
-|------|----------|
-| `package-lock.json` | Extract `{ name, version, lockfileVersion }` only |
-| `Dockerfile` | First 50 lines |
-| `docker-compose.yml` | First 100 lines if > 8KB |
-| `pom.xml`, `build.gradle*` | First 80 lines |
-| `setup.py` | First 60 lines |
-| `*.config.{js,ts,mjs}` | First 100 lines |
+Save your setup and reuse it across projects.
+
+```bash
+# Export current setup
+npx claude-setup export
+# → creates my-template.claude-template.json
+
+# Apply to a new project
+npx claude-setup init --template my-template.claude-template.json
+
+# Apply from a URL
+npx claude-setup init --template https://example.com/template.json
+```
+
+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
+
+## Token Cost Tracking
+
+Every command shows estimated token usage and cost across all Claude models.
+
+```
+Token cost
+  ~2,450 input tokens (Opus $0.0368 | Sonnet $0.0074 | Haiku $0.0006)
+```
+
+Status shows cumulative stats, per-command averages, and cost trends. Use `--budget` on sync to override the token limit for a single run.
+
+## Doctor
+
+Validates your entire setup and reports issues by severity.
+
+```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
+```
+
+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
+
+## Marketplace
+
+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.
+
+```bash
+npx claude-setup add
+# → "Stripe and frontend skills"
+# → generates stack-add.md with marketplace search + install instructions
+```
 
 ## Configuration
 
-Create `.claude-setup.json` in your project root to customize:
+Auto-generated on first run. Edit `.claude-setup.json` to customize:
 
 ```json
 {
@@ -93,27 +151,11 @@ Create `.claude-setup.json` in your project root to customize:
     "remove": 2000
   },
   "digestMode": true,
-  "extraBlockedDirs": ["my-custom-dir"],
-  "sourceDirs": ["src", "lib"]
+  "extraBlockedDirs": [],
+  "sourceDirs": []
 }
 ```
 
-## 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>"] }`
+## License
 
-`doctor` checks for mismatches and reports them as critical issues.
+MIT

package/dist/builder.js

@@ -2,7 +2,8 @@ import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { loadConfig } from "./config.js";
-import { detectOS } from "./os.js";
+import { detectOS, VERIFIED_MCP_PACKAGES } from "./os.js";
+import { buildMarketplaceInstructions } from "./marketplace.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
 function estimateTokens(content) {
@@ -97,6 +98,7 @@ function buildFlags(_collected, state) {
         HAS_MCP_JSON: state.mcpJson.exists,
         HAS_SETTINGS: state.settings.exists,
         HAS_GITHUB_DIR: state.hasGithubDir,
+        IS_WINDOWS: detectOS() === "Windows",
     };
 }
 // --- Token budget enforcement ---
@@ -137,10 +139,18 @@ export function buildInitCommand(collected, state) {
 }
 export function buildEmptyProjectCommand() {
     const template = loadTemplate("init-empty.md");
-    return replaceVars(template, { VERSION: getVersion(), DATE: new Date().toISOString().split("T")[0] });
+    const vars = { VERSION: getVersion(), DATE: new Date().toISOString().split("T")[0], DETECTED_OS: detectOS() };
+    const flags = { IS_WINDOWS: detectOS() === "Windows" };
+    let content = replaceVars(template, vars);
+    content = processConditionals(content, flags);
+    return content;
 }
 export function buildAddCommand(input, collected, state) {
-    return applyTemplate("add.md", collected, state, { USER_INPUT: input }, "add");
+    const marketplaceSection = buildMarketplaceInstructions(input);
+    return applyTemplate("add.md", collected, state, {
+        USER_INPUT: input,
+        MARKETPLACE_INSTRUCTIONS: marketplaceSection,
+    }, "add");
 }
 export function buildSyncCommand(diff, collected, state) {
     // Compact diff format — paths + one-line summary, not full content
@@ -214,20 +224,52 @@ export function buildAtomicSteps(collected, state) {
                     ? `### 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` +
+                `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` +
                 (os === "Windows"
-                    ? `Use: \`{ "command": "cmd", "args": ["/c", "npx", "<package>"] }\`\n`
-                    : `Use: \`{ "command": "npx", "args": ["<package>"] }\`\n`) +
+                    ? `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\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`,
@@ -243,16 +285,53 @@ export function buildAtomicSteps(collected, state) {
                 `### 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` +
+                `### CORRECT Claude Code hooks format — USE THIS EXACTLY\n` +
+                `The hooks object must be nested inside a top-level \`"hooks"\` key.\n` +
+                `Each event contains an array of matcher objects, each with its own \`"hooks"\` array.\n\n` +
+                `\`\`\`json\n` +
+                `{\n` +
+                `  "hooks": {\n` +
+                `    "PostToolUse": [\n` +
+                `      {\n` +
+                `        "matcher": "Edit|Write",\n` +
+                `        "hooks": [\n` +
+                `          {\n` +
+                `            "type": "command",\n` +
+                `            "command": "<shell command here>"\n` +
+                `          }\n` +
+                `        ]\n` +
+                `      }\n` +
+                `    ]\n` +
+                `  }\n` +
+                `}\n` +
+                `\`\`\`\n\n` +
+                `**WRONG formats (do NOT use):**\n` +
+                `- \`"hooks": { "post-edit": ["mvn compile"] }\` — INVALID event name and structure\n` +
+                `- \`"PostToolUse": [{ "command": "bash", "args": [...] }]\` — missing top-level "hooks" key\n` +
+                `- \`{ "command": "cmd", "args": ["/c", "..."] }\` — old format, must use "type": "command"\n\n` +
+                `### Valid hook event names — use ONLY these\n` +
+                `\`PreToolUse\`, \`PostToolUse\`, \`PostToolUseFailure\`, \`Stop\`, \`SessionStart\`,\n` +
+                `\`Notification\`, \`UserPromptSubmit\`, \`PermissionRequest\`, \`ConfigChange\`,\n` +
+                `\`SubagentStart\`, \`SubagentStop\`, \`SessionEnd\`\n\n` +
+                `### Matcher patterns\n` +
+                `- \`"Edit|Write"\` — fires only on file edits\n` +
+                `- \`"Bash"\` — fires only on shell commands\n` +
+                `- \`""\` (empty) — fires on all occurrences of the event\n\n` +
+                `### BUG 8 FIX: Verify build tools exist BEFORE adding hooks\n` +
+                `Before adding any hook that runs a build tool, verify it is installed:\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### Rules\n` +
+                    ? `\`\`\`\nwhere mvn 2>nul && mvn compile -q\nwhere gradle 2>nul && gradle build\nwhere npm 2>nul && npm run build\n\`\`\`\n`
+                    : `\`\`\`\ncommand -v mvn && mvn compile -q\ncommand -v gradle && gradle build\ncommand -v npm && npm run build\n\`\`\`\n`) +
+                `If the tool is NOT installed:\n` +
+                `- Wrap the command with an existence check: \`command -v mvn && mvn compile -q\`\n` +
+                `- OR skip the hook and print: \`⚠️ SKIPPED mvn hook — Maven not found. Install Maven first.\`\n` +
+                `- NEVER add a hook for a tool that doesn't exist on the system\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` +
+                `- Produce valid JSON only\n` +
+                `- The \`"type"\` field in each hook must be one of: \`"command"\`, \`"prompt"\`, \`"agent"\`, \`"http"\`\n\n` +
                 `### Output\n` +
                 `Created/Updated: ✅ settings.json — [hook name and justification]\n` +
                 `Skipped: ⏭ settings.json — [why no hooks warranted]\n`,
@@ -264,16 +343,37 @@ export function buildAtomicSteps(collected, state) {
                 `## Target: .claude/skills/\n` +
                 `Installed: ${vars.SKILLS_LIST}\n\n` +
                 `### When to create\n` +
-                `Create a skill ONLY if:\n` +
+                `Create a skill 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` +
+                `- The project type has standard workflows worth automating (build, deploy, test patterns)\n` +
                 `- It will save time across multiple Claude Code sessions\n\n` +
+                `### Correct skill file format\n` +
+                `Skills must be created as \`.claude/skills/<skill-name>/SKILL.md\` with YAML frontmatter:\n\n` +
+                `\`\`\`yaml\n` +
+                `---\n` +
+                `name: skill-name\n` +
+                `description: What this skill does and when to use it\n` +
+                `---\n\n` +
+                `Skill instructions here...\n` +
+                `\`\`\`\n\n` +
+                `Optional frontmatter fields:\n` +
+                `- \`disable-model-invocation: true\` — only user can invoke (for commands with side effects)\n` +
+                `- \`allowed-tools: Read, Grep\` — restrict which tools the skill can use\n` +
+                `- \`context: fork\` — run in isolated subagent\n` +
+                `- \`agent: Explore\` — which agent type to use with context: fork\n\n` +
+                `### Project-specific skills to consider\n` +
+                `Based on what you see in /stack-0-context, consider creating skills for:\n` +
+                `- Build/deploy workflows specific to this stack\n` +
+                `- Code review patterns specific to this codebase\n` +
+                `- Database migration patterns if migration files exist\n` +
+                `- Testing patterns if test infrastructure exists\n\n` +
                 `### Rules\n` +
-                `- Use \`applies-when:\` frontmatter so skills load only when relevant, not every message\n` +
+                `- Use \`description:\` frontmatter so Claude knows when to load the skill\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` +
+                `- Empty is valid — no skills is better than useless skills\n` +
+                `- Each skill directory MUST contain a SKILL.md file\n\n` +
                 `### Output\n` +
-                `Created: ✅ .claude/skills/[name] — [what pattern it captures]\n` +
+                `Created: ✅ .claude/skills/[name]/SKILL.md — [what pattern it captures]\n` +
                 `Skipped: ⏭ skills — checked [patterns], found [nothing project-specific]\n`,
         },
         // --- Step 5: .claude/commands/ ---
@@ -283,19 +383,55 @@ export function buildAtomicSteps(collected, state) {
                 `## 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` +
-                `- Deploy sequences\n` +
-                `- Database migration + seed\n` +
-                `- Release workflows\n` +
-                `- Environment setup for a new contributor\n\n` +
-                `Do NOT create commands for things expressible as a single shell alias.\n` +
-                `Look at the scripts in /stack-0-context for evidence of multi-step workflows.\n\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\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 — [why no project-specific workflows found]\n`,
+                `Skipped: ⏭ commands — scanned [list each source checked and result]. Nothing warranted.\n`,
         },
         // --- Step 6: .github/workflows/ ---
         {
@@ -321,9 +457,33 @@ export function buildAtomicSteps(collected, state) {
                         `- 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\n` +
-                        `Do not create workflows. Print:\n` +
-                        `Skipped: ⏭ .github/workflows/ — .github/ directory does not exist\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;
@@ -336,12 +496,12 @@ export function buildOrchestratorCommand(steps) {
     const stepList = runSteps
         .map((s, i) => `${i + 1}. /${s.filename.replace(".md", "")}`)
         .join("\n");
-    return `<!-- claude-setup ${version} ${date} -->
-
-Run these in order. If one fails, fix and continue from that step.
-
-${stepList}
-
-After all complete: one-line summary of what was created.
+    return `<!-- claude-setup ${version} ${date} -->
+
+Run these in order. If one fails, fix and continue from that step.
+
+${stepList}
+
+After all complete: one-line summary of what was created.
 `;
 }

package/dist/commands/add.js

@@ -4,7 +4,8 @@ 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";
+import { estimateTokens, estimateCost } from "../tokens.js";
+import { c, section } from "../output.js";
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -46,8 +47,18 @@ capabilities that need documentation, MCP servers, skills, and hooks together.
     // 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");
     writeFileSync(".claude/commands/stack-add.md", content, "utf8");
-    await updateManifest("add", collected, { input: userInput });
-    console.log(`\n${c.green("✅")} Ready. Open Claude Code and run:\n   ${c.cyan("/stack-add")}\n`);
+    await updateManifest("add", collected, {
+        input: userInput,
+        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(`Opus $${cost.opus.toFixed(4)} | Sonnet $${cost.sonnet.toFixed(4)} | Haiku $${cost.haiku.toFixed(4)}`)})`);
+    console.log("");
 }

package/dist/commands/compare.d.ts

@@ -0,0 +1 @@
+export declare function runCompare(): Promise<void>;