@shipfast-ai/shipfast 1.0.0 → 1.0.2

package/README.md

@@ -4,7 +4,7 @@
 
 **Autonomous context-engineered development system with SQLite brain.**
 
-**5 agents. 14 commands. Per-task fresh context. 70-90% fewer tokens.**
+**5 agents. 17 commands. Per-task fresh context. 70-90% fewer tokens.**
 
 Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline
 
@@ -65,7 +65,9 @@ Updates the package and re-detects runtimes (catches newly installed AI tools).
 ```bash
 shipfast init           # Index current repo into .shipfast/brain.db
 shipfast init --fresh   # Full reindex (clears existing brain)
-shipfast status         # Show installed runtimes + brain stats
+shipfast link <path>    # Link another repo for cross-repo search
+shipfast unlink [path]  # Unlink a repo (or all)
+shipfast status         # Show installed runtimes + brain + links
 shipfast update         # Update + re-detect runtimes
 shipfast uninstall      # Remove from all AI tools
 shipfast help           # Show all commands
@@ -208,10 +210,35 @@ All state lives in `.shipfast/brain.db`. Zero markdown files.
 | `requirements` | REQ-IDs mapped to phases for tracing |
 | `checkpoints` | Git stash refs for rollback |
 | `hot_files` | Most frequently changed files from git history |
+| `architecture` | Auto-computed layers from import graph (zero hardcoding) |
+| `folders` | Directory roles auto-detected from import patterns |
 
 **Incremental indexing**: only re-indexes changed files (~300ms). Deleted files auto-cleaned.
 
-**MCP Server**: brain.db is exposed as structured MCP tools — `brain_stats`, `brain_search`, `brain_decisions`, `brain_learnings`, etc. LLMs call these instead of improvising SQL.
+**MCP Server**: brain.db is exposed as 17 structured MCP tools. LLMs call these instead of improvising SQL.
+
+---
+
+## Architecture Intelligence
+
+ShipFast auto-derives architecture layers from the import graph — **zero hardcoded folder patterns**. Works with any project structure, any language.
+
+**How it works**:
+1. BFS from entry points (files nothing imports) assigns layer depth
+2. Fuzzy import resolution handles `@/`, `~/`, and alias paths
+3. Folder roles detected from aggregate import/export ratios
+4. Recomputed on every `shipfast init` (instant)
+
+**What it produces**:
+
+- **Layer 0** (entry): files nothing imports — pages, routes, App.tsx
+- **Layer 1-N** (deeper): each layer imported by the layer above
+- **Leaf layer**: files that import nothing — types, constants
+- **Folder roles**: entry (imports many), shared (imported by many), consumer, leaf, foundation
+
+**Why it matters**: Scout knows which layer a file lives in. Builder knows to check upstream consumers before modifying a shared layer. Critic can detect skip-layer violations. Verifier traces data flow from entry to data source.
+
+All exposed as MCP tools: `brain_arch_layers`, `brain_arch_folders`, `brain_arch_file`, `brain_arch_data_flow`, `brain_arch_most_connected`.
 
 ---
 
@@ -247,6 +274,7 @@ If other files use it → update them or keep it. **NEVER remove without checkin
 |---|---|
 | `/sf-do <task>` | Execute a task. Auto-detects complexity: trivial → medium → complex |
 | `/sf-plan <task>` | Research (Scout) + Plan (Architect). Stores tasks in brain.db |
+| `/sf-check-plan` | Verify plan before execution: scope, consumers, deps, STRIDE threats |
 | `/sf-verify` | Verify completed work: artifacts, data flow, stubs, build, consumers |
 | `/sf-discuss <task>` | Detect ambiguity, ask targeted questions, lock decisions |
 
@@ -254,8 +282,9 @@ If other files use it → update them or keep it. **NEVER remove without checkin
 
 | Command | What it does |
 |---|---|
-| `/sf-project <desc>` | Decompose large project into phases with REQ-ID tracing |
+| `/sf-project <desc>` | Decompose large project into phases with REQ-ID tracing + 4 parallel researchers |
 | `/sf-milestone [complete\|new]` | Complete current milestone or start next version |
+| `/sf-workstream <action>` | Parallel feature branches: create, list, switch, complete |
 
 ### Shipping
 
@@ -277,6 +306,7 @@ If other files use it → update them or keep it. **NEVER remove without checkin
 |---|---|
 | `/sf-brain <query>` | Query knowledge graph: files, decisions, learnings, hot files |
 | `/sf-learn <pattern>` | Teach a reusable pattern (persists across sessions) |
+| `/sf-map` | Generate codebase report: architecture layers, hot files, co-change clusters |
 
 ### Config
 
@@ -291,8 +321,8 @@ If other files use it → update them or keep it. **NEVER remove without checkin
 
 ```
 Simple:     /sf-do fix the typo in header
