sourcebook 0.4.1 → 0.5.1

package/dist/auth/license.d.ts

@@ -18,6 +18,10 @@ export declare function checkLicense(): Promise<LicenseInfo>;
  * Save a license key to disk.
  */
 export declare function saveLicenseKey(key: string): void;
+/**
+ * Remove the license key from disk.
+ */
+export declare function removeLicenseKey(): void;
 /**
  * Gate a feature behind Pro license.
  * Prints upgrade message and exits if not licensed.

package/dist/auth/license.js

@@ -44,12 +44,13 @@ export async function checkLicense() {
     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" };
+            // Only grant offline access if last validation was within 7 days
+            const OFFLINE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+            if (Date.now() - cached.timestamp <= OFFLINE_GRACE_MS) {
+                return cached.info;
+            }
         }
+        // No valid cached validation within 7 days — deny access
     }
     return { valid: false, tier: "free" };
 }
@@ -58,9 +59,22 @@ export async function checkLicense() {
  */
 export function saveLicenseKey(key) {
     if (!fs.existsSync(LICENSE_DIR)) {
-        fs.mkdirSync(LICENSE_DIR, { recursive: true });
+        fs.mkdirSync(LICENSE_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(LICENSE_FILE, key.trim(), { encoding: "utf-8", mode: 0o600 });
+}
+/**
+ * Remove the license key from disk.
+ */
+export function removeLicenseKey() {
+    try {
+        if (fs.existsSync(LICENSE_FILE)) {
+            fs.unlinkSync(LICENSE_FILE);
+        }
+    }
+    catch {
+        // ignore cleanup errors
     }
-    fs.writeFileSync(LICENSE_FILE, key.trim(), "utf-8");
 }
 /**
  * Read the license key from disk.
@@ -93,10 +107,10 @@ function readCache() {
 }
 function writeCache(key, info) {
     if (!fs.existsSync(LICENSE_DIR)) {
-        fs.mkdirSync(LICENSE_DIR, { recursive: true });
+        fs.mkdirSync(LICENSE_DIR, { recursive: true, mode: 0o700 });
     }
     const entry = { key, info, timestamp: Date.now() };
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(entry), "utf-8");
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(entry), { encoding: "utf-8", mode: 0o600 });
 }
 function isCacheExpired(timestamp) {
     return Date.now() - timestamp > CACHE_TTL_MS;

package/dist/commands/activate.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { saveLicenseKey, checkLicense } from "../auth/license.js";
+import { saveLicenseKey, removeLicenseKey, checkLicense } from "../auth/license.js";
 export async function activate(key) {
     if (!key || key.trim().length === 0) {
         console.log(chalk.red("\nNo license key provided."));
@@ -9,9 +9,9 @@ export async function activate(key) {
     }
     console.log(chalk.bold("\nsourcebook activate"));
     console.log(chalk.dim("Validating license key...\n"));
-    // Save key first
+    // Validate first, only save if valid
+    // Temporarily save so checkLicense can read it, then remove if invalid
     saveLicenseKey(key);
-    // Validate it
     const license = await checkLicense();
     if (license.tier === "pro" || license.tier === "team") {
         console.log(chalk.green("✓") +
@@ -30,9 +30,11 @@ export async function activate(key) {
         console.log("");
     }
     else {
+        // Validation failed — remove the saved key to prevent offline bypass
+        removeLicenseKey();
         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."));
+            " License key could not be validated and was not saved.");
+        console.log(chalk.dim("  This may be a network issue. Please try again when you have an internet connection."));
         console.log(chalk.dim("  If the problem persists, contact roy@maroond.ai\n"));
     }
 }

package/dist/generators/claude.js

@@ -1,4 +1,4 @@
-import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
+import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, buildQuickReference, getModePriorities, } from "./shared.js";
 /**
  * Generate a CLAUDE.md file from scan results.
  *
@@ -10,6 +10,7 @@ import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, }
  */
 export function generateClaude(scan, budget) {
     const { critical, important, supplementary } = categorizeFindings(scan.findings);
+    const priorities = getModePriorities(scan.repoMode);
     const sections = [];
     // ============================================
     // BEGINNING: Most critical info goes here
@@ -23,7 +24,12 @@ export function generateClaude(scan, budget) {
         "",
     ].join("\n");
     sections.push({ key: "header", content: header, priority: 100 });
-    // Commands first -- most immediately actionable
+    // Quick Reference — the "30-second handoff" (highest priority in app mode)
+    const quickRef = buildQuickReference(scan.findings);
+    if (quickRef) {
+        sections.push({ key: "quick_reference", content: quickRef, priority: priorities.quick_reference });
+    }
+    // Commands — most immediately actionable
     if (hasCommands(scan.commands)) {
         const lines = ["## Commands", ""];
         if (scan.commands.dev)
@@ -49,7 +55,7 @@ export function generateClaude(scan, budget) {
             lines.push(`- **${finding.category}:** ${finding.description}`);
         }
         lines.push("");
-        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
+        sections.push({ key: "critical", content: lines.join("\n"), priority: priorities.critical });
     }
     // ============================================
     // MIDDLE: Less critical but useful info
@@ -58,7 +64,7 @@ export function generateClaude(scan, budget) {
     // Stack (brief)
     if (scan.frameworks.length > 0) {
         const content = ["## Stack", "", scan.frameworks.join(", "), ""].join("\n");
-        sections.push({ key: "stack", content, priority: 50 });
+        sections.push({ key: "stack", content, priority: priorities.stack });
     }
     // Key directories (only non-obvious ones)
     if (Object.keys(scan.structure.directories).length > 0) {
@@ -69,7 +75,7 @@ export function generateClaude(scan, budget) {
                 lines.push(`- \`${dir}/\` — ${purpose}`);
             }
             lines.push("");
-            sections.push({ key: "structure", content: lines.join("\n"), priority: 40 });
+            sections.push({ key: "structure", content: lines.join("\n"), priority: priorities.structure });
         }
     }
     // Core modules (from PageRank)
@@ -80,7 +86,7 @@ export function generateClaude(scan, budget) {
             lines.push(`- \`${file}\``);
         }
         lines.push("");
-        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: priorities.core_modules });
     }
     // Important findings (high confidence, non-critical)
     if (important.length > 0) {
@@ -98,7 +104,7 @@ export function generateClaude(scan, budget) {
             }
         }
         lines.push("");
