sourcebook 0.5.1 → 0.6.0

package/README.md

@@ -4,25 +4,27 @@
 
 # sourcebook
 
-Generate AI context files from your codebase's actual conventions. Not what agents already know — what they keep missing.
+**AI can read your code. It still doesn't know how your project works.**
+
+sourcebook captures the project knowledge your team carries in its head — conventions, patterns, traps, and where things actually go — and turns it into context your coding agent can use.
 
 ```bash
 npx sourcebook init
 ```
 
-One command. Analyzes your codebase. Outputs a `CLAUDE.md` tuned for how your project actually works.
-
 <p align="center">
   <img src="demo.svg" alt="sourcebook demo" width="820" />
 </p>
 
+> Tools like Repomix give AI your entire codebase. sourcebook gives it your project knowledge.
+
 ## Why
 
-AI coding agents spend most of their context window just orienting — reading files to build a mental model before doing real work. Developers manually write context files (`CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`), but most are generic and go stale fast.
+AI coding agents spend most of their context window orienting — reading files to build a mental model before doing real work. Most context files (`CLAUDE.md`, `.cursorrules`) are generic and go stale fast.
 
-Research shows auto-generated context that restates obvious information (tech stack, directory structure) actually makes agents [worse by 2-3%](https://arxiv.org/abs/2502.09601). The only context that helps is **non-discoverable information** — things agents can't figure out by reading the code alone.
+Research shows auto-generated context that restates obvious information actually makes agents [worse by 2-3%](https://arxiv.org/abs/2502.09601). The only context that helps is **non-discoverable information** — the project knowledge agents can't figure out by reading code alone.
 
-sourcebook inverts the typical approach: instead of dumping everything, it extracts only what agents keep missing, filtered through a discoverability test.
+sourcebook extracts only what agents keep missing: the conventions, hidden dependencies, fragile areas, and dominant patterns that live in your team's heads — not in the code.
 
 ## What It Finds
 
@@ -62,6 +64,7 @@ npx sourcebook init --budget 1000
 | `sourcebook init` | Analyze codebase and generate context files |
 | `sourcebook update` | Re-analyze while preserving sections you added manually |
 | `sourcebook diff` | Show what would change without writing files (exit code 1 if changes found — useful for CI) |
+| `sourcebook serve` | Start an MCP server exposing live codebase intelligence (Pro) |
 
 ### Options
 
@@ -142,6 +145,59 @@ Then applies a **discoverability filter**: for every finding, asks "can an agent
 
 Output is formatted for **context-rot resistance** — critical constraints go at the top and bottom of the file (where LLMs pay the most attention), lightweight reference info goes in the middle.
 
+## MCP Server Mode
+
+> **Pro feature** — requires a sourcebook Pro license.
+
+`sourcebook serve` starts a local MCP (Model Context Protocol) server that exposes live codebase intelligence to any MCP-compatible AI client — Claude Desktop, Cursor, and others.
+
+Instead of a static context file, your AI agent can query your project's architecture on demand: look up blast radius before editing, check conventions before writing code, mine git history for anti-patterns.
+
+### Setup
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sourcebook": {
+      "command": "npx",
+      "args": ["sourcebook", "serve", "--dir", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "sourcebook": {
+      "command": "npx",
+      "args": ["sourcebook", "serve", "--dir", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+Restart your client after updating the config.
+
+### Available Tools
+
+| Tool | What it does |
+|------|-------------|
+| `analyze_codebase` | Full analysis: languages, frameworks, findings, top files by PageRank importance |
+| `get_file_context` | File-level context: importance score, hub status, co-change partners, applicable conventions |
+| `get_blast_radius` | Risk assessment for editing a file: dependents, co-change coupling, fragility, circular deps |
+| `query_conventions` | All detected project conventions: import style, error handling, naming, commit format |
+| `get_import_graph` | Dependency architecture: hub files, circular deps, dead code, PageRank rankings |
+| `get_git_insights` | Git history mining: fragile files, reverted commits, anti-patterns, active dev areas |
+| `get_pressing_questions` | Pre-edit briefing: everything important to know before touching a specific file |
+| `search_codebase_context` | Keyword search across all findings, conventions, structure, and frameworks |
+
+The server caches the scan in memory — subsequent tool calls are fast. Pass `refresh: true` to `analyze_codebase` to force a re-scan.
+
 ## Roadmap
 
 - [x] `.cursor/rules/sourcebook.mdc` + legacy `.cursorrules` output
@@ -153,9 +209,9 @@ Output is formatted for **context-rot resistance** — critical constraints go a
 - [x] Python support (Django, FastAPI, Flask, pytest)
 - [x] Go support (Gin, Echo, Fiber, module layout)
 - [x] GitHub Action for CI
+- [x] `sourcebook serve` — MCP server mode
 - [ ] Framework knowledge packs (community-contributed)
 - [ ] Tree-sitter AST parsing for deeper convention detection
-- [ ] `sourcebook serve` — MCP server mode
 - [ ] Hosted dashboard with context quality scores
 
 ## Research Foundation

package/dist/cli.js

@@ -4,6 +4,7 @@ import { init } from "./commands/init.js";
 import { update } from "./commands/update.js";
 import { diff } from "./commands/diff.js";
 import { activate } from "./commands/activate.js";
+import { serve } from "./commands/serve.js";
 const program = new Command();
 program
     .name("sourcebook")
@@ -35,4 +36,9 @@ program
     .command("activate <key>")
     .description("Activate a Pro or Team license key")
     .action(activate);
+program
+    .command("serve")
+    .description("Start an MCP server over STDIO for AI tool integration")
+    .option("-d, --dir <path>", "Target directory to analyze", ".")
+    .action(serve);
 program.parse();

package/dist/commands/serve.d.ts

@@ -0,0 +1,5 @@
+interface ServeOptions {
+    dir: string;
+}
+export declare function serve(options: ServeOptions): Promise<void>;
+export {};

package/dist/commands/serve.js

@@ -0,0 +1,556 @@
+import { Server } from "@modelcontextprotocol/sdk/server";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types";
+import path from "node:path";
+import { requirePro } from "../auth/license.js";
+import { scanProject } from "../scanner/index.js";
+import { analyzeImportGraph } from "../scanner/graph.js";
+// Cache the scan to avoid re-running on every tool call
+let cachedScan = null;
+let cachedDir = null;
+async function getScan(dir) {
+    const resolved = path.resolve(dir);
+    if (cachedScan && cachedDir === resolved) {
+        return cachedScan;
+    }
+    cachedScan = await scanProject(resolved);
+    cachedDir = resolved;
+    return cachedScan;
+}
+function invalidateCache() {
+    cachedScan = null;
+    cachedDir = null;
+}
+const TOOLS = [
+    {
+        name: "analyze_codebase",
+        description: "Run a full sourcebook analysis on the codebase. Returns the complete ProjectScan including detected languages, frameworks, build commands, project structure, architectural findings, file importance rankings, and repo mode. Use this for a comprehensive overview before making changes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                refresh: {
+                    type: "boolean",
+                    description: "Force a fresh scan instead of using cached results. Default: false.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_file_context",
+        description: "Get context for a specific file: its importance score (PageRank), what imports it, what it imports, which conventions apply to it, and whether it appears in co-change clusters. Use this before editing a file to understand its role and impact.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Relative file path from the project root (e.g. 'src/utils/auth.ts').",
+                },
+            },
+            required: ["file"],
+        },
+    },
+    {
+        name: "get_blast_radius",
+        description: "Determine what could break if you edit a given file. Returns direct dependents (files that import it), co-change partners (files historically modified together), and whether the file is a hub module. Use this to assess risk before modifying critical code.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Relative file path from the project root (e.g. 'src/lib/db.ts').",
+                },
+            },
+            required: ["file"],
+        },
+    },
+    {
+        name: "query_conventions",
+        description: "Return all detected conventions and patterns in the codebase: import styles, error handling, naming conventions, framework-specific patterns, and commit conventions. Use this to ensure new code follows established project patterns.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "Optional filter by category (e.g. 'Import conventions', 'Error handling', 'Commit conventions'). Returns all conventions if omitted.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_import_graph",
+        description: "Get import relationship data: hub files (most depended-on), circular dependencies, dead code candidates, and file importance rankings from PageRank analysis. Use this to understand the dependency architecture.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Optional file path to focus on. If provided, returns only edges involving this file. If omitted, returns the full graph summary.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_git_insights",
+        description: "Get insights mined from git history: fragile files (high churn), reverted commits (failed approaches to avoid), active development areas, co-change coupling (invisible dependencies), and commit conventions. Use this to avoid repeating past mistakes.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "get_pressing_questions",
+        description: "Get the most important things to know before editing a specific file or area of the codebase. Combines blast radius, conventions, git history, and structural context into prioritized guidance. This is the 'what should I know?' briefing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Relative file path you're about to edit (e.g. 'src/api/routes.ts').",
+                },
+            },
+            required: ["file"],
+        },
+    },
+    {
+        name: "search_codebase_context",
+        description: "Search across all analyzed context (findings, conventions, structure, frameworks) by keyword. Returns matching findings with their category, confidence, and rationale. Use this when looking for specific architectural knowledge.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Keyword or phrase to search for across all findings and context (e.g. 'authentication', 'circular', 'migration').",
+                },
+            },
+            required: ["query"],
+        },
+    },
+];
+// --- Tool Handlers ---
+async function handleAnalyzeCodebase(dir, args) {
+    if (args.refresh)
+        invalidateCache();
+    const scan = await getScan(dir);
+    return {
+        dir: scan.dir,
+        languages: scan.languages,
+        frameworks: scan.frameworks,
+        repoMode: scan.repoMode,
+        commands: scan.commands,
+        structure: {
+            layout: scan.structure.layout,
+            entryPoints: scan.structure.entryPoints,
+            directories: scan.structure.directories,
+        },
+        fileCount: scan.files.length,
+        findingCount: scan.findings.length,
+        findings: scan.findings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+        topFiles: (scan.rankedFiles || []).slice(0, 15).map((f) => ({
+            file: f.file,
+            score: Math.round(f.score * 10000) / 10000,
+        })),
+    };
+}
+async function handleGetFileContext(dir, args) {
+    const scan = await getScan(dir);
+    const file = args.file;
+    // Find importance score
+    const ranked = scan.rankedFiles || [];
+    const fileRank = ranked.find((r) => r.file === file);
+    const rank = ranked.findIndex((r) => r.file === file);
+    // Find findings mentioning this file
+    const relevantFindings = scan.findings.filter((f) => f.evidence?.includes(file) ||
+        f.description.includes(file) ||
+        f.description.includes(path.basename(file)));
+    // Get conventions that apply (category-based)
+    const conventionCategories = new Set([
+        "Import conventions",
+        "Error handling",
+        "TypeScript",
+        "TypeScript imports",
+        "Commit conventions",
+    ]);
+    const conventions = scan.findings.filter((f) => conventionCategories.has(f.category));
+    // Check if it's a hub file
+    const hubFinding = scan.findings.find((f) => f.category === "Core modules" && f.description.includes(file));
+    // Check co-change clusters
+    const coChangeFinding = scan.findings.find((f) => f.category === "Hidden dependencies" &&
+        (f.description.includes(path.basename(file)) ||
+            f.description.includes(file)));
+    return {
+        file,
+        exists: scan.files.includes(file),
+        importance: fileRank
+            ? {
+                score: Math.round(fileRank.score * 10000) / 10000,
+                rank: rank + 1,
+                totalFiles: ranked.length,
+            }
+            : null,
+        isHub: !!hubFinding,
+        hubDetail: hubFinding?.description || null,
+        coChangePartners: coChangeFinding?.description || null,
+        relevantFindings: relevantFindings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            confidence: f.confidence,
+        })),
+        applicableConventions: conventions.map((f) => ({
+            category: f.category,
+            description: f.description,
+        })),
+    };
+}
+async function handleGetBlastRadius(dir, args) {
+    const scan = await getScan(dir);
+    const file = args.file;
+    // Re-run import graph to get edge-level data
+    const graphAnalysis = await analyzeImportGraph(path.resolve(dir), scan.files);
+    // Find files that import this file (dependents)
+    // We need to look at the graph findings for hub info
+    const hubFinding = scan.findings.find((f) => f.category === "Core modules" && f.description.includes(file));
+    // Co-change partners from git analysis
+    const coChangeFinding = scan.findings.find((f) => f.category === "Hidden dependencies" &&
+        (f.description.includes(path.basename(file)) ||
+            f.description.includes(file)));
+    // Fragile code mentions
+    const fragileFinding = scan.findings.find((f) => f.category === "Fragile code" && f.description.includes(file));
+    // Circular dependency involvement
+    const circularFinding = scan.findings.find((f) => f.category === "Circular dependencies" &&
+        f.description.includes(path.basename(file)));
+    // Importance rank
+    const ranked = scan.rankedFiles || [];
+    const fileRank = ranked.find((r) => r.file === file);
+    return {
+        file,
+        importance: fileRank
+            ? Math.round(fileRank.score * 10000) / 10000
+            : null,
+        isHub: !!hubFinding,
+        hubDetail: hubFinding?.description || null,
+        coChangePartners: coChangeFinding?.description || null,
+        isFragile: !!fragileFinding,
+        fragileDetail: fragileFinding?.description || null,
+        inCircularDep: !!circularFinding,
+        circularDetail: circularFinding?.description || null,
+        graphFindings: graphAnalysis.findings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            confidence: f.confidence,
+        })),
+        riskLevel: hubFinding
+            ? "high"
+            : circularFinding || fragileFinding
+                ? "medium"
+                : "low",
+    };
+}
+async function handleQueryConventions(dir, args) {
+    const scan = await getScan(dir);
+    // Convention-related categories
+    const conventionCategories = new Set([
+        "Import conventions",
+        "Error handling",
+        "TypeScript",
+        "TypeScript imports",
+        "Commit conventions",
+        "Tailwind",
+        "Next.js routing",
+        "Next.js deployment",
+        "Next.js images",
+        "Expo routing",
+        "Expo builds",
+        "Expo deep linking",
+        "Supabase",
+        "Django",
+        "FastAPI",
+        "Go module",
+        "Go layout",
+        "Go visibility",
+        "Testing",
+        "Python environment",
+        "Dominant patterns",
+    ]);
+    let conventions = scan.findings.filter((f) => conventionCategories.has(f.category) ||
+        f.category.includes("convention") ||
+        f.category.includes("pattern"));
+    if (args.category) {
+        const cat = args.category.toLowerCase();
+        conventions = conventions.filter((f) => f.category.toLowerCase().includes(cat));
+    }
+    return {
+        conventions: conventions.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+        frameworks: scan.frameworks,
+        repoMode: scan.repoMode,
+    };
+}
+async function handleGetImportGraph(dir, args) {
+    const scan = await getScan(dir);
+    const graphFindings = scan.findings.filter((f) => ["Core modules", "Circular dependencies", "Dead code candidates"].includes(f.category));
+    const ranked = scan.rankedFiles || [];
+    if (args.file) {
+        const fileRank = ranked.find((r) => r.file === args.file);
+        const rank = ranked.findIndex((r) => r.file === args.file);
+        return {
+            file: args.file,
+            importance: fileRank
+                ? {
+                    score: Math.round(fileRank.score * 10000) / 10000,
+                    rank: rank + 1,
+                    totalFiles: ranked.length,
+                }
+                : null,
+            graphFindings: graphFindings
+                .filter((f) => f.description.includes(args.file) ||
+                f.description.includes(path.basename(args.file)))
+                .map((f) => ({
+                category: f.category,
+                description: f.description,
+                confidence: f.confidence,
+            })),
+        };
+    }
+    return {
+        topFiles: ranked.slice(0, 20).map((f) => ({
+            file: f.file,
+            score: Math.round(f.score * 10000) / 10000,
+        })),
+        findings: graphFindings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            confidence: f.confidence,
+        })),
+    };
+}
+async function handleGetGitInsights(dir) {
+    const scan = await getScan(dir);
+    const gitCategories = new Set([
+        "Git history",
+        "Anti-patterns",
+        "Active development",
+        "Hidden dependencies",
+        "Fragile code",
+        "Commit conventions",
+    ]);
+    const gitFindings = scan.findings.filter((f) => gitCategories.has(f.category));
+    return {
+        findings: gitFindings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+    };
+}
+async function handleGetPressingQuestions(dir, args) {
+    const scan = await getScan(dir);
+    const file = args.file;
+    const basename = path.basename(file);
+    const questions = [];
+    // Check if it's a hub file
+    const hubFinding = scan.findings.find((f) => f.category === "Core modules" && f.description.includes(file));
+    if (hubFinding) {
+        questions.push({
+            priority: 1,
+            question: "This is a hub file with wide blast radius",
+            detail: hubFinding.description,
+        });
+    }
+    // Check circular dependencies
+    const circularFinding = scan.findings.find((f) => f.category === "Circular dependencies" &&
+        f.description.includes(basename));
+    if (circularFinding) {
+        questions.push({
+            priority: 2,
+            question: "This file is involved in a circular dependency",
+            detail: circularFinding.description,
+        });
+    }
+    // Check fragile code
+    const fragileFinding = scan.findings.find((f) => f.category === "Fragile code" && f.description.includes(file));
+    if (fragileFinding) {
+        questions.push({
+            priority: 3,
+            question: "This file has high recent churn (hard to get right)",
+            detail: fragileFinding.description,
+        });
+    }
+    // Check co-change coupling
+    const coChangeFinding = scan.findings.find((f) => f.category === "Hidden dependencies" &&
+        (f.description.includes(basename) || f.description.includes(file)));
+    if (coChangeFinding) {
+        questions.push({
+            priority: 4,
+            question: "This file has hidden dependencies (co-change partners)",
+            detail: coChangeFinding.description,
+        });
+    }
+    // Check anti-patterns
+    const antiPatterns = scan.findings.filter((f) => f.category === "Anti-patterns");
+    if (antiPatterns.length > 0) {
+        questions.push({
+            priority: 5,
+            question: "There are known anti-patterns in this project",
+            detail: antiPatterns.map((f) => f.description).join("; "),
+        });
+    }
+    // Applicable conventions
+    const conventions = scan.findings.filter((f) => f.category.includes("convention") ||
+        f.category.includes("Convention") ||
+        f.category.includes("Import") ||
+        f.category.includes("TypeScript") ||
+        f.category.includes("pattern") ||
+        f.category.includes("Pattern"));
+    if (conventions.length > 0) {
+        questions.push({
+            priority: 6,
+            question: "Follow these project conventions",
+            detail: conventions.map((f) => f.description).join("; "),
+        });
+    }
+    // Active development area?
+    const activeFinding = scan.findings.find((f) => f.category === "Active development" &&
+        f.description.includes(file.split("/")[0]));
+    if (activeFinding) {
+        questions.push({
+            priority: 7,
+            question: "This area is under active development",
+            detail: activeFinding.description,
+        });
+    }
+    questions.sort((a, b) => a.priority - b.priority);
+    return {
+        file,
+        questions,
+        summary: questions.length > 0
+            ? `${questions.length} things to know before editing ${file}`
+            : `No special concerns found for ${file}`,
+    };
+}
+async function handleSearchCodebaseContext(dir, args) {
+    const scan = await getScan(dir);
+    const query = args.query.toLowerCase();
+    const matches = scan.findings.filter((f) => f.description.toLowerCase().includes(query) ||
+        f.category.toLowerCase().includes(query) ||
+        (f.rationale && f.rationale.toLowerCase().includes(query)) ||
+        (f.evidence && f.evidence.toLowerCase().includes(query)));
+    // Also search structure
+    const structureMatches = [];
+    for (const [dir, purpose] of Object.entries(scan.structure.directories)) {
+        if (dir.toLowerCase().includes(query) ||
+            purpose.toLowerCase().includes(query)) {
+            structureMatches.push({ key: dir, value: purpose });
+        }
+    }
+    // Search frameworks
+    const frameworkMatches = scan.frameworks.filter((f) => f.toLowerCase().includes(query));
+    return {
+        query: args.query,
+        findings: matches.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+        structureMatches,
+        frameworkMatches,
+        totalResults: matches.length + structureMatches.length + frameworkMatches.length,
+    };
+}
+// --- Main ---
+export async function serve(options) {
+    await requirePro("sourcebook serve");
+    const dir = path.resolve(options.dir);
+    // Suppress all console output — STDIO transport uses stdout for JSON-RPC
+    const originalLog = console.log;
+    const originalError = console.error;
+    console.log = () => { };
+    console.error = () => { };
+    const server = new Server({
+        name: "sourcebook",
+        version: "0.6.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case "analyze_codebase":
+                    result = await handleAnalyzeCodebase(dir, args);
+                    break;
+                case "get_file_context":
+                    result = await handleGetFileContext(dir, args);
+                    break;
+                case "get_blast_radius":
+                    result = await handleGetBlastRadius(dir, args);
+                    break;
+                case "query_conventions":
+                    result = await handleQueryConventions(dir, args);
+                    break;
+                case "get_import_graph":
+                    result = await handleGetImportGraph(dir, args);
+                    break;
+                case "get_git_insights":
+                    result = await handleGetGitInsights(dir);
+                    break;
+                case "get_pressing_questions":
+                    result = await handleGetPressingQuestions(dir, args);
+                    break;
+                case "search_codebase_context":
+                    result = await handleSearchCodebaseContext(dir, args);
+                    break;
+                default:
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: `Unknown tool: ${name}` }),
+                            },
+                        ],
+                        isError: true,
+                    };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: message }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Restore console for cleanup messages on stderr
+    console.error = originalError;
+}