-Standard:   /sf-plan add dark mode → /sf-do → /sf-verify
-Complex:    /sf-project Build billing → /sf-discuss → /sf-plan → /sf-do → /sf-verify → /sf-ship
+Standard:   /sf-plan add dark mode → /sf-check-plan → /sf-do → /sf-verify
+Complex:    /sf-project Build billing → /sf-discuss → /sf-plan → /sf-check-plan → /sf-do → /sf-verify → /sf-ship
 ```
 
 ---

package/agents/architect.md

@@ -17,7 +17,7 @@ Plan BACKWARD from the goal:
 
 1. **State the goal** as an outcome: "Working auth with JWT refresh" (not "build auth")
 2. **Derive observable truths** (3-7): What must be TRUE when done?
-   - "Valid credentials return 200 + JWT cookie"
+   - "Specific testable outcome from this feature"
    - "Invalid credentials return 401"
    - "Expired token auto-refreshes"
 3. **Derive required artifacts**: What files must EXIST for each truth?
@@ -38,9 +38,9 @@ Must-haves:
 
 Every task MUST have:
 
-**Files**: EXACT paths. `src/services/api/venueApi.ts` — NOT "the venue service file"
+**Files**: EXACT paths from Scout findings — never vague like "the service file"
 **Action**: Specific instructions. Testable: could a different AI implement without asking?
-**Verify**: Concrete command: `npx tsc --noEmit`, `npm test -- auth`, `grep -r "functionName" src/`
+**Verify**: Concrete command that proves the task works (build check, grep, test run)
 **Done**: Measurable criteria: "Returns 200 with JWT" — NOT "auth works"
 
 ## Sizing
@@ -149,7 +149,7 @@ Key links: [what must be CONNECTED]
   - [specific instruction with function names]
   - [specific instruction]
   - Update consumers: `file1.ts` line 15 (change import)
-- **Verify**: `npx tsc --noEmit` and `grep -r "functionName" src/`
+- **Verify**: [concrete command from project's build/test tooling]
 - **Done**: [measurable criterion]
 - **Size**: small | medium | large
 - **Depends**: none | Task N

package/agents/builder.md

@@ -16,7 +16,7 @@ You are BUILDER. You implement tasks precisely and safely. You NEVER remove, ren
 
 Before deleting, removing, renaming, or modifying ANY function, type, selector, export, or component:
 
-1. `grep -r "functionName" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" .`
+1. `grep -r "<name-being-changed>" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" .`
 2. Count results. If OTHER files use it → update those files too, or keep the original
 3. NEVER remove without checking. This is the #1 cause of cascading breaks.
 

package/agents/scout.md

@@ -1,101 +1,111 @@
 ---
 name: sf-scout
-description: Reconnaissance agent. Reads code, finds files, fetches docs. Gathers precisely what's needed — nothing more.
+description: Reconnaissance agent. Finds EVERY relevant file for a task — across repos, across layers, across runtime boundaries.
 model: haiku
 tools: Read, Glob, Grep, Bash, WebSearch, WebFetch
 ---
 
 <role>
