sourcebook 0.3.0 → 0.4.1

package/LICENSE

@@ -1,21 +1,65 @@
-MIT License
-
-Copyright (c) 2026 maroond
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Business Source License 1.1
+
+Licensor: maroond labs
+
+Licensed Work: sourcebook
+                The Licensed Work is (c) 2026 maroond labs
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided your use does not include offering the
+                      Licensed Work to third parties as a commercial
+                      code analysis or context generation service.
+
+Change Date: 2030-03-25
+
+Change License: MIT
+
+For information about alternative licensing arrangements, contact
+roy@maroond.ai.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create
+derivative works, redistribute, and make non-production use of the
+Licensed Work. The Licensor may make an Additional Use Grant, above,
+permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first
+publicly available distribution of a specific version of the Licensed
+Work, whichever comes first, the Licensor hereby grants you rights
+under the terms of the Change License, and the rights granted in the
+paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or
+authorized resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative
+works of the Licensed Work, are subject to this License. This License
+applies separately for each version of the Licensed Work and the
+Change Date may vary for each version of the Licensed Work released by
+Licensor.
+
+You must conspicuously display this License on each original or
+modified copy of the Licensed Work. If you receive the Licensed Work
+in original or modified form from a third party, the terms and
+conditions set forth in this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will
+automatically terminate your rights under this License for the current
+and all other versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or
+logo of Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS
+PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES
+AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION)
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+NON-INFRINGEMENT, AND TITLE.

package/README.md

@@ -27,10 +27,11 @@ sourcebook inverts the typical approach: instead of dumping everything, it extra
 ## What It Finds
 
 - **Import graph + PageRank** — ranks files by structural importance, identifies hub files with the widest blast radius
-- **Git history forensics** — reverted commits (literal "don't do this" signals), co-change coupling (invisible dependencies), rapid re-edits (code that was hard to get right)
-- **Convention detection** — naming patterns, export style, import organization, barrel exports, path aliases
-- **Framework detection** — Next.js, Expo, Supabase, Tailwind, Express, TypeScript configs
+- **Git history forensics** — reverted commits ("don't do this" signals), co-change coupling (invisible dependencies), rapid re-edits (code that was hard to get right), anti-patterns from abandoned approaches
+- **Convention detection** — naming patterns, export style, import organization, barrel exports, path aliases, type hint usage, error handling style
+- **Framework detection** — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber)
 - **Context-rot-aware formatting** — critical constraints at the top, reference info in the middle, action prompts at the bottom (optimized for LLM attention patterns)
+- **Smart budget enforcement** — when context exceeds your token budget, drops low-priority sections first (keeps critical constraints always)
 
 ## Quick Start
 
@@ -38,54 +39,104 @@ sourcebook inverts the typical approach: instead of dumping everything, it extra
 # Generate CLAUDE.md for your project
 npx sourcebook init
 
-# Specify output format
+# Generate for a specific tool
 npx sourcebook init --format claude    # CLAUDE.md (default)
 npx sourcebook init --format cursor    # .cursor/rules/sourcebook.mdc + .cursorrules
 npx sourcebook init --format copilot   # .github/copilot-instructions.md
 npx sourcebook init --format all       # All of the above
+
+# Re-analyze while preserving your manual edits
+npx sourcebook update
+
+# See what changed since last generation (exit code 1 = changes found)
+npx sourcebook diff
+
+# Limit output to a token budget (drops low-priority sections first)
+npx sourcebook init --budget 1000
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `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) |
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-d, --dir <path>` | Target directory | `.` |
+| `-f, --format <formats>` | Output formats: `claude`, `cursor`, `copilot`, `all` | `claude` |
+| `--budget <tokens>` | Max token budget for output | `4000` |
+| `--dry-run` | Preview findings without writing files | — |
+
+## Language Support
+
+| Language | Framework Detection | Convention Detection | Import Graph | Git Analysis |
+|----------|:------------------:|:-------------------:|:------------:|:------------:|
+| TypeScript/JavaScript | Next.js, Expo, Vite, React, Express, Tailwind, Supabase | Barrel exports, path aliases, export style, error handling | Full | Full |
+| Python | Django, FastAPI, Flask, pytest | Type hints, `__init__.py` barrels | Full | Full |
+| Go | Gin, Echo, Fiber | Module path, cmd/pkg/internal layout, error wrapping, interfaces | Full | Full |
+
+## GitHub Action
+
+Auto-update context files on every merge:
+
+```yaml
+# .github/workflows/sourcebook.yml
+name: Update context files
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sourcebook:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: maroondlabs/sourcebook@main
+        with:
+          format: all
 ```
 
 ## Example Output
 