package/dist/commands/update.js

@@ -28,6 +28,8 @@ const SOURCEBOOK_HEADERS = new Set([
     "High-Impact Files",
     "Code Conventions",
     "Constraints",
+    "Quick Reference",
+    "Dominant Patterns",
 ]);
 /**
  * Re-analyze and regenerate context files while preserving manual edits.

package/dist/scanner/frameworks.js

@@ -218,9 +218,7 @@ export async function detectFrameworks(dir, files) {
                 }
                 const paths = tsconfig?.compilerOptions?.paths;
                 if (paths) {
-                    const aliases = Object.keys(paths)
-                        .map((k) => k.replace("/*", ""))
-                        .join(", ");
+                    const aliases = [...new Set(Object.keys(paths).map((k) => k.replace("/*", "")))].join(", ");
                     findings.push({
                         category: "TypeScript imports",
                         description: `Path aliases configured: ${aliases}. Use these instead of relative imports.`,

package/dist/scanner/git.js

@@ -67,9 +67,14 @@ function detectRevertedPatterns(dir, revertedPatterns) {
     if (reverts.length >= 2) {
         // Extract what was reverted
         const revertDescriptions = [];
+        const REVERT_NOISE = [
+            /\.yml$/i, /\.yaml$/i, /scorecard/i, /dependabot/i,
+            /^update /i, /^bump /i, /^deps/i, /^ci:/i, /^build:/i,
+            /^chore\(deps\)/i, /^chore\(release\)/i,
+        ];
         for (const line of reverts.slice(0, 10)) {
             const match = line.match(/^[a-f0-9]+ Revert "(.+)"/);
-            if (match) {
+            if (match && !REVERT_NOISE.some(n => n.test(match[1]))) {
                 revertDescriptions.push(match[1]);
                 revertedPatterns.push(match[1]);
             }
@@ -103,8 +108,15 @@ function detectAntiPatterns(dir) {
                 antiPatterns.push(match[1]);
             }
         }
-        if (antiPatterns.length > 0) {
-            for (const pattern of antiPatterns.slice(0, 5)) {
+        // Filter out noise: CI config, deps, version bumps
+        const REVERT_NOISE = [
+            /\.yml$/i, /\.yaml$/i, /scorecard/i, /dependabot/i,
+            /^update /i, /^bump /i, /^deps/i, /^ci:/i, /^build:/i,
+            /^chore\(deps\)/i, /^chore\(release\)/i,
+        ];
+        const meaningful = antiPatterns.filter(p => !REVERT_NOISE.some(n => n.test(p)));
+        if (meaningful.length > 0) {
+            for (const pattern of meaningful.slice(0, 5)) {
                 findings.push({
                     category: "Anti-patterns",
                     description: `Tried and reverted: "${pattern}". This approach was explicitly rejected.`,
@@ -137,8 +149,22 @@ function detectAntiPatterns(dir) {
         if (currentFiles.length >= 3) {
             deletionBatches.push({ message: currentMessage, files: currentFiles });
         }
+        // Filter out release/changeset/version commits and revert-of-revert noise
+        const NOISE_PATTERNS = [
+            /^chore\(release\)/i,
+            /^\[ci\] release/i,
+            /^version packages/i,
+            /^changeset/i,
+            /^bump/i,
+            /^release/i,
+            /^Revert "Revert/i,
+            /^merge/i,
+            /^ci:/i,
+            /^build:/i,
+            /^Revert /i,
+        ];
         // Only report significant deletions (3+ files in one commit = abandoned feature)
-        for (const batch of deletionBatches.slice(0, 3)) {
+        for (const batch of deletionBatches.filter(b => !NOISE_PATTERNS.some(p => p.test(b.message))).slice(0, 3)) {
             if (batch.files.length >= 3) {
                 const fileList = batch.files.slice(0, 3).map((f) => path.basename(f)).join(", ");
                 findings.push({
@@ -313,9 +339,17 @@ function detectRapidReEdits(dir) {
     }
     // Find files edited 5+ times within a 7-day window
     const churnyFiles = [];
+    // Filter out non-source files that naturally churn
+    const NON_SOURCE_PATTERNS = [
+        /\.md$/i, /\.mdx$/i, /\.rst$/i, /\.txt$/i, /\.json$/i, /\.ya?ml$/i, /\.lock$/i, /\.log$/i,
+        /CHANGELOG/i, /\.env/, /\.generated\./, /\.config\./,
+        /\.github\//, /\.claude\//, /dashboard\//, /ops\//,
+    ];
     for (const [file, dates] of fileEdits) {
         if (dates.length < 5)
             continue;
+        if (NON_SOURCE_PATTERNS.some((p) => p.test(file)))
+            continue;
         // Sort dates
         dates.sort((a, b) => a.getTime() - b.getTime());
         // Sliding window: find any 7-day window with 5+ edits
@@ -377,7 +411,7 @@ function detectCommitPatterns(dir) {
             .map(([scope]) => scope);
         findings.push({
             category: "Commit conventions",
-            description: `Uses Conventional Commits (feat/fix/docs/etc). ${topScopes.length > 0 ? `Common scopes: ${topScopes.join(", ")}` : ""}. Follow this pattern for new commits.`,
+            description: `Uses Conventional Commits (feat/fix/docs/etc).${topScopes.length > 0 ? ` Common scopes: ${topScopes.join(", ")}.` : ""} Follow this pattern for new commits.`,
             confidence: "high",
             discoverable: false,
         });

package/dist/scanner/patterns.js

@@ -64,8 +64,11 @@ function sampleFiles(files, maxCount) {
         f.includes("layout.") ||
         f.includes("middleware."));
     const rest = files.filter((f) => !priority.includes(f));
-    const shuffled = rest.sort(() => Math.random() - 0.5);
-    return [...priority, ...shuffled].slice(0, maxCount);
+    // Deterministic sampling: sort by path, take evenly spaced files
+    const sorted = rest.sort();
+    const step = Math.max(1, Math.floor(sorted.length / Math.max(1, maxCount - priority.length)));
+    const sampled = sorted.filter((_, i) => i % step === 0);
+    return [...priority, ...sampled].slice(0, maxCount);
 }
 function detectBarrelExports(files, contents) {
     const indexFiles = files.filter((f) => path.basename(f).startsWith("index.") && !f.includes("node_modules"));
@@ -318,7 +321,25 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
             }
         }
     }
-    const dominantI18n = i18nPatterns.filter((p) => p.count >= 3).sort((a, b) => b.count - a.count);
+    // Filter: if only t() matched, require corroborating evidence (i18n files or packages)
+    const hasI18nFiles = files.some((f) => f.includes("locale") || f.includes("i18n") || f.includes("translations") || f.includes("messages/"));
+    let hasI18nPackage = false;
+    for (const [f, c] of allContents) {
+        if (f.endsWith("package.json") && (c.includes("i18next") || c.includes("react-intl") || c.includes("next-intl") || c.includes("@lingui"))) {
+            hasI18nPackage = true;
+            break;
+        }
+    }
+    const dominantI18n = i18nPatterns
+        .filter((p) => {
+        if (p.count < 3)
+            return false;
+        // t() alone is too generic — require corroborating evidence
+        if (p.hook === 't("key")' && !hasI18nFiles && !hasI18nPackage)
+            return false;
+        return true;
+    })
+        .sort((a, b) => b.count - a.count);
     if (dominantI18n.length > 0) {
         const primary = dominantI18n[0];
         let desc = `User-facing strings use ${primary.hook} for internationalization.`;
@@ -345,10 +366,10 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 2. ROUTING / API PATTERNS
     // ========================================
     const routerPatterns = [
-        { pattern: "trpc\\.router|createTRPCRouter|t\\.router", name: "tRPC routers", count: 0 },
+        { pattern: "trpc\\.router|createTRPCRouter|from ['\"]@trpc", name: "tRPC routers", count: 0 },
         { pattern: "express\\.Router|router\\.get|router\\.post", name: "Express routers", count: 0 },
         { pattern: "app\\.get\\(|app\\.post\\(|app\\.put\\(", name: "Express app routes", count: 0 },
-        { pattern: "Hono|app\\.route\\(|c\\.json\\(", name: "Hono routes", count: 0 },
+        { pattern: "new Hono|from ['\"]hono['\"]", name: "Hono routes", count: 0 },
         { pattern: "FastAPI|@app\\.(get|post|put|delete)", name: "FastAPI endpoints", count: 0 },
         { pattern: "flask\\.route|@app\\.route", name: "Flask routes", count: 0 },
         { pattern: "gin\\.Engine|r\\.GET|r\\.POST", name: "Gin routes", count: 0 },
@@ -377,7 +398,7 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // ========================================
     const schemaPatterns = [
         { pattern: "z\\.object|z\\.string|z\\.number", name: "Zod", usage: "Use Zod schemas for validation", count: 0 },
-        { pattern: "BaseModel|Field\\(", name: "Pydantic", usage: "Use Pydantic BaseModel for data classes", count: 0 },
+        { pattern: "class\\s+\\w+\\(BaseModel\\)|from pydantic", name: "Pydantic", usage: "Use Pydantic BaseModel for data classes", count: 0 },
         { pattern: "Joi\\.object|Joi\\.string", name: "Joi", usage: "Use Joi schemas for validation", count: 0 },
         { pattern: "yup\\.object|yup\\.string", name: "Yup", usage: "Use Yup schemas for validation", count: 0 },
         { pattern: "class.*Serializer.*:|serializers\\.Serializer", name: "Django serializers", usage: "Use Django REST serializers for API data", count: 0 },
@@ -433,7 +454,7 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 5. TESTING PATTERNS
     // ========================================
     const testPatterns = [
-        { pattern: "describe\\(|it\\(|test\\(", name: "Jest/Vitest", count: 0 },
+        { pattern: "describe\\(|it\\(|test\\(", name: "_generic_test", count: 0 },
         { pattern: "def test_|class Test|pytest", name: "pytest", count: 0 },
         { pattern: "func Test.*\\(t \\*testing\\.T\\)", name: "Go testing", count: 0 },
         { pattern: "expect\\(.*\\)\\.to", name: "Chai/expect", count: 0 },
@@ -466,7 +487,46 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     }
     const dominantTest = testPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
     if (dominantTest.length > 0) {
-        const primary = dominantTest[0];
+        let primary = dominantTest[0];
+        // Disambiguate generic test pattern by checking package.json devDependencies
+        if (primary.name === "_generic_test") {
+            let pkgContent = allContents.get("package.json") || "";
+            if (!pkgContent) {
+                const pkgPath = safePath(dir, "package.json");
+                if (pkgPath) {
+                    try {
+                        pkgContent = fs.readFileSync(pkgPath, "utf-8");
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            if (pkgContent.includes('"vitest"')) {
+                primary = { ...primary, name: "Vitest" };
+            }
+            else if (pkgContent.includes('"jest"') || pkgContent.includes('"@jest/')) {
+                primary = { ...primary, name: "Jest" };
+            }
+            else if (pkgContent.includes('"mocha"')) {
+                primary = { ...primary, name: "Mocha" };
+            }
+            else if (pkgContent.includes('"jasmine"')) {
+                primary = { ...primary, name: "Jasmine" };
+            }
+            else {
+                // Check for Deno (deno.json/deno.jsonc) or Bun (bun.lockb)
+                const hasDeno = files.some(f => f === "deno.json" || f === "deno.jsonc" || f === "deno.lock");
+                const hasBun = files.some(f => f === "bun.lockb" || f === "bunfig.toml");
+                if (hasDeno) {
+                    primary = { ...primary, name: "Deno test" };
+                }
+                else if (hasBun) {
+                    primary = { ...primary, name: "Bun test" };
+                }
+                else {
+                    primary = { ...primary, name: "Jest" }; // default for JS/TS projects
+                }
+            }
+        }
         // Also detect common test utilities/helpers
         const testHelperFiles = files.filter((f) => (f.includes("test-utils") || f.includes("testUtils") || f.includes("fixtures") || f.includes("helpers")) &&
             (f.includes("test") || f.includes("spec")));
@@ -527,9 +587,9 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 7. STYLING CONVENTIONS
     // ========================================
     const stylePatterns = [
-        { pattern: "className=|class=.*tw-", name: "Tailwind CSS", desc: "Styling uses Tailwind CSS utility classes", count: 0 },
-        { pattern: "styled\\.|styled\\(|css`", name: "styled-components/Emotion", desc: "Styling uses CSS-in-JS (styled-components or Emotion)", count: 0 },
-        { pattern: "styles\\.\\w+|from.*\\.module\\.(css|scss)", name: "CSS Modules", desc: "Styling uses CSS Modules (*.module.css)", count: 0 },
+        { pattern: "class=.*tw-|className=[\"'](?:flex |grid |p-|m-|text-|bg-|border-|rounded-|shadow-|w-|h-)", name: "Tailwind CSS", desc: "Styling uses Tailwind CSS utility classes", count: 0 },
+        { pattern: "from ['\"]styled-components|from ['\"]@emotion|styled\\.|styled\\(", name: "styled-components/Emotion", desc: "Styling uses CSS-in-JS (styled-components or Emotion)", count: 0 },
+        { pattern: "from.*\\.module\\.(css|scss)", name: "CSS Modules", desc: "Styling uses CSS Modules (*.module.css)", count: 0 },
     ];
     for (const [f, content] of allContents) {
         for (const p of stylePatterns) {
@@ -645,13 +705,15 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     if (dominantRouter.length > 0) {
         const routeDirs = files
             .filter((f) => (f.includes("routes") || f.includes("routers") || f.includes("api/") || f.includes("app/api/")) &&
-            !f.includes("node_modules") && !f.includes(".test.") &&
+            !f.includes("node_modules") && !f.includes(".test.") && !f.includes(".spec.") &&
+            !f.includes("test/") && !f.includes("tests/") && !f.includes("__test") &&
+            !f.includes("fixture") && !f.includes("mock") &&
             (f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".py") || f.endsWith(".go")))
             .map((f) => {
             const parts = f.split("/");
-            // Get the directory containing route files
             return parts.slice(0, -1).join("/");
         })
+            .filter((v) => v && v !== "." && v.length > 0) // filter empty/root paths
             .filter((v, i, a) => a.indexOf(v) === i)
             .slice(0, 3);
         if (routeDirs.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcebook",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
   "type": "module",
   "bin": {
@@ -41,14 +41,15 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.4.0",
     "commander": "^13.0.0",
-    "glob": "^11.0.0",
-    "chalk": "^5.4.0"
+    "glob": "^11.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "vitest": "^3.0.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   }
 }