-You are SCOUT. Gather precisely the information needed for a task — nothing more. Every extra token is budget stolen from Builder.
+You are SCOUT. Your job is to find EVERY file relevant to a task — not just the obvious ones. You trace the complete flow: UI → state → API → backend → database. You search linked repos. You never miss a file.
 </role>
 
-<search_strategy>
-## Search narrow → wide
-1. Grep exact function/component/type name
-2. Glob for likely file paths
-3. Read first 50 lines of promising files (imports + exports only)
-4. Follow brain.db `related_code` if provided
-5. Wide search ONLY if steps 1-4 found nothing
+<flow_tracing>
+## Complete Flow Discovery (the core of what you do)
 
-## Hard limits
-- Max 12 tool calls total. If 5 consecutive searches find nothing, STOP.
-- Max 80 lines read per file (use offset/limit)
-- NEVER read entire files. Signatures + imports only.
-- Prefer Grep over Read. Prefer Glob over Bash ls.
-</search_strategy>
+For any task, trace the FULL flow by searching in 6 directions:
 
-<confidence_levels>
-## Tag every finding (gaps #28, #30, #34)
+**1. Direct matches** — files with the feature name
+```bash
+grep -rl "order" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.rs" --include="*.py" . | head -20
+```
 
-**[VERIFIED]** — confirmed via tool output (grep found it, file exists, npm registry checked)
-**[CITED: url]** — from official docs or README
-**[ASSUMED]** — from training knowledge, needs user confirmation
+**2. Upstream (who calls/renders this)**
+- grep for imports of the found files
+- grep for component usage: `<ComponentName` patterns
+- grep for function calls: `<name>(` patterns
+- grep for route definitions: path strings like `'/feature-name'`
 
-Critical claims MUST have 2+ sources. Single-source = tag as [LOW CONFIDENCE].
-Never state assumptions as facts.
-</confidence_levels>
+**3. Downstream (what this calls/uses)**
+- Read imports of found files
+- Follow: service calls, API fetches, database queries, hooks
+- grep for: `fetch(`, `axios.`, `useQuery(`, `useMutation(`
 
-<architecture_mapping>
-## For medium/complex tasks, identify tier ownership (gap #29)
+**4. State connections (Redux/Zustand/Context)**
+- grep for: `dispatch(orderActions.` or `orderSlice` or `useOrderStore`
+- grep for selectors: `selectOrder` or `makeSelectOrder` or `useSelector.*order`
+- grep for reducers/slices that handle this state
 
-| Tier | What lives here |
-|------|-----------------|
-| Client | Components, hooks, local state, routing |
-| Server | API routes, middleware, auth, SSR |
-| Database | Models, queries, migrations, seeds |
-| External | Third-party APIs, webhooks, CDN |
+**5. API/Backend bridge**
+- grep for endpoint strings: `'/api/orders'` or `'/orders'`
+- This finds BOTH frontend callers AND backend handlers
+- In linked repos: same grep runs across all brains
 
-Output which tiers the task touches.
-</architecture_mapping>
+**6. Data layer**
+- grep for table/model names: `orders` in SQL, ORM, migration files
+- grep for: `.findAll(`, `.create(`, `.update(`, `.delete(` near the feature name
+- grep for schema/migration files: `CreateTable`, `ALTER TABLE`
+</flow_tracing>
 
-<runtime_state>
-## For rename/refactor tasks only (gap #31)
+<search_strategy>
+## Search order
 
-Check 5 categories:
-1. Stored data — what DBs store the renamed string?
-2. Config — what external UIs/services reference it?
-3. OS registrations — cron jobs, launch agents, task scheduler?
-4. Secrets/env — what .env or CI vars reference it?
-5. Build artifacts — compiled files, Docker images, lock files?
+1. **MCP brain_search** (if available) — instant results from brain.db + linked repos
+2. **Grep** for feature keywords across entire codebase
+3. **Read imports** of found files to discover downstream dependencies
+4. **Grep for consumers** of found files to discover upstream callers
+5. **Architecture query** — `brain_arch_data_flow` to see layer position + connections
+6. **Linked repos** — `brain_linked` to check if cross-repo search is needed
 
