@phuetz/code-buddy 1.1.0 → 1.3.0

package/dist/config/model-tools.js

@@ -405,13 +405,13 @@ const DEFAULT_MODEL_CONFIGS = [
         patchFormat: 'full_file',
         promptProfile: 'lite',
     },
-    // Gemma 4 (Ollama, e2b/e4b) — local lightweight model. Same lite
-    // profile as qwen/llama: minimal SP, no tool_calls advertised,
-    // chat-only base prompt to avoid JSON hallucination on small models.
+    // Gemma 4 (Ollama, e2b/e4b) — local model with tool support. Keep the
+    // lite prompt/tool profile, but do not gate off tool calls: real `buddy goal`
+    // smoke with gemma4:12b only succeeds when the selected tools are preserved.
     {
         model: 'gemma4*',
         supportsReasoning: false,
-        supportsToolCalls: false,
+        supportsToolCalls: true,
         supportsVision: false,
         contextWindow: 8192,
         maxOutputTokens: 2048,

package/dist/config/toml-config.d.ts

@@ -122,6 +122,20 @@ export interface ModelPairsConfig {
     /** Model used for code edits and execution (the "doer") */
     editor?: string;
 }
+/** Active-LLM registry: auto-failover across the user's live logins + "together". */
+export interface LlmFailoverConfig {
+    /** Master gate. OFF by default — single-provider behavior is unchanged. */
+    enabled?: boolean;
+    /** Fallback ordering: 'resilience' (capable/subscription first, local last),
+     * 'free-first' (cheapest first), or 'manual' (explicit `manualOrder`). */
+    order?: 'resilience' | 'free-first' | 'manual';
+    /** Provider ids in preferred order when `order: 'manual'`. */
+    manualOrder?: string[];
+    /** Restrict the active set to local runtimes (privacy). */
+    local_only?: boolean;
+    /** Default strategy for `/llm ensemble` (Phase 2). */
+    together_strategy?: 'ensemble' | 'consensus' | 'fastest' | 'cascade';
+}
 /**
  * External integrations configuration
  */
@@ -497,6 +511,8 @@ export interface CodeBuddyConfig {
     integrations: IntegrationsConfig;
     /** Model pairs for architect/editor split */
     model_pairs?: ModelPairsConfig;
+    /** Active-LLM registry: auto-failover across live logins + "together" */
+    llm?: LlmFailoverConfig;
     /** Agent defaults (model preferences) — Native Engine v2026.3.14 */
     agent_defaults?: AgentDefaultsConfig;
     /** Advisor tool settings (second opinion model) — V4.1 */

package/dist/config/toml-config.js

@@ -540,6 +540,9 @@ class ConfigManager {
         if (partial.model_pairs) {
             this.config.model_pairs = { ...this.config.model_pairs, ...partial.model_pairs };
         }
+        if (partial.llm) {
+            this.config.llm = { ...this.config.llm, ...partial.llm };
+        }
     }
     /**
      * Get current config

package/dist/context/bootstrap-loader.js

@@ -15,10 +15,12 @@ import { logger } from '../utils/logger.js';
 // ============================================================================
 // Defaults
 // ============================================================================
+// AGENTS.md is intentionally NOT here — instruction files (AGENTS/CODEBUDDY/
+// CONTEXT/INSTRUCTIONS) are owned by the unified project-context loader
+// (src/context/project-context.ts). This loader covers soul/identity files.
 const DEFAULT_BOOTSTRAP_FILES = [
     'BOOT.md',
     'BOOTSTRAP.md',
-    'AGENTS.md',
     'SOUL.md',
     // TOOLS.md excluded: tool descriptions are already sent as function definitions
     'IDENTITY.md',
@@ -80,28 +82,9 @@ export class BootstrapLoader {
             sources.push(content.source);
             totalChars += text.length;
         }
-        // 2. Hierarchical instruction files (Codex CLI pattern)
-        if (totalChars < this.config.maxChars) {
-            const hierarchicalResult = await this.loadHierarchical(cwd);
-            for (const entry of hierarchicalResult) {
-                if (totalChars >= this.config.maxChars) {
-                    truncated = true;
-                    break;
-                }
-                if (sources.includes(entry.source))
-                    continue;
-                const remaining = this.config.maxChars - totalChars;
-                let text = entry.text;
-                if (text.length > remaining) {
-                    text = text.slice(0, remaining) + '\n\n... (truncated)';
-                    truncated = true;
-                }
-                const relSource = path.relative(cwd, entry.source) || entry.source;
-                sections.push(`## ${entry.fileName} (${relSource})\n\n${text}`);
-                sources.push(entry.source);
-                totalChars += text.length;
-            }
-        }
+        // (Instruction-file hierarchy — AGENTS/CODEBUDDY/CONTEXT/INSTRUCTIONS — is
+        // now handled by the unified project-context loader, injected before this
+        // block in prompt-builder. `loadHierarchical` below is retained but unused.)
         // 3. Auto-generated project knowledge (from /docs generate --with-llm)
         if (totalChars < this.config.maxChars) {
             const knowledgePath = path.join(cwd, '.codebuddy', 'PROJECT_KNOWLEDGE.md');

package/dist/context/context-manager-v2.js

@@ -699,6 +699,7 @@ export class ContextManagerV2 {
      * Clean up resources
      */
     dispose() {
+        this.stopPeriodicSnapshot();
         this.tokenCounter.dispose();
         this.summaries = [];
         this.triggeredWarnings.clear();

package/dist/context/import-directive-parser.d.ts

@@ -27,6 +27,10 @@ export interface ImportResolveOptions {
     depth?: number;
     /** Set of already-visited absolute paths (cycle detection) */
     visited?: Set<string>;
+    /** Max recursion depth for nested imports (default 5) */
+    maxDepth?: number;
+    /** Max total content size after imports, in chars (default 50000) */
+    maxBytes?: number;
 }
 /**
  * Resolve all @import directives in the given content.

package/dist/context/import-directive-parser.js

@@ -43,14 +43,23 @@ const IMPORT_DIRECTIVE_REGEX = /^@(~\/|\/\/|[^\s@].+?)$/gm;
  * @returns Content with all imports resolved inline
  */
 export function resolveImportDirectives(content, options) {
-    const { baseDir, projectRoot = process.cwd(), homeDir = process.env.HOME || process.env.USERPROFILE || '', depth = 0, visited = new Set(), } = options;
-    if (depth >= MAX_IMPORT_DEPTH) {
-        logger.debug(`Import directive: max depth ${MAX_IMPORT_DEPTH} reached, skipping further imports`);
+    const { baseDir, projectRoot = process.cwd(), homeDir = process.env.HOME || process.env.USERPROFILE || '', depth = 0, visited = new Set(), maxDepth = MAX_IMPORT_DEPTH, maxBytes = MAX_IMPORT_CONTENT, } = options;
+    if (depth >= maxDepth) {
+        logger.debug(`Import directive: max depth ${maxDepth} reached, skipping further imports`);
         return content;
     }
     let result = content;
     let totalSize = content.length;
-    result = result.replace(IMPORT_DIRECTIVE_REGEX, (fullMatch, importPath) => {
+    // Mask code regions so an @path directive that sits inside a fenced block or
+    // inline code span is left as literal content, not resolved as an import.
+    // Matches Claude Code / Gemini CLI semantics (a code example that mentions
+    // `@./foo.md` must not trigger a file read).
+    const codeRegions = findCodeRegions(content);
+    result = result.replace(IMPORT_DIRECTIVE_REGEX, (fullMatch, importPath, offset) => {
+        // Leave directives inside code spans/fences untouched.
+        if (isInsideRegion(offset, codeRegions)) {
+            return fullMatch;
+        }
         // Resolve the import path
         const resolvedPath = resolveImportPath(importPath.trim(), baseDir, projectRoot, homeDir);
         if (!resolvedPath) {
@@ -71,9 +80,9 @@ export function resolveImportDirectives(content, options) {
         try {
             let importedContent = fs.readFileSync(absolutePath, 'utf-8');
             // Size guard
-            if (totalSize + importedContent.length > MAX_IMPORT_CONTENT) {
+            if (totalSize + importedContent.length > maxBytes) {
                 logger.debug(`Import directive: size limit reached, truncating "${importPath}"`);
-                const remaining = MAX_IMPORT_CONTENT - totalSize;
+                const remaining = maxBytes - totalSize;
                 if (remaining <= 0) {
                     return `<!-- import truncated: ${importPath} -->`;
                 }
@@ -88,6 +97,8 @@ export function resolveImportDirectives(content, options) {
                 homeDir,
                 depth: depth + 1,
                 visited: newVisited,
+                maxDepth,
+                maxBytes,
             });
             totalSize += resolved.length;
             logger.debug(`Import directive: resolved "${importPath}" (${resolved.length} chars)`);
@@ -129,4 +140,38 @@ function resolveImportPath(importPath, baseDir, projectRoot, homeDir) {
         return null;
     }
 }
+// ============================================================================
+// Code-region masking (so @imports inside code are inert)
+// ============================================================================
+/**
+ * Find all code spans/fences in the content as [start, end) ranges.
+ *
+ * Covers backtick code — inline `` `…` `` and fenced ```` ```…``` ```` (one or
+ * more backticks, closed by the same count) — plus `~~~` fenced blocks. An
+ * @import directive whose `@` falls inside any of these ranges is treated as
+ * literal text. Mirrors the gemini-cli memory import processor.
+ */
+function findCodeRegions(content) {
+    const regions = [];
+    // Backtick inline + fenced: one or more backticks, lazily to the same run.
+    const backtick = /(`+)([\s\S]*?)\1/g;
+    let m;
+    while ((m = backtick.exec(content)) !== null) {
+        regions.push([m.index, m.index + m[0].length]);
+    }
+    // Tilde fenced blocks: a line of >=3 tildes, content, closing tilde line.
+    const tilde = /^[^\S\n]*(~{3,})[^\n]*\n[\s\S]*?\n[^\S\n]*\1[^\S\n]*$/gm;
+    while ((m = tilde.exec(content)) !== null) {
+        regions.push([m.index, m.index + m[0].length]);
+    }
+    return regions;
+}
+/** True if `offset` lies within any [start, end) code region. */
+function isInsideRegion(offset, regions) {
+    for (const [start, end] of regions) {
+        if (offset >= start && offset < end)
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=import-directive-parser.js.map

package/dist/context/instruction-excludes.d.ts

@@ -7,9 +7,38 @@
  * Advanced enterprise architecture for claudeMdExcludes setting.
  */
 /**
- * Clear the excludes cache (for testing).
+ * Clear the excludes cache (for testing / config reload).
  */
 export declare function clearExcludesCache(): void;
+/**
+ * Clear the context-config cache (for testing / `/context reload`).
+ */
+export declare function clearContextConfigCache(): void;
+/**
+ * Accepted project-instruction filenames, in precedence order. `AGENTS.md` is
+ * the cross-CLI primary (read by Codex/Cursor/Copilot/Claude Code); the rest
+ * are read for interop. All present names compose within a directory.
+ */
+export declare const DEFAULT_CONTEXT_FILE_NAMES: readonly string[];
+export interface ResolvedContextConfig {
+    /** Accepted instruction filenames, in precedence order. */
+    fileNames: string[];
+    /** Total byte budget for the startup hierarchy (Codex project_doc_max_bytes parity). */
+    maxBytes: number;
+    /** Per-touch incremental byte budget for JIT discovery. */
+    jitMaxBytes: number;
+    /** Byte budget passed to the @import resolver. */
+    importMaxBytes: number;
+    /** Max recursion depth for @import. */
+    importMaxDepth: number;
+}
+/**
+ * Load the `context` block from `.codebuddy/settings.json`, merged over
+ * defaults. Cached by settings path (cleared via `clearContextConfigCache()`).
+ * A missing `context` key returns the defaults, so existing projects are
+ * unaffected.
+ */
+export declare function loadContextConfig(projectRoot?: string): ResolvedContextConfig;
 /**
  * Load exclude patterns from settings.json.
  * Returns an array of glob patterns (e.g., ["packages/legacy/**"]).

package/dist/context/instruction-excludes.js

@@ -15,13 +15,83 @@ import { logger } from '../utils/logger.js';
 // ============================================================================
 let _excludePatterns = null;
 let _excludeCachePath = null;
+let _contextConfig = null;
+let _contextConfigCachePath = null;
 /**
- * Clear the excludes cache (for testing).
+ * Clear the excludes cache (for testing / config reload).
  */
 export function clearExcludesCache() {
     _excludePatterns = null;
     _excludeCachePath = null;
 }
+/**
+ * Clear the context-config cache (for testing / `/context reload`).
+ */
+export function clearContextConfigCache() {
+    _contextConfig = null;
+    _contextConfigCachePath = null;
+}
+// ============================================================================
+// Context-file configuration (single source of truth for accepted filenames)
+// ============================================================================
+/**
+ * Accepted project-instruction filenames, in precedence order. `AGENTS.md` is
+ * the cross-CLI primary (read by Codex/Cursor/Copilot/Claude Code); the rest
+ * are read for interop. All present names compose within a directory.
+ */
+export const DEFAULT_CONTEXT_FILE_NAMES = [
+    'AGENTS.md',
+    'CODEBUDDY.md',
+    'CLAUDE.md',
+    'GEMINI.md',
+    'CONTEXT.md',
+    'INSTRUCTIONS.md',
+];
+const DEFAULT_CONTEXT_CONFIG = {
+    fileNames: [...DEFAULT_CONTEXT_FILE_NAMES],
+    maxBytes: 32_768,
+    jitMaxBytes: 4_096,
+    importMaxBytes: 50_000,
+    importMaxDepth: 5,
+};
+/**
+ * Load the `context` block from `.codebuddy/settings.json`, merged over
+ * defaults. Cached by settings path (cleared via `clearContextConfigCache()`).
+ * A missing `context` key returns the defaults, so existing projects are
+ * unaffected.
+ */
+export function loadContextConfig(projectRoot = process.cwd()) {
+    const settingsPath = path.join(projectRoot, '.codebuddy', 'settings.json');
+    if (_contextConfig && _contextConfigCachePath === settingsPath) {
+        return _contextConfig;
+    }
+    const cfg = { ...DEFAULT_CONTEXT_CONFIG, fileNames: [...DEFAULT_CONTEXT_FILE_NAMES] };
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const raw = fs.readFileSync(settingsPath, 'utf-8');
+            const ctx = JSON.parse(raw)?.context;
+            if (ctx && typeof ctx === 'object') {
+                if (Array.isArray(ctx.fileNames) && ctx.fileNames.every((n) => typeof n === 'string') && ctx.fileNames.length > 0) {
+                    cfg.fileNames = ctx.fileNames;
+                }
+                if (Number.isFinite(ctx.maxBytes) && ctx.maxBytes > 0)
+                    cfg.maxBytes = ctx.maxBytes;
+                if (Number.isFinite(ctx.jitMaxBytes) && ctx.jitMaxBytes > 0)
+                    cfg.jitMaxBytes = ctx.jitMaxBytes;
+                if (Number.isFinite(ctx.importMaxBytes) && ctx.importMaxBytes > 0)
+                    cfg.importMaxBytes = ctx.importMaxBytes;
+                if (Number.isFinite(ctx.importMaxDepth) && ctx.importMaxDepth > 0)
+                    cfg.importMaxDepth = ctx.importMaxDepth;
+            }
+        }
+        catch (err) {
+            logger.debug(`Failed to load context config: ${err}`);
+        }
+    }
+    _contextConfig = cfg;
+    _contextConfigCachePath = settingsPath;
+    return cfg;
+}
 // ============================================================================
 // Loader
 // ============================================================================

package/dist/context/jit-context.d.ts

@@ -1,24 +1,22 @@
 /**
  * JIT (Just-In-Time) Context Discovery
  *
- * Dynamically loads .codebuddy/ context files when tools access
- * subdirectories. Context grows organically as the agent explores,
- * rather than loading everything at startup.
+ * When a tool accesses a path, this loads the instruction files in that
+ * subtree that weren't already injected at startup (delegated to the unified
+ * `project-context` loader, sharing its dedup registry), plus two JIT-only
+ * concerns: auto-discovered doc pages (DOC_DIR_MAP) and path-scoped rules.
  *
- * Inspired by Gemini CLI's jit-context.ts
+ * Inspired by Gemini CLI's jit-context.
  */
 export declare const JIT_CONTEXT_PREFIX = "\n\n--- Discovered Context ---\n";
 export declare const JIT_CONTEXT_SUFFIX = "\n--- End Context ---";
 /**
- * Clear loaded paths cache (for testing).
+ * Clear caches (for testing / `/context reload`). Resets both the doc dedup set
+ * and the active context registry so the next pass re-scans from scratch.
  */
 export declare function clearJitCache(): void;
 /**
- * Discover and load context files for a given accessed path.
- *
- * Walks upward from the accessed file's directory to the project root,
- * checking for context files at each level. Only loads files that
- * haven't been loaded before in this session.
+ * Discover and load JIT context for a given accessed path.
  *
  * @param accessedPath - The file/directory path being accessed by a tool
  * @param projectRoot - The project root directory (stop walking here)

package/dist/context/jit-context.js

@@ -1,28 +1,18 @@
 /**
  * JIT (Just-In-Time) Context Discovery
  *
- * Dynamically loads .codebuddy/ context files when tools access
- * subdirectories. Context grows organically as the agent explores,
- * rather than loading everything at startup.
+ * When a tool accesses a path, this loads the instruction files in that
+ * subtree that weren't already injected at startup (delegated to the unified
+ * `project-context` loader, sharing its dedup registry), plus two JIT-only
+ * concerns: auto-discovered doc pages (DOC_DIR_MAP) and path-scoped rules.
  *
- * Inspired by Gemini CLI's jit-context.ts
+ * Inspired by Gemini CLI's jit-context.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { logger } from '../utils/logger.js';
 import { discoverRulesForPath } from './rules-loader.js';
-import { shouldExcludeInstructionFile } from './instruction-excludes.js';
-import { resolveImportDirectives } from './import-directive-parser.js';
-/** Context file names to discover */
-const CONTEXT_FILES = [
-    'CODEBUDDY.md',
-    'CONTEXT.md',
-    'INSTRUCTIONS.md',
-    'AGENTS.md',
-    'README.md',
-];
-/** Directories that may contain context files */
-const CONTEXT_DIRS = ['.codebuddy', '.claude'];
+import { resolveJitContext, getActiveContextRegistry } from './project-context.js';
 /**
  * Map of source directory prefixes → relevant doc page slugs.
  * When a tool accesses a path under a key, the matching doc is auto-discovered.
@@ -45,26 +35,22 @@ const DOC_DIR_MAP = {
     'src/checkpoints': ['architecture'],
     'tests': ['testing'],
 };
-/** Set of already-loaded paths (avoid re-loading) */
+/** Set of already-loaded doc paths (instruction files dedup via the registry). */
 const loadedPaths = new Set();
 /** Maximum context size per discovery (chars) */
 const MAX_JIT_CONTEXT_CHARS = 4000;
-/** Maximum directory depth to traverse upward */
-const MAX_UPWARD_DEPTH = 10;
 export const JIT_CONTEXT_PREFIX = '\n\n--- Discovered Context ---\n';
 export const JIT_CONTEXT_SUFFIX = '\n--- End Context ---';
 /**
- * Clear loaded paths cache (for testing).
+ * Clear caches (for testing / `/context reload`). Resets both the doc dedup set
+ * and the active context registry so the next pass re-scans from scratch.
  */
 export function clearJitCache() {
     loadedPaths.clear();
+    getActiveContextRegistry().clear();
 }
 /**
- * Discover and load context files for a given accessed path.
- *
- * Walks upward from the accessed file's directory to the project root,
- * checking for context files at each level. Only loads files that
- * haven't been loaded before in this session.
+ * Discover and load JIT context for a given accessed path.
  *
  * @param accessedPath - The file/directory path being accessed by a tool
  * @param projectRoot - The project root directory (stop walking here)
@@ -74,84 +60,18 @@ export function discoverJitContext(accessedPath, projectRoot = process.cwd()) {
     try {
         const normalizedRoot = path.resolve(projectRoot);
         const normalizedPath = path.resolve(accessedPath);
-        // Start from the accessed file's directory
-        let currentDir = fs.existsSync(normalizedPath) && fs.statSync(normalizedPath).isDirectory()
-            ? normalizedPath
-            : path.dirname(normalizedPath);
         const discoveredContent = [];
-        let depth = 0;
-        while (depth < MAX_UPWARD_DEPTH) {
-            // Check if we've gone above the project root
-            if (!currentDir.startsWith(normalizedRoot) && currentDir !== normalizedRoot) {
-                break;
-            }
-            // Look for context files in this directory
-            for (const contextFile of CONTEXT_FILES) {
-                const filePath = path.join(currentDir, contextFile);
-                if (!loadedPaths.has(filePath) && fs.existsSync(filePath)) {
-                    // CC10: Check instruction excludes
-                    if (shouldExcludeInstructionFile(filePath, normalizedRoot)) {
-                        logger.debug(`JIT context: excluded ${path.relative(normalizedRoot, filePath)}`);
-                        loadedPaths.add(filePath); // Mark as "seen" to avoid re-checking
-                        continue;
-                    }
-                    try {
-                        let content = fs.readFileSync(filePath, 'utf-8');
-                        if (content.trim()) {
-                            // CC9: Resolve @import directives
-                            content = resolveImportDirectives(content, {
-                                baseDir: path.dirname(filePath),
-                                projectRoot: normalizedRoot,
-                            });
-                            const relativePath = path.relative(normalizedRoot, filePath).replace(/\\/g, '/');
-                            discoveredContent.push(`[${relativePath}]\n${content.trim()}`);
-                            loadedPaths.add(filePath);
-                            logger.debug(`JIT context: loaded ${relativePath}`);
-                        }
-                    }
-                    catch { /* read error — skip */ }
-                }
-            }
-            // Also check .codebuddy/ and .claude/ subdirectories
-            for (const contextDir of CONTEXT_DIRS) {
-                const dirPath = path.join(currentDir, contextDir);
-                if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
-                    for (const contextFile of CONTEXT_FILES) {
-                        const filePath = path.join(dirPath, contextFile);
-                        if (!loadedPaths.has(filePath) && fs.existsSync(filePath)) {
-                            // CC10: Check instruction excludes
-                            if (shouldExcludeInstructionFile(filePath, normalizedRoot)) {
-                                logger.debug(`JIT context: excluded ${path.relative(normalizedRoot, filePath)}`);
-                                loadedPaths.add(filePath);
-                                continue;
-                            }
-                            try {
-                                let content = fs.readFileSync(filePath, 'utf-8');
-                                if (content.trim()) {
-                                    // CC9: Resolve @import directives
-                                    content = resolveImportDirectives(content, {
-                                        baseDir: path.dirname(filePath),
-                                        projectRoot: normalizedRoot,
-                                    });
-                                    const relativePath = path.relative(normalizedRoot, filePath).replace(/\\/g, '/');
-                                    discoveredContent.push(`[${relativePath}]\n${content.trim()}`);
-                                    loadedPaths.add(filePath);
-                                    logger.debug(`JIT context: loaded ${relativePath}`);
-                                }
-                            }
-                            catch { /* read error — skip */ }
-                        }
-                    }
-                }
-            }
-            // Move up
-            const parent = path.dirname(currentDir);
-            if (parent === currentDir)
-                break; // reached filesystem root
-            currentDir = parent;
-            depth++;
+        // 1. Instruction files in the accessed subtree, via the unified loader.
+        //    The shared active registry skips anything already injected at startup,
+        //    so the same AGENTS.md/CODEBUDDY.md is never duplicated.
+        const ctx = resolveJitContext(accessedPath, {
+            projectRoot: normalizedRoot,
+            registry: getActiveContextRegistry(),
+        });
+        if (ctx.text) {
+            discoveredContent.push(ctx.text);
         }
-        // Auto-discover relevant doc pages based on accessed path
+        // 2. Auto-discover relevant doc pages based on the accessed path.
         const relativePath = path.relative(normalizedRoot, normalizedPath).replace(/\\/g, '/');
         for (const [prefix, slugPatterns] of Object.entries(DOC_DIR_MAP)) {
             if (!relativePath.startsWith(prefix))
@@ -160,16 +80,16 @@ export function discoverJitContext(accessedPath, projectRoot = process.cwd()) {
             if (!fs.existsSync(docsDir))
                 break;
             try {
-                const docFiles = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+                const docFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith('.md'));
                 for (const pattern of slugPatterns) {
-                    const match = docFiles.find(f => f.includes(pattern));
+                    const match = docFiles.find((f) => f.includes(pattern));
                     if (!match)
                         continue;
                     const docPath = path.join(docsDir, match);
                     if (loadedPaths.has(docPath))
                         continue;
                     const content = fs.readFileSync(docPath, 'utf-8');
-                    // Only inject the first 2 sections (title + first H2) to stay compact
+                    // Only inject the first 2 sections (title + first H2) to stay compact.
                     const sections = content.split(/(?=^## )/m);
                     const compact = sections.slice(0, 2).join('').trim();
                     if (compact) {
@@ -181,10 +101,12 @@ export function discoverJitContext(accessedPath, projectRoot = process.cwd()) {
                     break; // One doc per prefix
                 }
             }
-            catch { /* docs dir not readable */ }
+            catch {
+                /* docs dir not readable */
+            }
             break; // One prefix match
         }
-        // Discover path-scoped rules matching this access
+        // 3. Path-scoped rules matching this access.
         const rulesContext = discoverRulesForPath(accessedPath, projectRoot);
         if (rulesContext) {
             discoveredContent.push(rulesContext);