@shipfast-ai/shipfast 0.4.4 → 0.6.1

package/bin/install.js

@@ -56,6 +56,10 @@ function main() {
     case 'train':    return cmdInit();
     case 'update':   return cmdUpdate();
     case 'uninstall': return cmdUninstall();
+    case 'status':   return cmdStatus();
+    case 'brain':    return cmdBrain();
+    case 'learn':    return cmdLearn();
+    case 'decide':   return cmdDecide();
     case 'help':
     case 'h':        return cmdHelp();
     case 'version':
@@ -108,6 +112,9 @@ function installFor(key, runtime) {
   const coreDir = path.join(sfDir, 'core');
   for (const d of [sfDir, brainDir, coreDir]) fs.mkdirSync(d, { recursive: true });
 
+  // Write version file so /sf-status can read it
+  fs.writeFileSync(path.join(sfDir, 'version'), pkg.version);
+
   for (const f of ['schema.sql', 'index.cjs', 'indexer.cjs'])
     copy('brain/' + f, path.join(brainDir, f));
 
@@ -132,18 +139,25 @@ function installFor(key, runtime) {
   for (const f of ['sf-context-monitor.js','sf-statusline.js','sf-first-run.js'])
     copy('hooks/' + f, path.join(hooksDir, f));
 
+  // Copy MCP server
+  const mcpDir = path.join(sfDir, 'mcp');
+  fs.mkdirSync(mcpDir, { recursive: true });
+  copy('mcp/server.cjs', path.join(mcpDir, 'server.cjs'));
+
   // Runtime-specific config
   const claudeCompat = ['Claude Code', 'OpenCode', 'Kilo'];
   const geminiCompat = ['Gemini CLI', 'Antigravity'];
 
   if (claudeCompat.includes(runtime.name)) {
     writeSettings(dir, hooksDir);
+    writeMcpConfig(dir);
     writeInstruction(path.join(dir, 'CLAUDE.md'));
   } else if (geminiCompat.includes(runtime.name)) {
     writeInstruction(path.join(dir, 'AGENTS.md'));
   } else if (runtime.name === 'Copilot') {
     writeInstruction(path.join(dir, 'copilot-instructions.md'));
   } else if (runtime.name === 'Cursor') {
+    writeMcpConfig(dir);
     writeInstruction(path.join(dir, 'rules'));
   } else {
     writeInstruction(path.join(dir, 'AGENTS.md'));
@@ -168,6 +182,8 @@ function printDone(count) {
 
 function cmdInit() {
   const cwd = process.cwd();
+  const fresh = process.argv.includes('--fresh');
+
   if (!fs.existsSync(path.join(cwd, '.git'))) {
     console.log(`${red}Not a git repo.${reset} Run this inside a git repository.\n`);
     return;
@@ -180,10 +196,19 @@ function cmdInit() {
   }
 
   const brainExists = fs.existsSync(path.join(cwd, '.shipfast', 'brain.db'));
-  console.log(brainExists ? 'Re-indexing codebase...' : 'Indexing codebase...');
+
+  // FIX #8: --fresh flag
+  if (fresh && brainExists) {
+    fs.unlinkSync(path.join(cwd, '.shipfast', 'brain.db'));
+    console.log('Cleared existing brain.db');
+  }
+
+  console.log(brainExists && !fresh ? 'Re-indexing codebase...' : 'Indexing codebase...');
 
   try {
-    const out = safeRun(process.execPath, [indexer, cwd], {
+    const args = [indexer, cwd];
+    if (fresh) args.push('--fresh');
+    const out = safeRun(process.execPath, args, {
       encoding: 'utf8', timeout: 120000, stdio: ['pipe', 'pipe', 'pipe']
     });
     console.log(`${green}${out.trim()}${reset}`);
@@ -258,8 +283,13 @@ function cmdUninstall() {
           if (f.startsWith('sf-')) fs.unlinkSync(path.join(hd, f));
         }
       }
-      // Clean settings.json
+      // Clean settings.json hooks (#18: remove empty arrays too)
       cleanSettings(dir);
+      // FIX #7: Clean instruction files (CLAUDE.md, AGENTS.md, etc.)
+      cleanInstructionFile(path.join(dir, 'CLAUDE.md'));
+      cleanInstructionFile(path.join(dir, 'AGENTS.md'));
+      cleanInstructionFile(path.join(dir, 'copilot-instructions.md'));
+      cleanInstructionFile(path.join(dir, 'rules'));
       console.log(`  ${green}${runtime.name}${reset} — removed`);
       removed++;
     }
@@ -309,6 +339,8 @@ function cleanSettings(dir) {
 function cmdHelp() {
   console.log(`${bold}Terminal commands:${reset}\n`);
   console.log(`  ${cyan}shipfast init${reset}           Index current repo into .shipfast/brain.db`);
+  console.log(`  ${cyan}shipfast init --fresh${reset}   Full reindex (clears existing brain.db)`);
+  console.log(`  ${cyan}shipfast status${reset}         Show installed runtimes + brain status`);
   console.log(`  ${cyan}shipfast update${reset}         Update to latest + re-detect runtimes`);
   console.log(`  ${cyan}shipfast uninstall${reset}      Remove from all AI tools`);
   console.log(`  ${cyan}shipfast help${reset}           Show this help\n`);
@@ -322,7 +354,7 @@ function cmdHelp() {
   console.log(`  ${cyan}/sf-undo${reset}              Rollback a task`);
   console.log(`  ${cyan}/sf-brain${reset} <query>     Query the knowledge graph`);
   console.log(`  ${cyan}/sf-learn${reset} <pattern>   Teach a pattern or lesson`);
-  console.log(`  ${cyan}/sf-config${reset}            Set token budget and model tiers`);
+  console.log(`  ${cyan}/sf-config${reset}            Set model tiers and preferences`);
   console.log(`  ${cyan}/sf-milestone${reset}         Complete or start a milestone`);
   console.log(`  ${cyan}/sf-help${reset}              Show all commands\n`);
 }
@@ -352,6 +384,23 @@ function writeSettings(dir, hooksDir) {
   fs.writeFileSync(sp, JSON.stringify(s, null, 2));
 }
 
+function writeMcpConfig(dir) {
+  const serverPath = path.join(dir, 'shipfast', 'mcp', 'server.cjs');
+  const settingsPath = path.join(dir, 'settings.json');
+  let s = {};
+  if (fs.existsSync(settingsPath)) { try { s = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {} }
+
+  if (!s.mcpServers) s.mcpServers = {};
+
+  s.mcpServers['shipfast-brain'] = {
+    command: 'node',
+    args: [serverPath],
+    env: {}
+  };
+
+  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2));
+}
+
 function writeInstruction(filePath) {
   const marker = '<!-- ShipFast -->';
   const close = '<!-- /ShipFast -->';
@@ -368,6 +417,61 @@ function writeInstruction(filePath) {
   fs.writeFileSync(filePath, content);
 }
 
+// FIX #7: Remove ShipFast block from instruction files during uninstall
+function cleanInstructionFile(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  try {
+    let content = fs.readFileSync(filePath, 'utf8');
+    const marker = '<!-- ShipFast -->';
+    const close = '<!-- /ShipFast -->';
+    const s = content.indexOf(marker);
+    const e = content.indexOf(close);
+    if (s !== -1 && e !== -1) {
+      content = content.slice(0, s) + content.slice(e + close.length);
+      content = content.trim() + '\n';
+      fs.writeFileSync(filePath, content);
+    }
+  } catch {}
+}
+
+// FIX #17: CLI status command — show installed runtimes + version + brain status
+function cmdStatus() {
+  console.log(`${bold}Installed runtimes:${reset}\n`);
+  let count = 0;
+  for (const [key, runtime] of Object.entries(RUNTIMES)) {
+    const dir = path.join(os.homedir(), runtime.path);
+    if (fs.existsSync(path.join(dir, 'shipfast'))) {
+      console.log(`  ${green}${runtime.name}${reset} ${dim}${dir}${reset}`);
+      count++;
+    }
+  }
+  if (count === 0) {
+    console.log(`  ${dim}(none)${reset}`);
+  }
+
+  // Brain status for current directory
+  const cwd = process.cwd();
+  const brainPath = path.join(cwd, '.shipfast', 'brain.db');
+  console.log(`\n${bold}Current repo:${reset} ${cwd}\n`);
+  if (fs.existsSync(brainPath)) {
+    try {
+      const out = safeRun('sqlite3', [brainPath,
+        "SELECT 'nodes', COUNT(*) FROM nodes UNION ALL SELECT 'edges', COUNT(*) FROM edges UNION ALL SELECT 'decisions', COUNT(*) FROM decisions UNION ALL SELECT 'learnings', COUNT(*) FROM learnings;"
+      ], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+      console.log(`  Brain: ${green}indexed${reset}`);
+      out.trim().split('\n').forEach(line => {
+        const [k, v] = line.split('|');
+        console.log(`  ${dim}${k}: ${v}${reset}`);
+      });
+    } catch {
+      console.log(`  Brain: ${green}exists${reset} (.shipfast/brain.db)`);
+    }
+  } else {
+    console.log(`  Brain: ${yellow}not indexed${reset} — run ${cyan}shipfast init${reset}`);
+  }
+  console.log('');
+}
+
 function copy(rel, dest) {
   const src = path.join(__dirname, '..', rel);
   if (fs.existsSync(src)) fs.copyFileSync(src, dest);

package/brain/indexer.cjs

@@ -461,21 +461,67 @@ function indexCodebase(cwd, opts = {}) {
     execFileSync('sqlite3', [dbPath], { input: sql, stdio: ['pipe', 'pipe', 'pipe'] });
   }
 
-  // Update hot files (separate transaction)
+  // FIX #1: Clean orphan nodes (deleted/renamed/moved files)
+  let cleaned = 0;
+  if (!changedOnly) {
+    const discoveredPaths = new Set(files.map(f => path.relative(cwd, f).replace(/\\/g, '/')));
+    const existingFiles = brain.query(cwd, "SELECT file_path FROM nodes WHERE kind = 'file'");
+    const orphans = existingFiles.filter(row => !discoveredPaths.has(row.file_path));
+
+    if (orphans.length > 0) {
+      const cleanSql = ['BEGIN TRANSACTION;'];
+      for (const orphan of orphans) {
+        const escaped = orphan.file_path.replace(/'/g, "''");
+        // Delete file node + all symbols from that file + all edges from/to that file
+        cleanSql.push(`DELETE FROM nodes WHERE file_path = '${escaped}';`);
+        cleanSql.push(`DELETE FROM edges WHERE source LIKE 'file:${escaped}%' OR target LIKE 'file:${escaped}%' OR source LIKE 'fn:${escaped}%' OR source LIKE 'type:${escaped}%' OR source LIKE 'class:${escaped}%' OR source LIKE 'component:${escaped}%';`);
+      }
+      cleanSql.push('COMMIT;');
+      const dbPath = brain.getBrainPath(cwd);
+      execFileSync('sqlite3', [dbPath], { input: cleanSql.join('\n'), stdio: ['pipe', 'pipe', 'pipe'] });
+      cleaned = orphans.length;
+    }
+  }
+
+  // FIX #6: Update hot files on every index
   brain.updateHotFiles(cwd);
 
+  // FIX #11: Run co-change analysis
+  try {
+    const gitIntelPath = path.join(__dirname, '..', 'core', 'git-intel.cjs');
+    if (fs.existsSync(gitIntelPath)) {
+      const gitIntel = require(gitIntelPath);
+      gitIntel.analyzeCoChanges(cwd, 200);
+    }
+  } catch { /* git-intel optional */ }
+
   const elapsed = Date.now() - startTime;
-  return { files: files.length, indexed, skipped, nodes: totalNodes, edges: totalEdges, statements: batch.count, elapsed_ms: elapsed };
+  return { files: files.length, indexed, skipped, cleaned, nodes: totalNodes, edges: totalEdges, statements: batch.count, elapsed_ms: elapsed };
 }
 
 // CLI mode
 if (require.main === module) {
   const args = process.argv.slice(2);
   const changedOnly = args.includes('--changed-only');
+  const fresh = args.includes('--fresh');
   const cwd = args.find(a => !a.startsWith('-')) || process.cwd();
-  console.log(`Indexing ${cwd}${changedOnly ? ' (changed only)' : ''}...`);
+
+  // FIX #8: --fresh flag deletes brain.db first
+  if (fresh) {
+    const dbPath = path.join(cwd, '.shipfast', 'brain.db');
+    if (fs.existsSync(dbPath)) {
+      fs.unlinkSync(dbPath);
+      console.log('Cleared existing brain.db');
+    }
+  }
+
+  console.log(`Indexing ${cwd}...`);
   const result = indexCodebase(cwd, { verbose: true, changedOnly });
-  console.log(`Done in ${result.elapsed_ms}ms: ${result.indexed} files (${result.skipped} unchanged), ${result.nodes} symbols, ${result.edges} edges, ${result.statements} SQL statements`);
+  const parts = [`Done in ${result.elapsed_ms}ms: ${result.indexed} files indexed`];
+  if (result.skipped) parts.push(`${result.skipped} unchanged`);
+  if (result.cleaned) parts.push(`${result.cleaned} deleted files cleaned`);
+  parts.push(`${result.nodes} symbols, ${result.edges} edges`);
+  console.log(parts.join(', '));
 }
 
 module.exports = { indexCodebase, discoverFiles, discoverChangedFiles };

package/commands/sf/do.md

@@ -51,19 +51,13 @@ Classify the user's input using these heuristics:
 
 ---
 
-## STEP 2: INIT BRAIN (0 tokens)
+## STEP 2: CONTEXT GATHERING (0 tokens)
 
-If `.shipfast/brain.db` does not exist:
-```bash
-node [shipfast-path]/brain/indexer.cjs [cwd]
-```
+**FIX #5: Git diff awareness** — Run `git diff --name-only HEAD` to see what files changed since last commit. Pass this list to Scout so it focuses on recent changes instead of searching blindly.
 
-If brain.db exists, run incremental index on changed files only:
-```bash
-node [shipfast-path]/brain/indexer.cjs [cwd] --changed-only
-```
+If `.shipfast/brain.db` does not exist, tell user to run `shipfast init` first.
 
-This takes ~300ms and ensures the knowledge graph is current.
+**Store the changed files list** — use it in Step 4 (Scout) and Step 6 (Builder) for targeted context.
 
 ---
 
@@ -208,14 +202,21 @@ If brain.db has requirements for this phase:
 
 ---
 
-## STEP 8: LEARN (0 tokens)
+## STEP 8: LEARN
+
+**FIX #9/#10: Explicitly record decisions and learnings using these exact commands:**
+
+If you made any architectural decisions during this task, record each one:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO decisions (question, decision, reasoning, phase) VALUES ('[what was decided]', '[the choice]', '[why]', '[current task]');"
+```
+
+If you encountered and fixed any errors, record the pattern:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO learnings (pattern, problem, solution, domain, source, confidence) VALUES ('[short pattern name]', '[what went wrong]', '[what fixed it]', '[domain]', 'auto', 0.5);"
+```
 
-Automatically update brain.db:
-- **Decisions**: Extract "chose X", "decided on Y" patterns from the session
-- **Learnings**: Record any error→fix patterns for future sessions
-- **Conventions**: If Builder matched a pattern not yet in brain.db, store it
-- **Boost**: Increase confidence of learnings that helped this session
-- **Prune**: Remove old low-confidence learnings that haven't been used
+**These are not optional.** If decisions were made or errors were fixed, you MUST record them. This is how ShipFast gets smarter over time.
 
 ---
 

package/commands/sf/status.md

@@ -5,20 +5,24 @@ allowed-tools:
   - Bash
 ---
 
-Run this EXACT command. Do NOT modify it. Do NOT run any other commands. Do NOT add insights or commentary.
+Run these EXACT commands. Do NOT modify them. Do NOT add insights or commentary.
 
 ```bash
 sqlite3 .shipfast/brain.db "SELECT 'nodes' as k, COUNT(*) as v FROM nodes UNION ALL SELECT 'edges', COUNT(*) FROM edges UNION ALL SELECT 'decisions', COUNT(*) FROM decisions UNION ALL SELECT 'learnings', COUNT(*) FROM learnings UNION ALL SELECT 'tasks', COUNT(*) FROM tasks UNION ALL SELECT 'checkpoints', COUNT(*) FROM checkpoints UNION ALL SELECT 'hot_files', COUNT(*) FROM hot_files UNION ALL SELECT 'active', (SELECT COUNT(*) FROM tasks WHERE status IN ('running','pending')) UNION ALL SELECT 'passed', (SELECT COUNT(*) FROM tasks WHERE status='passed');" 2>/dev/null || echo "No brain.db found. Run: shipfast init"
 ```
 
-Then output EXACTLY this format using the numbers from above. Nothing else:
+```bash
+cat ~/.claude/shipfast/version 2>/dev/null || cat ~/.cursor/shipfast/version 2>/dev/null || cat ~/.gemini/shipfast/version 2>/dev/null || echo "unknown"
+```
+
+Then output EXACTLY this format. Nothing else:
 
 ```
-ShipFast Status
+ShipFast v[version]
 ===============
 Brain: [nodes] nodes | [edges] edges | [decisions] decisions | [learnings] learnings | [hot_files] hot files
 Tasks: [active] active | [passed] completed
 Checkpoints: [checkpoints] available
 ```
 
-STOP after printing this. No analysis. No suggestions. No insights. Just the status block.
+STOP after printing this. No analysis. No suggestions. No insights.

package/hooks/sf-first-run.js

@@ -2,68 +2,60 @@
 /**
  * ShipFast First-Run Hook — PreToolUse
  *
- * Detects when brain.db doesn't exist in the current repo.
- * Injects a message telling the agent to run the indexer first.
- * Only fires once per repo — after indexing, brain.db exists and this becomes a no-op.
+ * FIX #3: Exits immediately for non-Skill tools (near-zero overhead).
+ * Only injects brain indexing instruction when:
+ * - Tool is Skill (sf-* command)
+ * - brain.db doesn't exist for this repo
+ * - This is a git repo
+ *
+ * After user runs `shipfast init`, brain.db exists and this becomes a no-op.
  */
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 let input = '';
-const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+const stdinTimeout = setTimeout(() => process.exit(0), 5000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {
     const data = JSON.parse(input);
-    const cwd = data.cwd || process.cwd();
 
-    // Only trigger for sf-* skill invocations
-    const toolName = data.tool_name || '';
-    if (toolName !== 'Skill') {
-      process.exit(0);
-    }
+    // FIX #3: Fast exit for non-Skill tools (99% of calls)
+    if ((data.tool_name || '') !== 'Skill') process.exit(0);
 
-    // Check if brain.db exists
-    const brainPath = path.join(cwd, '.shipfast', 'brain.db');
-    if (fs.existsSync(brainPath)) {
-      process.exit(0); // already trained, no-op
-    }
+    const cwd = data.cwd || process.cwd();
 
-    // Check if this is a git repo
-    if (!fs.existsSync(path.join(cwd, '.git'))) {
-      process.exit(0); // not a repo, skip
-    }
+    // Already indexed — no-op
+    if (fs.existsSync(path.join(cwd, '.shipfast', 'brain.db'))) process.exit(0);
 
-    // Find the indexer
-    const possiblePaths = [
-      path.join(cwd, '.claude', 'shipfast', 'brain', 'indexer.cjs'),
-      path.join(cwd, '.cursor', 'shipfast', 'brain', 'indexer.cjs'),
-      path.join(cwd, '.gemini', 'shipfast', 'brain', 'indexer.cjs'),
-      path.join(require('os').homedir(), '.claude', 'shipfast', 'brain', 'indexer.cjs'),
-    ];
+    // Not a git repo — skip
+    if (!fs.existsSync(path.join(cwd, '.git'))) process.exit(0);
 
-    const indexerPath = possiblePaths.find(p => fs.existsSync(p));
-    if (!indexerPath) {
-      process.exit(0); // can't find indexer
-    }
+    // Find indexer in global install locations
+    const home = os.homedir();
+    const indexer = [
+      path.join(home, '.claude', 'shipfast', 'brain', 'indexer.cjs'),
+      path.join(home, '.cursor', 'shipfast', 'brain', 'indexer.cjs'),
+      path.join(home, '.gemini', 'shipfast', 'brain', 'indexer.cjs'),
+      path.join(home, '.codex', 'shipfast', 'brain', 'indexer.cjs'),
+      path.join(home, '.config', 'opencode', 'shipfast', 'brain', 'indexer.cjs'),
+    ].find(p => fs.existsSync(p));
 
-    // Inject training instruction
-    const output = {
+    if (!indexer) process.exit(0);
+
+    process.stdout.write(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'PreToolUse',
-        additionalContext: 'SHIPFAST FIRST RUN: brain.db not found for this repo. ' +
-          'Before proceeding with the task, run the indexer to train the brain:\n' +
-          '```bash\nnode "' + indexerPath + '" "' + cwd + '"\n```\n' +
-          'This indexes the codebase (~1 second) and creates .shipfast/brain.db. ' +
-          'Also add ".shipfast/" to .gitignore if not already there. ' +
-          'After indexing, proceed with the user\'s command normally.'
+        additionalContext: 'SHIPFAST: brain.db not found for this repo. ' +
+          'Run this first to index the codebase:\n' +
+          '```bash\nnode "' + indexer + '" "' + cwd + '"\n```\n' +
+          'Then proceed with the command.'
       }
-    };
-
-    process.stdout.write(JSON.stringify(output));
+    }));
   } catch {
     process.exit(0);
   }

package/mcp/server.cjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+/**
+ * ShipFast MCP Server — stdio transport
+ *
+ * Exposes brain.db as structured MCP tools.
+ * Works with: Claude Code, Cursor, Windsurf, Codex, OpenCode, Gemini, etc.
+ *
+ * Tools:
+ *   brain_stats       — node/edge/decision/learning counts
+ *   brain_search      — search files/functions by name
+ *   brain_files       — list indexed files
+ *   brain_decisions   — list or add decisions
+ *   brain_learnings   — list or add learnings
+ *   brain_hot_files   — show most changed files
+ *   brain_status      — full status summary
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync: safeRun } = require('child_process');
+
+const CWD = process.env.SHIPFAST_CWD || process.cwd();
+const DB_PATH = path.join(CWD, '.shipfast', 'brain.db');
+
+// ============================================================
+// SQLite query helper
+// ============================================================
+
+function query(sql) {
+  if (!fs.existsSync(DB_PATH)) return [];
+  try {
+    const result = safeRun('sqlite3', ['-json', DB_PATH, sql], {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return result.trim() ? JSON.parse(result) : [];
+  } catch { return []; }
+}
+
+function run(sql) {
+  if (!fs.existsSync(DB_PATH)) return false;
+  try {
+    safeRun('sqlite3', [DB_PATH, sql], { stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch { return false; }
+}
+
+function esc(s) {
+  return s == null ? '' : String(s).replace(/'/g, "''");
+}
+
+// ============================================================
+// Tool implementations
+// ============================================================
+
+const TOOLS = {
+  brain_stats: {
+    description: 'Get brain.db statistics: node count, edge count, decisions, learnings, hot files, tasks.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    handler() {
+      if (!fs.existsSync(DB_PATH)) return { error: 'brain.db not found. Run: shipfast init' };
+      const rows = query(
+        "SELECT 'nodes' as metric, COUNT(*) as count FROM nodes " +
+        "UNION ALL SELECT 'edges', COUNT(*) FROM edges " +
+        "UNION ALL SELECT 'decisions', COUNT(*) FROM decisions " +
+        "UNION ALL SELECT 'learnings', COUNT(*) FROM learnings " +
+        "UNION ALL SELECT 'tasks', COUNT(*) FROM tasks " +
+        "UNION ALL SELECT 'checkpoints', COUNT(*) FROM checkpoints " +
+        "UNION ALL SELECT 'hot_files', COUNT(*) FROM hot_files"
+      );
+      const stats = {};
+      rows.forEach(r => stats[r.metric] = r.count);
+      return stats;
+    }
+  },
+
+  brain_search: {
+    description: 'Search the codebase knowledge graph for files, functions, types, or components by name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search term (file name, function name, type name)' },
+        kind: { type: 'string', description: 'Filter by kind: file, function, type, class, component. Optional.', enum: ['file', 'function', 'type', 'class', 'component', ''] }
+      },
+      required: ['query']
+    },
+    handler({ query: q, kind }) {
+      const kindFilter = kind ? `AND kind = '${esc(kind)}'` : '';
+      return query(
+        `SELECT kind, name, file_path, signature, line_start FROM nodes ` +
+        `WHERE (name LIKE '%${esc(q)}%' OR file_path LIKE '%${esc(q)}%') ${kindFilter} ` +
+        `ORDER BY kind, name LIMIT 30`
+      );
+    }
+  },
+
+  brain_files: {
+    description: 'List indexed files in brain.db. Optionally filter by path pattern.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Filter file paths containing this string. Optional.' }
+      },
+      required: []
+    },
+    handler({ pattern }) {
+      const where = pattern ? `AND file_path LIKE '%${esc(pattern)}%'` : '';
+      return query(
+        `SELECT file_path, hash FROM nodes WHERE kind = 'file' ${where} ORDER BY file_path LIMIT 50`
+      );
+    }
+  },
+
+  brain_decisions: {
+    description: 'List all decisions, or add a new decision. Decisions persist across sessions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', description: 'list or add', enum: ['list', 'add'] },
+        question: { type: 'string', description: 'What was decided? (required for add)' },
+        decision: { type: 'string', description: 'The choice made. (required for add)' },
+        reasoning: { type: 'string', description: 'Why this choice? (optional)' },
+        phase: { type: 'string', description: 'Which phase/task. (optional)' }
+      },
+      required: ['action']
+    },
+    handler({ action, question, decision, reasoning, phase }) {
+      if (action === 'add') {
+        if (!question || !decision) return { error: 'question and decision are required' };
+        const ok = run(
+          `INSERT INTO decisions (question, decision, reasoning, phase) ` +
+          `VALUES ('${esc(question)}', '${esc(decision)}', '${esc(reasoning || '')}', '${esc(phase || '')}')`
+        );
+        return ok ? { status: 'recorded', question, decision } : { error: 'failed to insert' };
+      }
+      return query("SELECT id, question, decision, reasoning, phase, created_at FROM decisions ORDER BY created_at DESC LIMIT 20");
+    }
+  },
+
+  brain_learnings: {
+    description: 'List all learnings, or add a new learning. Learnings help ShipFast avoid past mistakes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', description: 'list or add', enum: ['list', 'add'] },
+        pattern: { type: 'string', description: 'Short identifier e.g. "react-19-refs". (required for add)' },
+        problem: { type: 'string', description: 'What went wrong. (required for add)' },
+        solution: { type: 'string', description: 'What fixed it. (optional)' },
+        domain: { type: 'string', description: 'Area: frontend, backend, database, auth, etc. (optional)' }
+      },
+      required: ['action']
+    },
+    handler({ action, pattern, problem, solution, domain }) {
+      if (action === 'add') {
+        if (!pattern || !problem) return { error: 'pattern and problem are required' };
+        const ok = run(
+          `INSERT INTO learnings (pattern, problem, solution, domain, source, confidence) ` +
+          `VALUES ('${esc(pattern)}', '${esc(problem)}', '${esc(solution || '')}', '${esc(domain || '')}', 'user', 0.8)`
+        );
+        return ok ? { status: 'recorded', pattern, problem, solution } : { error: 'failed to insert' };
+      }
+      return query("SELECT id, pattern, problem, solution, domain, confidence, times_used FROM learnings ORDER BY confidence DESC LIMIT 20");
+    }
+  },
+
+  brain_hot_files: {
+    description: 'Show most frequently changed files based on git history.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'How many files to show. Default: 15.' }
+      },
+      required: []
+    },
+    handler({ limit }) {
+      return query(`SELECT file_path, change_count FROM hot_files ORDER BY change_count DESC LIMIT ${parseInt(limit) || 15}`);
+    }
+  },
+
+  brain_status: {
+    description: 'Full ShipFast status: brain stats, active tasks, recent tasks, checkpoints.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    handler() {
+      if (!fs.existsSync(DB_PATH)) return { error: 'brain.db not found. Run: shipfast init' };
+
+      const stats = TOOLS.brain_stats.handler();
+      const active = query("SELECT id, description, status FROM tasks WHERE status IN ('running','pending') ORDER BY created_at DESC LIMIT 5");
+      const recent = query("SELECT id, description, status, commit_sha FROM tasks WHERE status = 'passed' ORDER BY finished_at DESC LIMIT 5");
+      const checkpoints = query("SELECT id, description FROM checkpoints ORDER BY created_at DESC LIMIT 5");
+
+      return { stats, activeTasks: active, recentTasks: recent, checkpoints };
+    }
+  }
+};
+
+// ============================================================
+// MCP Protocol (JSON-RPC over stdio)
+// ============================================================
+
+let buffer = '';
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buffer += chunk;
+
+  // MCP uses Content-Length header framing
+  while (true) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) break;
+
+    const header = buffer.slice(0, headerEnd);
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (!match) { buffer = buffer.slice(headerEnd + 4); continue; }
+
+    const contentLength = parseInt(match[1]);
+    const bodyStart = headerEnd + 4;
+    if (buffer.length < bodyStart + contentLength) break;
+
+    const body = buffer.slice(bodyStart, bodyStart + contentLength);
+    buffer = buffer.slice(bodyStart + contentLength);
+
+    try {
+      const msg = JSON.parse(body);
+      handleMessage(msg);
+    } catch {}
+  }
+});
+
+function send(msg) {
+  const body = JSON.stringify(msg);
+  const header = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`;
+  process.stdout.write(header + body);
+}
+
+function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  if (method === 'initialize') {
+    return send({
+      jsonrpc: '2.0', id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'shipfast-brain', version: '0.5.0' }
+      }
+    });
+  }
+
+  if (method === 'notifications/initialized') return;
+
+  if (method === 'tools/list') {
+    const tools = Object.entries(TOOLS).map(([name, t]) => ({
+      name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }));
+    return send({ jsonrpc: '2.0', id, result: { tools } });
+  }
+
+  if (method === 'tools/call') {
+    const toolName = params.name;
+    const tool = TOOLS[toolName];
+    if (!tool) {
+      return send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: 'Unknown tool: ' + toolName }], isError: true } });
+    }
+
+    try {
+      const result = tool.handler(params.arguments || {});
+      return send({
+        jsonrpc: '2.0', id,
+        result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
+      });
+    } catch (err) {
+      return send({
+        jsonrpc: '2.0', id,
+        result: { content: [{ type: 'text', text: 'Error: ' + err.message }], isError: true }
+      });
+    }
+  }
+
+  // Unknown method
+  send({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found: ' + method } });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipfast-ai/shipfast",
-  "version": "0.4.4",
+  "version": "0.6.1",
   "description": "Autonomous context-engineered development system. 5 agents, 12 commands, SQLite brain. 70-90% less tokens than alternatives.",
   "bin": {
     "shipfast": "bin/install.js"
@@ -12,6 +12,7 @@
     "core",
     "agents",
     "hooks",
+    "mcp",
     "scripts"
   ],
   "keywords": [

package/scripts/postinstall.js

@@ -2,8 +2,18 @@
 
 /**
  * Postinstall — auto-detect AI tools and install for all of them.
- * Runs automatically after `npm i -g @shipfast-ai/shipfast`
+ * Only runs when installed globally (npm i -g). Skips for local project deps.
  */
 
-// Just run the main CLI with no args — it auto-detects and installs
-require('../bin/install.js');
+// FIX #4: Only run auto-install when installed globally
+const isGlobal = process.env.npm_config_global === 'true' ||
+  (process.env.npm_lifecycle_event === 'postinstall' && !process.env.INIT_CWD);
+
+if (isGlobal) {
+  require('../bin/install.js');
+} else {
+  // Local install — just show a message
+  const cyan = '\x1b[36m';
+  const reset = '\x1b[0m';
+  console.log(`\nShipFast installed locally. For global install: ${cyan}npm i -g @shipfast-ai/shipfast${reset}\n`);
+}