-If nothing in a category, state explicitly: "None — verified by [how]"
-</runtime_state>
+## Hard limits
+- Max 15 tool calls. If 5 consecutive find nothing new, STOP.
+- Max 80 lines per file read (imports + key functions only)
+- Prefer Grep over Read. Prefer MCP tools over raw sqlite3.
+</search_strategy>
+
+<confidence_levels>
+**[VERIFIED]** — grep found it, file confirmed to exist
+**[CITED: source]** — from docs or official source
+**[ASSUMED]** — training knowledge, needs confirmation
+**[LINKED: repo-name]** — found in a linked repo
+
+Critical claims need 2+ sources. Single-source = [LOW CONFIDENCE].
+</confidence_levels>
 
 <output_format>
 ## Findings
 
-### Files (with confidence)
-- `path/to/file.ts` — [purpose, 5 words] [VERIFIED]
+### Flow Map
+Build a tree showing how files connect — from what you actually found via grep/read.
+Show each file with its role (entry/state/service/api/data) and how it connects to the next.
+Tag linked repo files. Show the ACTUAL chain, not a generic template.
 
-### Key Functions
-- `functionName(params)` in `file.ts:42` — [what it does] [VERIFIED]
-
-### Consumers (CRITICAL for refactors)
-- `functionName` is imported by: `file1.ts`, `file2.ts`, `file3.ts` [VERIFIED]
+### Files
+Group every found file by its role in the flow. Tag with [VERIFIED] or [LINKED: repo].
 
-### Types
-- `TypeName` in `file.ts:10` — { field1, field2 } [VERIFIED]
+### Key Functions
+List function signatures with file:line for anything Builder will need to modify.
 
-### Architecture
-- Tiers touched: [Client, Server, Database]
+### Consumers
+For every function/type/export that might be changed: list ALL files that import/use it.
+This is the MOST IMPORTANT section — missing a consumer causes cascading breaks.
 
-### Conventions
-- [import style, error handling, state management pattern]
+### Config/Env
+List any env vars, feature flags, or config referenced by the found files.
 
 ### Risks
-- [gotchas, deprecated APIs, version quirks] [confidence level]
+Gotchas, deprecated APIs, version-specific behavior found during search.
 
 ### Recommendation
-[2-3 sentences: what to change, which files, what consumers to update]
+What to change, which files, which consumers to update, cross-repo impact.
 </output_format>
 
 <anti_patterns>
-- Reading entire directories "to understand the project"
-- Reading config files "just in case"
-- Searching for broad patterns ("how is error handling done")
-- Reading the same file twice
-- Continuing after finding the answer — STOP immediately
-- Stating unverified claims without [ASSUMED] tag
+- Stopping after finding the "main" file — ALWAYS trace the full flow
+- Missing linked repo files — ALWAYS check brain_linked
+- Ignoring state management connections — grep for dispatch/selector/store
+- Ignoring API string matches — the string '/api/orders' bridges frontend↔backend
+- Reading entire files — signatures + imports only
+- Stating unverified claims without confidence tag
 </anti_patterns>
 
 <context>
@@ -103,7 +113,8 @@ $ARGUMENTS
 </context>
 
 <task>
-Research the task. Return compact, actionable findings with confidence tags.
-Include consumer list for anything Builder might modify/remove.
-Stop as soon as you have enough. Less is more.
+Find EVERY file relevant to this task.
+Trace the complete flow: entry → state → service → API → backend → data.
+Search linked repos. Check consumers. Map the architecture layers.
+Output a flow map + grouped file list + consumer list.
 </task>

package/bin/install.js