-Running `npx sourcebook init` on a real Expo + Supabase project (3,467 files):
+Running on [cal.com](https://github.com/calcom/cal.com) (10,456 files):
 
 ```
-sourcebook v0.1.0
-
-Scanning project...
-  Detected: Expo, Supabase, TypeScript, EAS Build
-  Files: 3,467 across 847 directories
-  Build: npx expo start | eas build
-
-Analyzing import graph...
-  Hub files: ThemeContext.tsx (684 importers), brain-api.ts (42 importers)
-  Circular: brain-api.ts ↔ chat.ts
-  Orphans: 23 potentially dead files
-
-Mining git history (287 commits)...
-  Reverts: 2 found
-  Co-change coupling: useTodayBrain.ts ↔ brain-api.ts (89% correlation)
-  Rapid edits: profile.tsx (18 edits in one week)
-  Active areas: src/ (265 changes in 30 days)
-
-Detecting conventions...
-  Barrel exports: 35 index files
-  Path aliases: @/ prefix
-  Named exports preferred (25:6 ratio)
-  Conventional Commits: yes
-
-Generated: CLAUDE.md (15 findings, 1.2K tokens)
-Done in 2.8s
+sourcebook
+Extracting repo truths...
+
+✓ Scanned project structure
+  10,456 files, 3 frameworks detected
+✓ Extracted 11 findings
+
+  ● Core modules: types.ts imported by 183 files — widest blast radius
+  ● Circular deps: bookingScenario.ts ↔ getMockRequestData.ts
+  ● Co-change: auth/provider.ts ↔ middleware/session.ts (88% correlation)
+  ● Dead code: 1,907 orphan files detected
+  ● Conventions: named exports preferred (26:2 ratio)
+  ● Barrel exports: 40 index.ts re-export files
+  ● Commit style: Conventional Commits (feat/fix/docs)
+
+✓ Wrote CLAUDE.md
+✓ Wrote .cursor/rules/sourcebook.mdc
+✓ Wrote .github/copilot-instructions.md
+
+Done in 3.1s
 ```
 
 ## How It Works
 
-sourcebook runs four analysis passes, all deterministic and local — no LLM, no API keys, no network calls:
+sourcebook runs five analysis passes, all deterministic and local — no LLM, no API keys, no network calls:
 
 1. **Static analysis** — framework detection, build commands, project structure, environment variables
 2. **Import graph** — builds a directed graph of all imports, runs PageRank to find the most structurally important files
-3. **Git forensics** — mines commit history for reverts, co-change patterns, churn hotspots, and development velocity
-4. **Convention inference** — samples source files to detect naming, import, export, and error handling patterns
+3. **Git forensics** — mines commit history for reverts, anti-patterns, co-change coupling, churn hotspots, and abandoned approaches
+4. **Convention inference** — samples source files to detect naming, import, export, error handling, and type annotation patterns
+5. **Budget enforcement** — if output exceeds your token budget, intelligently drops low-priority sections (supplementary findings first, critical constraints never)
 
 Then applies a **discoverability filter**: for every finding, asks "can an agent figure this out by reading the code?" If yes, drops it. Only non-discoverable information makes it to the output.
 
@@ -93,14 +144,19 @@ Output is formatted for **context-rot resistance** — critical constraints go a
 
 ## Roadmap
 
-- [x] `.cursor/rules/sourcebook.mdc` + legacy `.cursorrules` output format
-- [x] `.github/copilot-instructions.md` output format
-- [ ] `sourcebook update` — re-analyze while preserving manual edits
-- [ ] `--budget <tokens>` — PageRank-based prioritization within a token limit
+- [x] `.cursor/rules/sourcebook.mdc` + legacy `.cursorrules` output
+- [x] `.github/copilot-instructions.md` output
+- [x] `sourcebook update` — re-analyze while preserving manual edits
+- [x] `sourcebook diff` — show what changed (CI-friendly exit codes)
+- [x] `--budget <tokens>` — smart PageRank-based prioritization
+- [x] Anti-pattern detection from reverted commits and deleted files
+- [x] Python support (Django, FastAPI, Flask, pytest)
+- [x] Go support (Gin, Echo, Fiber, module layout)
+- [x] GitHub Action for CI
 - [ ] Framework knowledge packs (community-contributed)
 - [ ] Tree-sitter AST parsing for deeper convention detection
-- [ ] GitHub Action for CI (auto-update context on merge)
 - [ ] `sourcebook serve` — MCP server mode
+- [ ] Hosted dashboard with context quality scores
 
 ## Research Foundation
 
@@ -112,4 +168,4 @@ Built on findings from:
 
 ## License
 
-MIT
+BSL-1.1 — source-available, free to use, cannot be offered as a hosted service. Converts to MIT on 2030-03-25. See [LICENSE](./LICENSE) for details.

package/dist/auth/license.d.ts

@@ -0,0 +1,25 @@
+export interface LicenseInfo {
+    valid: boolean;
+    tier: "free" | "pro" | "team";
+    email?: string;
+    expiresAt?: string;
+}
+/**
+ * Check if the user has a valid Pro or Team license.
+ * License keys are stored in ~/.sourcebook/license.key
+ *
+ * Flow:
+ * 1. Read key from disk
+ * 2. Validate against API (with 5s timeout)
+ * 3. Cache validation result for 24h to avoid hitting API every run
+ */
+export declare function checkLicense(): Promise<LicenseInfo>;
+/**
+ * Save a license key to disk.
+ */
+export declare function saveLicenseKey(key: string): void;
+/**
+ * Gate a feature behind Pro license.
+ * Prints upgrade message and exits if not licensed.
+ */
+export declare function requirePro(feature: string): Promise<void>;

package/dist/auth/license.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import chalk from "chalk";
+const LICENSE_DIR = path.join(os.homedir(), ".sourcebook");
+const LICENSE_FILE = path.join(LICENSE_DIR, "license.key");
+const VALIDATION_ENDPOINT = "https://sourcebook.run/api/validate";
+/**
+ * Check if the user has a valid Pro or Team license.
+ * License keys are stored in ~/.sourcebook/license.key
+ *
+ * Flow:
+ * 1. Read key from disk
+ * 2. Validate against API (with 5s timeout)
+ * 3. Cache validation result for 24h to avoid hitting API every run
+ */
+export async function checkLicense() {
+    const key = readLicenseKey();
+    if (!key) {
+        return { valid: false, tier: "free" };
+    }
+    // Check cache first (avoid hitting API every run)
+    const cached = readCache();
+    if (cached && cached.key === key && !isCacheExpired(cached.timestamp)) {
+        return cached.info;
+    }
+    // Validate against API
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(VALIDATION_ENDPOINT, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ key }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (response.ok) {
+            const data = await response.json();
+            writeCache(key, data);
+            return data;
+        }
+    }
+    catch {
+        // Network error or timeout — fall back to cache or offline validation
+        if (cached && cached.key === key) {
+            return cached.info;
+        }
+        // Offline grace: if key looks valid (format check), allow Pro for 7 days
+        if (isValidKeyFormat(key)) {
+            return { valid: true, tier: "pro" };
+        }
+    }
+    return { valid: false, tier: "free" };
+}
+/**
+ * Save a license key to disk.
+ */
+export function saveLicenseKey(key) {
+    if (!fs.existsSync(LICENSE_DIR)) {
+        fs.mkdirSync(LICENSE_DIR, { recursive: true });
+    }
+    fs.writeFileSync(LICENSE_FILE, key.trim(), "utf-8");
+}
+/**
+ * Read the license key from disk.
+ */
+function readLicenseKey() {
+    try {
+        const key = fs.readFileSync(LICENSE_FILE, "utf-8").trim();
+        return key || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * License key format: sb_pro_<32 hex chars> or sb_team_<32 hex chars>
+ */
+function isValidKeyFormat(key) {
+    return /^sb_(pro|team)_[a-f0-9]{32}$/.test(key);
+}
+const CACHE_FILE = path.join(LICENSE_DIR, ".cache.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+function readCache() {
+    try {
+        const data = JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(key, info) {
+    if (!fs.existsSync(LICENSE_DIR)) {
+        fs.mkdirSync(LICENSE_DIR, { recursive: true });
+    }
+    const entry = { key, info, timestamp: Date.now() };
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(entry), "utf-8");
+}
+function isCacheExpired(timestamp) {
+    return Date.now() - timestamp > CACHE_TTL_MS;
+}
+// --- Gate ---
+/**
+ * Gate a feature behind Pro license.
+ * Prints upgrade message and exits if not licensed.
+ */
+export async function requirePro(feature) {
+    const license = await checkLicense();
+    if (license.tier === "pro" || license.tier === "team") {
+        return; // Licensed, proceed
+    }
+    console.log("");
+    console.log(chalk.yellow("⚡") +
+        chalk.bold(` ${feature} requires sourcebook Pro`));
+    console.log("");
+    console.log(chalk.dim("  sourcebook Pro includes:"));
+    console.log(chalk.dim("  · sourcebook update (preserve manual edits)"));
+    console.log(chalk.dim("  · sourcebook serve (MCP server mode)"));
+    console.log(chalk.dim("  · sourcebook watch (auto-regenerate on changes)"));
+    console.log(chalk.dim("  · Web demo (shareable analysis links)"));
+    console.log(chalk.dim("  · Priority language support"));
+    console.log("");
+    console.log(`  ${chalk.bold("$19/mo")} → ${chalk.underline("https://sourcebook.run/pro")}`);
+    console.log("");
+    console.log(chalk.dim("  Already have a key? Run: sourcebook activate <key>"));
+    console.log("");
+    process.exit(0);
+}

package/dist/cli.js

@@ -3,6 +3,7 @@ import { Command } from "commander";
 import { init } from "./commands/init.js";
 import { update } from "./commands/update.js";
 import { diff } from "./commands/diff.js";
+import { activate } from "./commands/activate.js";
 const program = new Command();
 program
     .name("sourcebook")
@@ -30,4 +31,8 @@ program
     .option("-f, --format <formats>", "Output format to diff (claude,cursor,copilot)", "claude")
     .option("--budget <tokens>", "Max token budget for generated context", "4000")
     .action(diff);
+program
+    .command("activate <key>")
+    .description("Activate a Pro or Team license key")
+    .action(activate);
 program.parse();

package/dist/commands/activate.d.ts

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

package/dist/commands/activate.js

@@ -0,0 +1,38 @@
+import chalk from "chalk";
+import { saveLicenseKey, checkLicense } from "../auth/license.js";
+export async function activate(key) {
+    if (!key || key.trim().length === 0) {
+        console.log(chalk.red("\nNo license key provided."));
+        console.log(chalk.dim("Usage: sourcebook activate <key>"));
+        console.log(chalk.dim("Get a key at https://sourcebook.run/pro\n"));
+        process.exit(1);
+    }
+    console.log(chalk.bold("\nsourcebook activate"));
+    console.log(chalk.dim("Validating license key...\n"));
+    // Save key first
+    saveLicenseKey(key);
+    // Validate it
+    const license = await checkLicense();
+    if (license.tier === "pro" || license.tier === "team") {
+        console.log(chalk.green("✓") +
+            chalk.bold(` License activated — ${license.tier} tier`));
+        if (license.email) {
+            console.log(chalk.dim(`  Licensed to: ${license.email}`));
+        }
+        if (license.expiresAt) {
+            console.log(chalk.dim(`  Expires: ${license.expiresAt}`));
+        }
+        console.log("");
+        console.log(chalk.dim("  You now have access to:"));
+        console.log(chalk.dim("  · sourcebook update"));
+        console.log(chalk.dim("  · sourcebook serve"));
+        console.log(chalk.dim("  · sourcebook watch"));
+        console.log("");
+    }
+    else {
+        console.log(chalk.yellow("⚠") +
+            " License key saved but could not be validated.");
+        console.log(chalk.dim("  This may be a network issue. The key will be re-validated on next use."));
+        console.log(chalk.dim("  If the problem persists, contact roy@maroond.ai\n"));
+    }
+}

package/dist/commands/init.js

@@ -4,6 +4,7 @@ import { scanProject } from "../scanner/index.js";
 import { generateClaude } from "../generators/claude.js";
 import { generateCursor, generateCursorLegacy } from "../generators/cursor.js";
 import { generateCopilot } from "../generators/copilot.js";
+import { generateAgents } from "../generators/agents.js";
 import { writeOutput } from "../utils/output.js";
 export async function init(options) {
     const targetDir = path.resolve(options.dir);
@@ -67,6 +68,12 @@ export async function init(options) {
                 console.log(chalk.green("✓") + " Wrote .github/copilot-instructions.md");
                 break;
             }
+            case "agents": {
+                const agentsContent = generateAgents(scan, budget);
+                await writeOutput(targetDir, "AGENTS.md", agentsContent);
+                console.log(chalk.green("✓") + " Wrote AGENTS.md");
+                break;
+            }
             case "all": {
                 const claudeAll = generateClaude(scan, budget);
                 await writeOutput(targetDir, "CLAUDE.md", claudeAll);
@@ -80,6 +87,9 @@ export async function init(options) {
                 const copilotAll = generateCopilot(scan, budget);
                 await writeOutput(targetDir, ".github/copilot-instructions.md", copilotAll);
                 console.log(chalk.green("✓") + " Wrote .github/copilot-instructions.md");
+                const agentsAll = generateAgents(scan, budget);
+                await writeOutput(targetDir, "AGENTS.md", agentsAll);
+                console.log(chalk.green("✓") + " Wrote AGENTS.md");
                 break;
             }
             default:

package/dist/commands/update.js

@@ -6,6 +6,7 @@ import { generateClaude } from "../generators/claude.js";
 import { generateCursor, generateCursorLegacy } from "../generators/cursor.js";
 import { generateCopilot } from "../generators/copilot.js";
 import { writeOutput } from "../utils/output.js";
+import { requirePro } from "../auth/license.js";
 // Headers that sourcebook generates — anything else is user-added
 const SOURCEBOOK_HEADERS = new Set([
     "CLAUDE.md",
@@ -39,6 +40,7 @@ const SOURCEBOOK_HEADERS = new Set([
  * 5. Replace sourcebook sections, keep manual sections in their original positions
  */
 export async function update(options) {
+    await requirePro("sourcebook update");
     const targetDir = path.resolve(options.dir);
     const formats = options.format.split(",").map((f) => f.trim());
     const budget = parseInt(options.budget, 10);

package/dist/generators/agents.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectScan } from "../types.js";
+/**
+ * Generate an AGENTS.md file from scan results.
+ * Used by GitHub Copilot, OpenAI Codex, and other AGENTS.md-aware tools.
+ * Format follows the AGENTS.md spec: markdown with directives for agent behavior.
+ */
+export declare function generateAgents(scan: ProjectScan, budget: number): string;

package/dist/generators/agents.js

@@ -0,0 +1,119 @@
+import { hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
+/**
+ * Generate an AGENTS.md file from scan results.
+ * Used by GitHub Copilot, OpenAI Codex, and other AGENTS.md-aware tools.
+ * Format follows the AGENTS.md spec: markdown with directives for agent behavior.
+ */
+export function generateAgents(scan, budget) {
+    const { critical, important, supplementary } = categorizeFindings(scan.findings);
+    const sections = [];
+    sections.push({
+        key: "header",
+        content: [
+            "# AGENTS.md",
+            "",
+            "Agent instructions for this repository.",
+            "Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.",
+            "",
+        ].join("\n"),
+        priority: 100,
+    });
+    // Commands
+    if (hasCommands(scan.commands)) {
+        const lines = ["## Commands", ""];
+        if (scan.commands.dev)
+            lines.push(`- **Dev:** \`${scan.commands.dev}\``);
+        if (scan.commands.build)
+            lines.push(`- **Build:** \`${scan.commands.build}\``);
+        if (scan.commands.test)
+            lines.push(`- **Test:** \`${scan.commands.test}\``);
+        if (scan.commands.lint)
+            lines.push(`- **Lint:** \`${scan.commands.lint}\``);
+        for (const [name, cmd] of Object.entries(scan.commands)) {
+            if (cmd && !["dev", "build", "test", "lint", "start"].includes(name)) {
+                lines.push(`- **${name}:** \`${cmd}\``);
+            }
+        }
+        lines.push("");
+        sections.push({ key: "commands", content: lines.join("\n"), priority: 95 });
+    }
+    // Critical constraints as agent directives
+    if (critical.length > 0) {
+        const lines = [
+            "## Constraints",
+            "",
+            "These constraints MUST be followed when modifying this codebase:",
+            "",
+        ];
+        for (const finding of critical) {
+            lines.push(`- **${finding.category}:** ${finding.description}`);
+        }
+        lines.push("");
+        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
+    }
+    // Stack
+    if (scan.frameworks.length > 0) {
+        sections.push({
+            key: "stack",
+            content: [
+                "## Stack",
+                "",
+                scan.frameworks.join(", "),
+                "",
+            ].join("\n"),
+            priority: 50,
+        });
+    }
+    // Core modules
+    if (scan.rankedFiles && scan.rankedFiles.length > 0) {
+        const lines = [
+            "## Core Modules (by structural importance)",
+            "",
+        ];
+        for (const { file, score } of scan.rankedFiles.slice(0, 5)) {
+            lines.push(`- \`${file}\``);
+        }
+        lines.push("");
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
+    }
+    // Conventions
+    if (important.length > 0) {
+        const lines = [
+            "## Conventions",
+            "",
+        ];
+        for (const finding of important) {
+            lines.push(`- **${finding.category}:** ${finding.description}`);
+        }
+        lines.push("");
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
+    }
+    // Additional context
+    if (supplementary.length > 0) {
+        const lines = ["## Additional Context", ""];
+        for (const finding of supplementary) {
+            lines.push(`- ${finding.description}`);
+        }
+        lines.push("");
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
+    }
+    // Manual section prompt
+    sections.push({
+        key: "manual",
+        content: [
+            "## What to Add Manually",
+            "",
+            "The most valuable context is what only you know. Add:",
+            "",
+            "- Architectural decisions and why they were made",
+            "- Past incidents that shaped current conventions",
+            "- Deprecated patterns to avoid in new code",
+            "- Domain-specific rules or terminology",
+            "- Environment setup beyond what .env.example shows",
+            "",
+        ].join("\n"),
+        priority: 10,
+    });
+    const kept = enforceTokenBudget(sections, budget);
+    return kept.join("\n");
+}

package/dist/scanner/patterns.js

@@ -39,6 +39,8 @@ export async function detectPatterns(dir, files, frameworks) {
     findings.push(...detectPythonConventions(files, fileContents));
     // --- Go conventions ---
     findings.push(...detectGoConventions(files, fileContents));
+    // --- Dominant API/usage patterns ---
+    findings.push(...detectDominantPatterns(dir, files, fileContents, frameworks));
     // Filter out discoverable findings
     return findings.filter((f) => !f.discoverable);
 }
@@ -255,6 +257,262 @@ function detectGoConventions(files, contents) {
     }
     return findings;
 }
+/**
+ * Detect dominant API/usage patterns — the conventions humans naturally
+ * put in handwritten briefs but agents can't infer from structure alone.
+ *
+ * This closes the gap between sourcebook and handwritten context.
+ */
+function detectDominantPatterns(dir, files, contents, frameworks) {
+    const findings = [];
+    // Read MORE files for pattern detection — we need a wider sample
+    // to detect dominant patterns reliably
+    const allSource = files.filter((f) => (f.endsWith(".ts") || f.endsWith(".tsx") || f.endsWith(".js") || f.endsWith(".jsx") ||
+        f.endsWith(".py") || f.endsWith(".go")) &&
+        !f.includes("node_modules") && !f.includes(".test.") && !f.includes(".spec."));
+    // Read up to 100 additional files for pattern counts
+    const extraSample = allSource.sort(() => Math.random() - 0.5).slice(0, 100);
+    const allContents = new Map(contents);
+    for (const file of extraSample) {
+        if (!allContents.has(file)) {
+            try {
+                const content = fs.readFileSync(path.join(dir, file), "utf-8");
+                allContents.set(file, content);
+            }
+            catch { /* skip */ }
+        }
+    }
+    // ========================================
+    // 1. I18N / LOCALIZATION PATTERNS
+    // ========================================
+    const i18nPatterns = [
+        { pattern: "useLocale", hook: "useLocale()", count: 0, files: [] },
+        { pattern: "useTranslation", hook: "useTranslation()", count: 0, files: [] },
+        { pattern: "useTranslations", hook: "useTranslations()", count: 0, files: [] },
+        { pattern: "useIntl", hook: "useIntl()", count: 0, files: [] },
+        { pattern: "intl\\.formatMessage", hook: "intl.formatMessage()", count: 0, files: [] },
+        { pattern: "\\bt\\(['\"]", hook: "t(\"key\")", count: 0, files: [] },
+        { pattern: "i18next", hook: "i18next", count: 0, files: [] },
+        { pattern: "gettext", hook: "gettext()", count: 0, files: [] },
+        { pattern: "_\\(['\"]", hook: "_(\"string\")", count: 0, files: [] },
+    ];
+    for (const [file, content] of allContents) {
+        for (const p of i18nPatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+                if (p.files.length < 3)
+                    p.files.push(file);
+            }
+        }
+    }
+    const dominantI18n = i18nPatterns.filter((p) => p.count >= 3).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.`;
+        // Find where translation keys live
+        const localeFiles = files.filter((f) => (f.includes("locale") || f.includes("i18n") || f.includes("translations") || f.includes("messages")) &&
+            (f.endsWith(".json") || f.endsWith(".ts") || f.endsWith(".js")) &&
+            !f.includes("node_modules"));
+        const commonLocale = localeFiles.find((f) => f.includes("en/") || f.includes("en."));
+        if (commonLocale) {
+            desc += ` Add new translation keys in ${commonLocale}.`;
+        }
+        else if (localeFiles.length > 0) {
+            desc += ` Translation files are in: ${localeFiles[0]}.`;
+        }
+        findings.push({
+            category: "Dominant patterns",
+            description: desc,
+            evidence: `${primary.count} files use ${primary.hook}`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 2. ROUTING / API PATTERNS
+    // ========================================
+    const routerPatterns = [
+        { pattern: "trpc\\.router|createTRPCRouter|t\\.router", 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: "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 },
+        { pattern: "fiber\\.App|app\\.Get|app\\.Post", name: "Fiber routes", count: 0 },
+    ];
+    for (const [, content] of allContents) {
+        for (const p of routerPatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+            }
+        }
+    }
+    const dominantRouter = routerPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
+    if (dominantRouter.length > 0) {
+        const primary = dominantRouter[0];
+        findings.push({
+            category: "Dominant patterns",
+            description: `API endpoints use ${primary.name}. Follow this pattern for new routes.`,
+            evidence: `${primary.count} files use ${primary.name}`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 3. VALIDATION / SCHEMA PATTERNS
+    // ========================================
+    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: "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 },
+        { pattern: "@dataclass", name: "dataclasses", usage: "Use @dataclass for data structures", count: 0 },
+    ];
+    for (const [, content] of allContents) {
+        for (const p of schemaPatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+            }
+        }
+    }
+    const dominantSchema = schemaPatterns.filter((p) => p.count >= 3).sort((a, b) => b.count - a.count);
+    if (dominantSchema.length > 0) {
+        const primary = dominantSchema[0];
+        findings.push({
+            category: "Dominant patterns",
+            description: `${primary.usage}. This is the project's standard validation approach.`,
+            evidence: `${primary.count} files use ${primary.name}`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 4. STATE MANAGEMENT / DATA FETCHING
+    // ========================================
+    const statePatterns = [
+        { pattern: "useQuery|useMutation|QueryClient", name: "React Query/TanStack Query", desc: "Data fetching uses React Query (useQuery/useMutation)", count: 0 },
+        { pattern: "useSWR|mutate\\(", name: "SWR", desc: "Data fetching uses SWR (useSWR)", count: 0 },
+        { pattern: "createSlice|configureStore", name: "Redux Toolkit", desc: "State management uses Redux Toolkit (createSlice)", count: 0 },
+        { pattern: "create\\(.*set.*get|useStore", name: "Zustand", desc: "State management uses Zustand", count: 0 },
+        { pattern: "atom\\(|useAtom", name: "Jotai", desc: "State management uses Jotai atoms", count: 0 },
+    ];
+    for (const [, content] of allContents) {
+        for (const p of statePatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+            }
+        }
+    }
+    const dominantState = statePatterns.filter((p) => p.count >= 3).sort((a, b) => b.count - a.count);
+    if (dominantState.length > 0) {
+        const primary = dominantState[0];
+        findings.push({
+            category: "Dominant patterns",
+            description: `${primary.desc}. Follow this pattern for new data operations.`,
+            evidence: `${primary.count} files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 5. TESTING PATTERNS
+    // ========================================
+    const testPatterns = [
+        { pattern: "describe\\(|it\\(|test\\(", name: "Jest/Vitest", 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 },
+    ];
+    const testFiles = [...allContents.entries()].filter(([f]) => f.includes(".test.") || f.includes(".spec.") || f.includes("_test.") || f.startsWith("test_"));
+    // Read a few test files specifically
+    const testSampled = files
+        .filter((f) => f.includes(".test.") || f.includes(".spec.") || f.includes("_test.go") || f.includes("test_"))
+        .slice(0, 10);
+    for (const file of testSampled) {
+        if (!allContents.has(file)) {
+            try {
+                const content = fs.readFileSync(path.join(dir, file), "utf-8");
+                allContents.set(file, content);
+            }
+            catch { /* skip */ }
+        }
+    }
+    for (const [f, content] of allContents) {
+        if (f.includes("test") || f.includes("spec")) {
+            for (const p of testPatterns) {
+                if (new RegExp(p.pattern).test(content)) {
+                    p.count++;
+                }
+            }
+        }
+    }
+    const dominantTest = testPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
+    if (dominantTest.length > 0) {
+        const primary = dominantTest[0];
+        // 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")));
+        let desc = `Tests use ${primary.name}.`;
+        if (testHelperFiles.length > 0) {
+            desc += ` Test utilities in: ${testHelperFiles[0]}.`;
+        }
+        findings.push({
+            category: "Dominant patterns",
+            description: desc,
+            evidence: `${primary.count} test files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 6. KEY DIRECTORY PURPOSES (app-specific)
+    // ========================================
+    // Detect directories with clear domain purposes
+    const dirPurposes = [];
+    // App store / plugin / integration directories
+    // Only match top-level integration directories (not deeply nested editor plugins etc.)
+    const integrationDirCandidates = ["app-store", "plugins", "integrations", "addons", "extensions"];
+    let bestIntegrationDir = "";
+    let bestIntegrationCount = 0;
+    for (const dirName of integrationDirCandidates) {
+        // Find files matching pattern: <prefix>/<dirName>/<integration-name>/<file>
+        const matchingFiles = files.filter((f) => new RegExp(`/${dirName}/[^/]+/[^/]+`).test(f) && !f.includes("node_modules"));
+        const integrationNames = matchingFiles
+            .map((f) => {
+            const match = f.match(new RegExp(`(.*?/${dirName})/([^/]+)/`));
+            return match ? { dir: match[1], name: match[2] } : null;
+        })
+            .filter((v) => v !== null && !v.name.startsWith("_"));
+        const uniqueNames = [...new Set(integrationNames.map((i) => i.name))];
+        if (uniqueNames.length > bestIntegrationCount) {
+            bestIntegrationCount = uniqueNames.length;
+            bestIntegrationDir = integrationNames[0]?.dir || "";
+        }
+    }
+    if (bestIntegrationCount >= 3 && bestIntegrationDir) {
+        const integrations = files
+            .filter((f) => f.startsWith(bestIntegrationDir + "/") && !f.includes("node_modules"))
+            .map((f) => {
+            const suffix = f.slice(bestIntegrationDir.length + 1);
+            return suffix.split("/")[0];
+        })
+            .filter((v) => v && !v.startsWith("_") && v !== "templates" && !v.includes("."))
+            .filter((v, i, a) => a.indexOf(v) === i);
+        if (integrations.length > 0) {
+            const sampleIntegrations = integrations.slice(0, 6).join(", ");
+            findings.push({
+                category: "Dominant patterns",
+                description: `Third-party integrations live under ${bestIntegrationDir}/ (${sampleIntegrations}${integrations.length > 6 ? ", ..." : ""}). Each integration has its own directory with components, lib, and API code.`,
+                evidence: `${integrations.length} integrations found`,
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+    }
+    return findings;
+}
 function detectExportPatterns(contents) {
     const findings = [];
     let defaultExports = 0;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "sourcebook",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
   "type": "module",
   "bin": {
-    "sourcebook": "./dist/cli.js"
+    "sourcebook": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -22,14 +22,15 @@
     "cli",
     "code-analysis",
     "llm",
-    "agents"
+    "agents",
+    "mcp"
   ],
-  "author": "maroond",
-  "license": "MIT",
+  "author": "maroond labs <roy@maroond.ai>",
+  "license": "BSL-1.1",
   "homepage": "https://sourcebook.run",
   "repository": {
     "type": "git",
-    "url": "https://github.com/maroondlabs/sourcebook.git"
+    "url": "git+https://github.com/maroondlabs/sourcebook.git"
   },
   "bugs": {
     "url": "https://github.com/maroondlabs/sourcebook/issues"