-        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: priorities.conventions });
     }
     // Supplementary findings (medium confidence)
     if (supplementary.length > 0) {
@@ -116,7 +122,7 @@ export function generateClaude(scan, budget) {
             }
         }
         lines.push("");
-        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: priorities.supplementary });
     }
     // ============================================
     // END: Important reminders go here

package/dist/generators/shared.d.ts

@@ -27,6 +27,18 @@ export declare function categorizeFindings(findings: Finding[]): {
  * 6. Supplementary findings (drop first)
  * 7. Footer/manual section (always keep — end of context = high retention)
  */
+/**
+ * Build a Quick Reference section from dominant pattern findings.
+ * This is the "30-second senior engineer handoff" — the single most
+ * actionable section in the output.
+ */
+export declare function buildQuickReference(findings: Finding[]): string | null;
+/**
+ * Get priority adjustments based on repo mode.
+ * App repos: boost dominant patterns, demote structural.
+ * Library repos: boost structural, demote patterns.
+ */
+export declare function getModePriorities(repoMode?: "app" | "library" | "monorepo"): Record<string, number>;
 export declare function enforceTokenBudget(sections: {
     key: string;
     content: string;

package/dist/generators/shared.js

@@ -10,6 +10,7 @@ const CRITICAL_CATEGORIES = new Set([
     "Git history",
     "Commit conventions",
     "Anti-patterns",
+    "Critical constraints",
 ]);
 const CRITICAL_KEYWORDS = [
     "breaking", "blast radius", "deprecated", "don't", "must",
@@ -62,6 +63,113 @@ export function categorizeFindings(findings) {
  * 6. Supplementary findings (drop first)
  * 7. Footer/manual section (always keep — end of context = high retention)
  */
+/**
+ * Build a Quick Reference section from dominant pattern findings.
+ * This is the "30-second senior engineer handoff" — the single most
+ * actionable section in the output.
+ */
+export function buildQuickReference(findings) {
+    const patterns = findings.filter((f) => f.category === "Dominant patterns");
+    if (patterns.length < 2)
+        return null;
+    const lines = ["## Quick Reference", ""];
+    for (const p of patterns) {
+        // Extract a short label from the description
+        const desc = p.description;
+        let label = "";
+        let value = desc;
+        if (desc.includes("internationalization") || desc.includes("i18n") || desc.includes("translation")) {
+            label = "i18n";
+        }
+        else if (desc.includes("route") || desc.includes("endpoint") || desc.includes("API")) {
+            label = "routing";
+        }
+        else if (desc.includes("validation") || desc.includes("schema") || desc.includes("Zod") || desc.includes("Pydantic")) {
+            label = "validation";
+        }
+        else if ((desc.includes("auth") || desc.includes("Auth") || desc.includes("session")) && !desc.includes("integration")) {
+            label = "auth";
+        }
+        else if (desc.includes("Test") || desc.includes("test")) {
+            label = "testing";
+        }
+        else if (desc.includes("Tailwind") || desc.includes("styled") || desc.includes("CSS")) {
+            label = "styling";
+        }
+        else if (desc.includes("database") || desc.includes("Database") || desc.includes("Prisma") || desc.includes("ORM")) {
+            label = "database";
+        }
+        else if (desc.includes("fetching") || desc.includes("Query") || desc.includes("SWR")) {
+            label = "data fetching";
+        }
+        else if (desc.includes("Route definitions") || desc.includes("Add new endpoints")) {
+            label = "routes";
+        }
+        else if (desc.includes("integration") || desc.includes("Third-party")) {
+            label = "integrations";
+        }
+        else if (desc.includes("components") || desc.includes("UI")) {
+            label = "components";
+        }
+        else if (desc.includes("Generated") || desc.includes("generated") || desc.includes("DO NOT")) {
+            label = "generated";
+        }
+        else {
+            continue; // Skip findings we can't label cleanly
+        }
+        // Compress the description to a short actionable line
+        const short = desc
+            .replace(/\. Follow this pattern.*$/, "")
+            .replace(/\. This is the project's standard.*$/, "")
+            .replace(/\. Each integration has.*$/, "");
+        lines.push(`- **${label}:** ${short}`);
+    }
+    if (lines.length <= 2)
+        return null; // Nothing useful
+    // Deduplicate by label — keep only first occurrence of each
+    const seen = new Set();
+    const deduped = [lines[0], lines[1]]; // Keep header
+    for (let i = 2; i < lines.length; i++) {
+        const labelMatch = lines[i].match(/^\- \*\*(\w[\w\s]*)\:\*\*/);
+        if (labelMatch) {
+            const lbl = labelMatch[1];
+            if (seen.has(lbl))
+                continue;
+            seen.add(lbl);
+        }
+        deduped.push(lines[i]);
+    }
+    deduped.push("");
+    return deduped.join("\n");
+}
+/**
+ * Get priority adjustments based on repo mode.
+ * App repos: boost dominant patterns, demote structural.
+ * Library repos: boost structural, demote patterns.
+ */
+export function getModePriorities(repoMode) {
+    if (repoMode === "library") {
+        return {
+            quick_reference: 85,
+            critical: 92,
+            core_modules: 90,
+            conventions: 80,
+            stack: 50,
+            structure: 40,
+            supplementary: 25,
+        };
+    }
+    // Default: app mode (boost patterns, Quick Reference highest)
+    return {
+        quick_reference: 96,
+        critical: 92,
+        core_modules: 50,
+        conventions: 85,
+        stack: 45,
+        structure: 60,
+        supplementary: 20,
+    };
+}
 export function enforceTokenBudget(sections, budget) {
     // Sort by priority descending (highest priority = keep)
     const sorted = [...sections].sort((a, b) => b.priority - a.priority);

package/dist/scanner/build.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 export async function detectBuildCommands(dir) {
     const commands = {};
     // Check package.json scripts

package/dist/scanner/frameworks.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 export async function detectFrameworks(dir, files) {
     const detected = [];
     // Read all package.json files (root + workspaces/sub-packages)
@@ -8,7 +15,9 @@ export async function detectFrameworks(dir, files) {
         pkgFiles.push("package.json");
     const allDeps = {};
     for (const pkgFile of pkgFiles) {
-        const pkgPath = path.join(dir, pkgFile);
+        const pkgPath = safePath(dir, pkgFile);
+        if (!pkgPath)
+            continue;
         if (fs.existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
@@ -44,29 +53,31 @@ export async function detectFrameworks(dir, files) {
         // Check for next.config
         const nextConfig = files.find((f) => /^next\.config\.(js|mjs|ts)$/.test(f));
         if (nextConfig) {
-            try {
-                const configContent = fs.readFileSync(path.join(dir, nextConfig), "utf-8");
-                if (configContent.includes("output:") && configContent.includes("standalone")) {
-                    findings.push({
-                        category: "Next.js deployment",
-                        description: "Standalone output mode is enabled. Build produces a self-contained server in .next/standalone.",
-                        confidence: "high",
-                        discoverable: false,
-                    });
+            const safeNextConfig = safePath(dir, nextConfig);
+            if (safeNextConfig)
+                try {
+                    const configContent = fs.readFileSync(safeNextConfig, "utf-8");
+                    if (configContent.includes("output:") && configContent.includes("standalone")) {
+                        findings.push({
+                            category: "Next.js deployment",
+                            description: "Standalone output mode is enabled. Build produces a self-contained server in .next/standalone.",
+                            confidence: "high",
+                            discoverable: false,
+                        });
+                    }
+                    if (configContent.includes("images") && configContent.includes("remotePatterns")) {
+                        findings.push({
+                            category: "Next.js images",
+                            description: "Remote image patterns are configured. New image domains must be added to next.config before use.",
+                            rationale: "Agents will try to use next/image with arbitrary URLs and get 400 errors without this config.",
+                            confidence: "high",
+                            discoverable: false,
+                        });
+                    }
                 }
-                if (configContent.includes("images") && configContent.includes("remotePatterns")) {
-                    findings.push({
-                        category: "Next.js images",
-                        description: "Remote image patterns are configured. New image domains must be added to next.config before use.",
-                        rationale: "Agents will try to use next/image with arbitrary URLs and get 400 errors without this config.",
-                        confidence: "high",
-                        discoverable: false,
-                    });
+                catch {
+                    // can't read config
                 }
-            }
-            catch {
-                // can't read config
-            }
         }
         detected.push({
             name: "Next.js",
@@ -157,7 +168,10 @@ export async function detectFrameworks(dir, files) {
         if (hasTwConfig) {
             try {
                 const configPath = files.find((f) => /^tailwind\.config\.(js|ts|mjs|cjs)$/.test(f));
-                const content = fs.readFileSync(path.join(dir, configPath), "utf-8");
+                const safeConfigPath = safePath(dir, configPath);
+                if (!safeConfigPath)
+                    throw new Error("path escape");
+                const content = fs.readFileSync(safeConfigPath, "utf-8");
                 if (content.includes("extend") && content.includes("colors")) {
                     findings.push({
                         category: "Tailwind",

package/dist/scanner/git.js

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 /**
  * Mine git history for non-obvious context:
@@ -33,7 +33,7 @@ export async function analyzeGitHistory(dir) {
 }
 function isGitRepo(dir) {
     try {
-        execSync("git rev-parse --is-inside-work-tree", {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
             cwd: dir,
             stdio: "pipe",
         });
@@ -45,7 +45,7 @@ function isGitRepo(dir) {
 }
 function git(dir, args) {
     try {
-        return execSync(`git ${args}`, {
+        return execFileSync("git", args, {
             cwd: dir,
             stdio: "pipe",
             maxBuffer: 10 * 1024 * 1024,
@@ -60,7 +60,7 @@ function git(dir, args) {
  */
 function detectRevertedPatterns(dir, revertedPatterns) {
     const findings = [];
-    const revertLog = git(dir, 'log --grep="^Revert" --oneline --since="1 year ago" -50');
+    const revertLog = git(dir, ["log", "--grep=^Revert", "--oneline", "--since=1 year ago", "-50"]);
     if (!revertLog.trim())
         return findings;
     const reverts = revertLog.trim().split("\n").filter(Boolean);
@@ -94,7 +94,7 @@ function detectRevertedPatterns(dir, revertedPatterns) {
 function detectAntiPatterns(dir) {
     const findings = [];
     // Extract detailed info from reverted commits
-    const revertLog = git(dir, 'log --grep="^Revert" --format="%s" --since="1 year ago" -20');
+    const revertLog = git(dir, ["log", "--grep=^Revert", "--format=%s", "--since=1 year ago", "-20"]);
     if (revertLog.trim()) {
         const antiPatterns = [];
         for (const line of revertLog.trim().split("\n").filter(Boolean)) {
@@ -116,13 +116,13 @@ function detectAntiPatterns(dir) {
         }
     }
     // Detect files deleted in bulk (abandoned features/approaches)
-    const deletedLog = git(dir, 'log --diff-filter=D --name-only --pretty=format:"COMMIT %s" --since="6 months ago" -50');
+    const deletedLog = git(dir, ["log", "--diff-filter=D", "--name-only", "--pretty=format:COMMIT %s", "--since=6 months ago", "-50"]);
     if (deletedLog.trim()) {
         const deletionBatches = [];
         let currentMessage = "";
         let currentFiles = [];
         for (const line of deletedLog.split("\n")) {
-            const commitMatch = line.match(/^"?COMMIT (.+)"?$/);
+            const commitMatch = line.match(/^COMMIT (.+)$/);
             if (commitMatch) {
                 if (currentFiles.length >= 3) {
                     deletionBatches.push({ message: currentMessage, files: currentFiles });
@@ -159,7 +159,7 @@ function detectAntiPatterns(dir) {
 function detectActiveAreas(dir, activeAreas) {
     const findings = [];
     // Get files changed in the last 30 days, count changes per directory
-    const recentChanges = git(dir, 'log --since="30 days ago" --name-only --pretty=format: --diff-filter=AMRC');
+    const recentChanges = git(dir, ["log", "--since=30 days ago", "--name-only", "--pretty=format:", "--diff-filter=AMRC"]);
     if (!recentChanges.trim())
         return findings;
     const dirCounts = new Map();
@@ -198,14 +198,14 @@ function detectActiveAreas(dir, activeAreas) {
 function detectCoChangeCoupling(dir, clusters) {
     const findings = [];
     // Get the last 200 commits with their changed files
-    const log = git(dir, 'log --name-only --pretty=format:"COMMIT" --since="6 months ago" -200');
+    const log = git(dir, ["log", "--name-only", "--pretty=format:COMMIT", "--since=6 months ago", "-200"]);
     if (!log.trim())
         return findings;
     // Parse commits into file groups
     const commits = [];
     let current = [];
     for (const line of log.split("\n")) {
-        if (line.trim() === '"COMMIT"' || line.trim() === "COMMIT") {
+        if (line.trim() === "COMMIT") {
             if (current.length > 0)
                 commits.push(current);
             current = [];
@@ -293,7 +293,7 @@ function detectCoChangeCoupling(dir, clusters) {
 function detectRapidReEdits(dir) {
     const findings = [];
     // Get files with high commit frequency in short windows
-    const log = git(dir, 'log --format="%H %aI" --name-only --since="3 months ago" -300');
+    const log = git(dir, ["log", "--format=%H %aI", "--name-only", "--since=3 months ago", "-300"]);
     if (!log.trim())
         return findings;
     // Track edits per file with timestamps
@@ -354,7 +354,7 @@ function detectRapidReEdits(dir) {
  */
 function detectCommitPatterns(dir) {
     const findings = [];
-    const log = git(dir, 'log --oneline --since="6 months ago" -200');
+    const log = git(dir, ["log", "--oneline", "--since=6 months ago", "-200"]);
     if (!log.trim())
         return findings;
     const messages = log.trim().split("\n").filter(Boolean);

package/dist/scanner/graph.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 /**
  * Build an import/dependency graph and run PageRank to identify
  * the most structurally important files. Conventions found in
@@ -16,7 +23,9 @@ export async function analyzeImportGraph(dir, files) {
     const edges = [];
     const fileSet = new Set(sourceFiles);
     for (const file of sourceFiles) {
-        const filePath = path.join(dir, file);
+        const filePath = safePath(dir, file);
+        if (!filePath)
+            continue;
         let content;
         try {
             content = fs.readFileSync(filePath, "utf-8");

package/dist/scanner/index.js

@@ -28,6 +28,7 @@ export async function scanProject(dir) {
         nodir: true,
         ignore: IGNORE_PATTERNS,
         dot: true,
+        follow: false,
     });
     // Detect languages from file extensions
     const languages = detectLanguages(files);
@@ -51,6 +52,8 @@ export async function scanProject(dir) {
         ...gitAnalysis.findings,
         ...graphAnalysis.findings,
     ];
+    // Detect repo mode for prioritization
+    const repoMode = detectRepoMode(dir, files, frameworks.map((f) => f.name));
     return {
         dir,
         files,
@@ -60,8 +63,29 @@ export async function scanProject(dir) {
         structure,
         findings,
         rankedFiles: graphAnalysis.rankedFiles,
+        repoMode,
     };
 }
+function detectRepoMode(dir, files, frameworks) {
+    // Monorepo detection
+    const hasWorkspaces = files.some((f) => f === "pnpm-workspace.yaml" || f === "lerna.json" || f === "nx.json");
+    if (hasWorkspaces)
+        return "monorepo";
+    // Library detection
+    const hasPublishConfig = files.some((f) => f === "setup.py" || f === "pyproject.toml" || f === "setup.cfg");
+    const hasSrcLib = files.some((f) => f.startsWith("src/lib/") || f.startsWith("lib/"));
+    const hasExportsField = false; // would need to read package.json, but frameworks already detected
+    const isLibraryFramework = frameworks.some((f) => ["FastAPI", "Flask", "Django", "Hono", "Express"].includes(f));
+    // If it has a setup.py/pyproject.toml AND no app/ or pages/ → library
+    const hasAppDirs = files.some((f) => f.startsWith("app/") || f.startsWith("pages/") || f.startsWith("src/app/") || f.startsWith("src/pages/"));
+    const hasComponents = files.some((f) => f.includes("/components/"));
+    if (hasPublishConfig && !hasAppDirs && !hasComponents)
+        return "library";
+    if (hasSrcLib && !hasAppDirs && !hasComponents && !isLibraryFramework)
+        return "library";
+    // Default: app
+    return "app";
+}
 function detectLanguages(files) {
     const extMap = {
         ".ts": "TypeScript",

package/dist/scanner/patterns.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 /**
  * Detect code patterns and conventions that are non-obvious.
  * This is the core intelligence layer -- finding things agents miss.
@@ -17,8 +24,11 @@ export async function detectPatterns(dir, files, frameworks) {
     const sampled = sampleFiles(sourceFiles, 50);
     const fileContents = new Map();
     for (const file of sampled) {
+        const safe = safePath(dir, file);
+        if (!safe)
+            continue;
         try {
-            const content = fs.readFileSync(path.join(dir, file), "utf-8");
+            const content = fs.readFileSync(safe, "utf-8");
             fileContents.set(file, content);
         }
         catch {
@@ -275,8 +285,11 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     const allContents = new Map(contents);
     for (const file of extraSample) {
         if (!allContents.has(file)) {
+            const safe = safePath(dir, file);
+            if (!safe)
+                continue;
             try {
-                const content = fs.readFileSync(path.join(dir, file), "utf-8");
+                const content = fs.readFileSync(safe, "utf-8");
                 allContents.set(file, content);
             }
             catch { /* skip */ }
@@ -432,8 +445,11 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
         .slice(0, 10);
     for (const file of testSampled) {
         if (!allContents.has(file)) {
+            const safe = safePath(dir, file);
+            if (!safe)
+                continue;
             try {
-                const content = fs.readFileSync(path.join(dir, file), "utf-8");
+                const content = fs.readFileSync(safe, "utf-8");
                 allContents.set(file, content);
             }
             catch { /* skip */ }
@@ -467,7 +483,213 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
         });
     }
     // ========================================
-    // 6. KEY DIRECTORY PURPOSES (app-specific)
+    // 6. AUTH PATTERNS
+    // ========================================
+    const authPatterns = [
+        { pattern: "useAuth|useSession|useUser", name: "auth hooks (useAuth/useSession/useUser)", count: 0 },
+        { pattern: "withAuth|authMiddleware|requireAuth", name: "auth middleware", count: 0 },
+        { pattern: "passport\\.authenticate", name: "Passport.js", count: 0 },
+        { pattern: "jwt\\.verify|jwt\\.sign|jsonwebtoken", name: "JWT (jsonwebtoken)", count: 0 },
+        { pattern: "@login_required|LoginRequiredMixin", name: "Django login_required", count: 0 },
+        { pattern: "IsAuthenticated|AllowAny|BasePermission", name: "DRF permissions", count: 0 },
+        { pattern: "NextAuth|getServerSession", name: "NextAuth.js", count: 0 },
+        { pattern: "supabase\\.auth|useSupabaseClient", name: "Supabase Auth", count: 0 },
+        { pattern: "clerk|useClerk|ClerkProvider", name: "Clerk", count: 0 },
+    ];
+    for (const [, content] of allContents) {
+        for (const p of authPatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+            }
+        }
+    }
+    const dominantAuth = authPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
+    if (dominantAuth.length > 0) {
+        const primary = dominantAuth[0];
+        // Find auth middleware/guard files
+        const authFiles = files.filter((f) => (f.includes("auth") || f.includes("middleware") || f.includes("guard") || f.includes("session")) &&
+            !f.includes("node_modules") && !f.includes(".test.") &&
+            (f.endsWith(".ts") || f.endsWith(".tsx") || f.endsWith(".js") || f.endsWith(".py")));
+        const authEntrypoint = authFiles.find((f) => f.includes("middleware") || f.includes("guard") || f.includes("auth/index"));
+        let desc = `Auth uses ${primary.name}.`;
+        if (authEntrypoint) {
+            desc += ` Auth logic lives in ${authEntrypoint}.`;
+        }
+        findings.push({
+            category: "Dominant patterns",
+            description: desc,
+            evidence: `${primary.count} files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 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 },
+    ];
+    for (const [f, content] of allContents) {
+        for (const p of stylePatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+            }
+        }
+    }
+    const dominantStyle = stylePatterns.filter((p) => p.count >= 3).sort((a, b) => b.count - a.count);
+    if (dominantStyle.length > 0) {
+        const primary = dominantStyle[0];
+        let desc = `${primary.desc}.`;
+        // For Tailwind, check for custom tokens
+        if (primary.name === "Tailwind CSS") {
+            const twConfig = files.find((f) => f.includes("tailwind.config"));
+            if (twConfig) {
+                const safeTw = safePath(dir, twConfig);
+                if (safeTw)
+                    try {
+                        const configContent = fs.readFileSync(safeTw, "utf-8");
+                        if (configContent.includes("colors") || configContent.includes("extend")) {
+                            desc += ` Custom design tokens defined in ${twConfig} — use these instead of arbitrary values.`;
+                        }
+                    }
+                    catch { /* skip */ }
+            }
+        }
+        findings.push({
+            category: "Dominant patterns",
+            description: desc,
+            evidence: `${primary.count} files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 8. DATABASE / ORM PATTERNS
+    // ========================================
+    const dbPatterns = [
+        { pattern: "prisma\\.|PrismaClient|\\$queryRaw", name: "Prisma", entryHint: "prisma/schema.prisma", count: 0 },
+        { pattern: "drizzle\\(|pgTable|sqliteTable", name: "Drizzle ORM", entryHint: "drizzle.config.ts", count: 0 },
+        { pattern: "knex\\(|knex\\.schema", name: "Knex.js", entryHint: "knexfile", count: 0 },
+        { pattern: "sequelize\\.define|Model\\.init", name: "Sequelize", entryHint: "models/", count: 0 },
+        { pattern: "TypeORM|@Entity|getRepository", name: "TypeORM", entryHint: "entities/", count: 0 },
+        { pattern: "mongoose\\.model|Schema\\(\\{", name: "Mongoose", entryHint: "models/", count: 0 },
+        { pattern: "from django\\.db|models\\.Model", name: "Django ORM", entryHint: "models.py", count: 0 },
+        { pattern: "SQLAlchemy|declarative_base|sessionmaker", name: "SQLAlchemy", entryHint: "models/", count: 0 },
+        { pattern: "from tortoise|tortoise\\.models", name: "Tortoise ORM", entryHint: "models/", count: 0 },
+    ];
+    for (const [, content] of allContents) {
+        for (const p of dbPatterns) {
+            if (new RegExp(p.pattern).test(content)) {
+                p.count++;
+            }
+        }
+    }
+    const dominantDB = dbPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
+    if (dominantDB.length > 0) {
+        const primary = dominantDB[0];
+        // Try to find the actual entrypoint file
+        const dbEntryFile = files.find((f) => f.includes(primary.entryHint) && !f.includes("node_modules"));
+        let desc = `Database access uses ${primary.name}.`;
+        if (dbEntryFile) {
+            desc += ` Schema/models defined in ${dbEntryFile}.`;
+        }
+        else {
+            desc += ` Look for schemas in ${primary.entryHint}.`;
+        }
+        findings.push({
+            category: "Dominant patterns",
+            description: desc,
+            evidence: `${primary.count} files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 9. GENERATED / DO-NOT-EDIT FILES
+    // ========================================
+    const generatedFiles = [];
+    for (const [file, content] of allContents) {
+        const firstLines = content.slice(0, 500);
+        if (/@generated/.test(firstLines) ||
+            /DO NOT EDIT/i.test(firstLines) ||
+            /auto-generated/i.test(firstLines) ||
+            /this file is generated/i.test(firstLines) ||
+            /generated by/i.test(firstLines)) {
+            generatedFiles.push(file);
+        }
+    }
+    // Also check for common generated file patterns in the full file list
+    const knownGenerated = files.filter((f) => !f.includes("node_modules") &&
+        (f.includes(".generated.") ||
+            f.includes(".gen.") ||
+            f.endsWith(".d.ts") && f.includes("generated") ||
+            f.includes("__generated__") ||
+            f.includes("codegen")));
+    const allGenerated = [...new Set([...generatedFiles, ...knownGenerated])];
+    if (allGenerated.length >= 2) {
+        const samples = allGenerated.slice(0, 5).join(", ");
+        findings.push({
+            category: "Critical constraints",
+            description: `Generated files detected (${samples}${allGenerated.length > 5 ? ", ..." : ""}). Do NOT edit these directly — modify the source/schema they are generated from.`,
+            evidence: `${allGenerated.length} generated files`,
+            confidence: "high",
+            discoverable: false,
+        });
+    }
+    // ========================================
+    // 10. EDIT ENTRYPOINTS (where changes usually land)
+    // ========================================
+    // For routing — find where route definitions live
+    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.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, i, a) => a.indexOf(v) === i)
+            .slice(0, 3);
+        if (routeDirs.length > 0) {
+            findings.push({
+                category: "Dominant patterns",
+                description: `Route definitions live in: ${routeDirs.join(", ")}. Add new endpoints here.`,
+                evidence: `${routeDirs.length} route directories`,
+                confidence: "high",
+                discoverable: false,
+            });
+        }
+    }
+    // For components — find where UI components live
+    const componentDirs = files
+        .filter((f) => (f.includes("/components/") || f.includes("/ui/")) &&
+        !f.includes("node_modules") && !f.includes(".test.") &&
+        (f.endsWith(".tsx") || f.endsWith(".jsx") || f.endsWith(".vue") || f.endsWith(".svelte")))
+        .map((f) => {
+        const match = f.match(/(.*\/(?:components|ui))\//);
+        return match ? match[1] : null;
+    })
+        .filter((v) => v !== null)
+        .filter((v, i, a) => a.indexOf(v) === i)
+        .slice(0, 3);
+    if (componentDirs.length > 0 && componentDirs.some((d) => !d.includes("node_modules"))) {
+        const filtered = componentDirs.filter((d) => !d.includes("node_modules"));
+        if (filtered.length > 0) {
+            findings.push({
+                category: "Dominant patterns",
+                description: `UI components live in: ${filtered.join(", ")}. Add new components here.`,
+                evidence: `${filtered.length} component directories`,
+                confidence: "medium",
+                discoverable: false,
+            });
+        }
+    }
+    // ========================================
+    // 11. KEY DIRECTORY PURPOSES (app-specific)
     // ========================================
     // Detect directories with clear domain purposes
     const dirPurposes = [];

package/dist/types.d.ts

@@ -48,4 +48,6 @@ export interface ProjectScan {
         file: string;
         score: number;
     }[];
+    /** Detected repo mode for context prioritization */
+    repoMode?: "app" | "library" | "monorepo";
 }

package/dist/utils/output.js

@@ -2,9 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 export async function writeOutput(dir, filename, content) {
     const filePath = path.join(dir, filename);
-    const parentDir = path.dirname(filePath);
+    const resolved = path.resolve(filePath);
+    if (!resolved.startsWith(path.resolve(dir) + path.sep)) {
+        throw new Error(`Output path escapes target directory: ${filename}`);
+    }
+    const parentDir = path.dirname(resolved);
     if (!fs.existsSync(parentDir)) {
         fs.mkdirSync(parentDir, { recursive: true });
     }
-    fs.writeFileSync(filePath, content, "utf-8");
+    fs.writeFileSync(resolved, content, "utf-8");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcebook",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
   "type": "module",
   "bin": {