@@ -15,6 +15,25 @@ const path = require('path');
 const os = require('os');
 const { execFileSync: safeRun } = require('child_process');
 
+// WSL + Windows detection (from GSD's 49-release edge case fixes)
+if (process.platform === 'win32') {
+  let isWSL = false;
+  try {
+    if (process.env.WSL_DISTRO_NAME) isWSL = true;
+    else if (fs.existsSync('/proc/version')) {
+      const pv = fs.readFileSync('/proc/version', 'utf8').toLowerCase();
+      if (pv.includes('microsoft') || pv.includes('wsl')) isWSL = true;
+    }
+  } catch {}
+  if (isWSL) {
+    console.error('\nDetected WSL with Windows-native Node.js.');
+    console.error('Install a Linux-native Node.js inside WSL:');
+    console.error('  curl -fsSL https://fnm.vercel.app/install | bash');
+    console.error('  fnm install --lts\n');
+    process.exit(1);
+  }
+}
+
 const cyan = '\x1b[36m';
 const green = '\x1b[32m';
 const yellow = '\x1b[33m';
@@ -54,12 +73,11 @@ function main() {
   switch (command) {
     case 'init':
     case 'train':    return cmdInit();
+    case 'link':     return cmdLink();
+    case 'unlink':   return cmdUnlink();
     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':
@@ -229,6 +247,142 @@ function cmdInit() {
   }
 }
 
+// ============================================================
+// LINK — connect another repo's brain for cross-repo awareness
+// ============================================================
+
+function cmdLink() {
+  const targetPath = process.argv[3];
+  if (!targetPath) {
+    console.log(`${bold}Usage:${reset} shipfast link <path-to-other-repo>\n`);
+    console.log(`Links another repo's brain.db so agents can query across repos.`);
+    console.log(`Example: ${cyan}shipfast link ../backend${reset}\n`);
+
+    // Show current links
+    const cwd = process.cwd();
+    const brainDb = path.join(cwd, '.shipfast', 'brain.db');
+    if (fs.existsSync(brainDb)) {
+      try {
+        const links = safeRun('sqlite3', ['-json', brainDb, "SELECT value FROM config WHERE key = 'linked_repos';"], {
+          encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+        if (links) {
+          const parsed = JSON.parse(links);
+          if (parsed.length && parsed[0].value) {
+            const repos = JSON.parse(parsed[0].value);
+            if (repos.length) {
+              console.log(`${bold}Linked repos:${reset}`);
+              repos.forEach(r => {
+                const hasDb = fs.existsSync(path.join(r, '.shipfast', 'brain.db'));
+                console.log(`  ${hasDb ? green : red}${r}${reset} ${hasDb ? '(brain.db found)' : '(brain.db missing — run shipfast init there)'}`);
+              });
+              console.log('');
+            }
+          }
+        }
+      } catch {}
+    }
+    return;
+  }
+
+  const cwd = process.cwd();
+  const resolved = path.resolve(cwd, targetPath);
+
+  // Validate target
+  if (!fs.existsSync(resolved)) {
+    console.log(`${red}Path not found: ${resolved}${reset}\n`);
+    return;
+  }
+
+  if (!fs.existsSync(path.join(resolved, '.git'))) {
+    console.log(`${yellow}Warning: ${resolved} is not a git repo.${reset}`);
+  }
+
+  const targetBrain = path.join(resolved, '.shipfast', 'brain.db');
+  if (!fs.existsSync(targetBrain)) {
+    console.log(`${yellow}Warning: No brain.db found at ${resolved}. Run ${cyan}shipfast init${reset}${yellow} there first.${reset}`);
+  }
+
+  // Ensure local brain exists
+  const localBrain = path.join(cwd, '.shipfast', 'brain.db');
+  if (!fs.existsSync(localBrain)) {
+    console.log(`${red}No local brain.db. Run ${cyan}shipfast init${reset}${red} first.${reset}\n`);
+    return;
+  }
+
+  // Get existing links
+  let links = [];
+  try {
+    const existing = safeRun('sqlite3', ['-json', localBrain, "SELECT value FROM config WHERE key = 'linked_repos';"], {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    if (existing) {
+      const parsed = JSON.parse(existing);
+      if (parsed.length && parsed[0].value) links = JSON.parse(parsed[0].value);
+    }
+  } catch {}
+
+  // Add if not already linked
+  if (links.includes(resolved)) {
+    console.log(`${dim}Already linked: ${resolved}${reset}\n`);
+    return;
+  }
+
+  links.push(resolved);
+  const escaped = JSON.stringify(links).replace(/'/g, "''");
+  safeRun('sqlite3', [localBrain, `INSERT OR REPLACE INTO config (key, value) VALUES ('linked_repos', '${escaped}');`], {
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  console.log(`${green}Linked: ${resolved}${reset}`);
+  console.log(`${dim}Agents will now query both local and linked brains.${reset}`);
+  console.log(`${dim}Total linked repos: ${links.length}${reset}\n`);
+}
+
+function cmdUnlink() {
+  const targetPath = process.argv[3];
+  const cwd = process.cwd();
+  const localBrain = path.join(cwd, '.shipfast', 'brain.db');
+
+  if (!fs.existsSync(localBrain)) {
+    console.log(`${red}No local brain.db.${reset}\n`);
+    return;
+  }
+
+  // Get existing links
+  let links = [];
+  try {
+    const existing = safeRun('sqlite3', ['-json', localBrain, "SELECT value FROM config WHERE key = 'linked_repos';"], {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    if (existing) {
+      const parsed = JSON.parse(existing);
+      if (parsed.length && parsed[0].value) links = JSON.parse(parsed[0].value);
+    }
+  } catch {}
+
+  if (!targetPath) {
+    // Unlink all
+    if (links.length === 0) {
+      console.log(`${dim}No linked repos.${reset}\n`);
+      return;
+    }
+    safeRun('sqlite3', [localBrain, "DELETE FROM config WHERE key = 'linked_repos';"], {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    console.log(`${green}Unlinked all ${links.length} repos.${reset}\n`);
+    return;
+  }
+
+  const resolved = path.resolve(cwd, targetPath);
+  links = links.filter(l => l !== resolved);
+  const escaped = JSON.stringify(links).replace(/'/g, "''");
+  safeRun('sqlite3', [localBrain, `INSERT OR REPLACE INTO config (key, value) VALUES ('linked_repos', '${escaped}');`], {
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+  console.log(`${green}Unlinked: ${resolved}${reset}\n`);
+}
+
 function findIndexer() {
   // Check all global runtime dirs + package source
   const paths = Object.values(RUNTIMES)
@@ -338,12 +492,14 @@ 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`);
+  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 link <path>${reset}      Link another repo for cross-repo search`);
+  console.log(`  ${cyan}shipfast unlink [path]${reset}    Unlink a repo (or all)`);
+  console.log(`  ${cyan}shipfast status${reset}           Show installed runtimes + brain + links`);
+  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`);
   console.log(`${bold}In your AI tool:${reset}\n`);
   console.log(`  ${cyan}/sf-do${reset} <task>         The one command — describe what you want`);
   console.log(`  ${cyan}/sf-discuss${reset} <task>    Clarify ambiguity before planning`);

package/brain/index.cjs

@@ -32,7 +32,8 @@ function initBrain(cwd) {
   const dbPath = getBrainPath(cwd);
   const schemaPath = path.join(__dirname, 'schema.sql');
   const schema = fs.readFileSync(schemaPath, 'utf8');
-  execFileSync('sqlite3', [dbPath], { input: schema, stdio: ['pipe', 'pipe', 'pipe'] });
+  // Enable WAL mode for corruption protection (safe against interrupted writes)
+  execFileSync('sqlite3', [dbPath], { input: 'PRAGMA journal_mode=WAL;\n' + schema, stdio: ['pipe', 'pipe', 'pipe'] });
   return dbPath;
 }
 

package/hooks/sf-first-run.js

@@ -16,7 +16,7 @@ const path = require('path');
 const os = require('os');
 
 let input = '';
-const stdinTimeout = setTimeout(() => process.exit(0), 5000);
+const stdinTimeout = setTimeout(() => process.exit(0), 10000); // consistent 10s timeout across all hooks
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {

package/mcp/server.cjs

@@ -47,6 +47,41 @@ function run(sql) {
   } catch { return false; }
 }
 
+// Query linked repos (cross-repo search)
+function getLinkedPaths() {
+  try {
+    const rows = query("SELECT value FROM config WHERE key = 'linked_repos'");
+    if (rows.length && rows[0].value) return JSON.parse(rows[0].value);
+  } catch {}
+  return [];
+}
+
+function queryLinked(sql) {
+  // Query local brain first
+  const local = query(sql);
+
+  // Then query each linked repo's brain
+  const linked = getLinkedPaths();
+  const results = [...local];
+  for (const repoPath of linked) {
+    const linkedDb = path.join(repoPath, '.shipfast', 'brain.db');
+    if (!fs.existsSync(linkedDb)) continue;
+    try {
+      const r = safeRun('sqlite3', ['-json', linkedDb, sql], {
+        encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      if (r) {
+        const parsed = JSON.parse(r);
+        // Tag results with source repo
+        const repoName = path.basename(repoPath);
+        parsed.forEach(row => { row._repo = repoName; });
+        results.push(...parsed);
+      }
+    } catch {}
+  }
+  return results;
+}
+
 function esc(s) {
   return s == null ? '' : String(s).replace(/'/g, "''");
 }
@@ -76,8 +111,24 @@ const TOOLS = {
     }
   },
 
+  brain_linked: {
+    description: 'Show linked repos and their brain.db status. Use shipfast link to connect repos for cross-repo search.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    handler() {
+      const linked = getLinkedPaths();
+      if (!linked.length) return { linked: [], message: 'No repos linked. Use: shipfast link ../other-repo' };
+      return {
+        linked: linked.map(p => ({
+          path: p,
+          name: path.basename(p),
+          hasBrain: fs.existsSync(path.join(p, '.shipfast', 'brain.db'))
+        }))
+      };
+    }
+  },
+
   brain_search: {
-    description: 'Search the codebase knowledge graph for files, functions, types, or components by name.',
+    description: 'Search the codebase knowledge graph for files, functions, types, or components by name. Searches local + all linked repos.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -88,7 +139,7 @@ const TOOLS = {
     },
     handler({ query: q, kind }) {
       const kindFilter = kind ? `AND kind = '${esc(kind)}'` : '';
-      return query(
+      return queryLinked(
         `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`
@@ -415,7 +466,7 @@ function handleMessage(msg) {
       result: {
         protocolVersion: '2024-11-05',
         capabilities: { tools: {} },
-        serverInfo: { name: 'shipfast-brain', version: '0.5.0' }
+        serverInfo: { name: 'shipfast-brain', version: '1.0.0' }
       }
     });
   }
@@ -440,9 +491,14 @@ function handleMessage(msg) {
 
     try {
       const result = tool.handler(params.arguments || {});
+      let text = JSON.stringify(result, null, 2);
+      // Truncate large responses to prevent context flooding (50KB max)
+      if (text.length > 50000) {
+        text = text.slice(0, 50000) + '\n... [truncated — ' + text.length + ' chars total. Use more specific query.]';
+      }
       return send({
         jsonrpc: '2.0', id,
-        result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
+        result: { content: [{ type: 'text', text }] }
       });
     } catch (err) {
       return send({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipfast-ai/shipfast",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Autonomous context-engineered development system with SQLite brain. 5 agents, 14 commands, per-task fresh context, 70-90% fewer tokens.",
   "bin": {
     "shipfast": "bin/install.js"