sourcebook 0.3.0 → 0.5.0

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");
+}