@phuetz/code-buddy 1.2.0 → 1.3.1

package/dist/commands/cli/improve-command.js

@@ -101,6 +101,129 @@ export function registerImproveCommands(program) {
             .join('\n');
         print({ ...result, committed }, options, text);
     });
+    improve
+        .command('tools')
+        .description('Author + behaviorally validate NEW tools for the agent (held-out gated, anti-gaming)')
+        .option('--json', 'output JSON')
+        .option('--apply', 'keep validated tools for this session (overrides propose-only)')
+        .action(async (options) => {
+        const { ToolImprovementEngine } = await import('../../agent/self-improvement/tool-engine.js');
+        const { LlmToolProposer } = await import('../../agent/self-improvement/llm-tool-proposer.js');
+        const { SEED_TOOL_SCENARIOS } = await import('../../agent/self-improvement/tool-benchmark.js');
+        const engine = new ToolImprovementEngine({
+            scenarios: SEED_TOOL_SCENARIOS,
+            proposer: new LlmToolProposer(),
+            ...(options.apply ? { autonomy: 'auto-apply' } : {}),
+        });
+        const results = await engine.runLoop();
+        const kept = results.map((r) => (r.applied ? r.gate?.appliedRef : null)).filter(Boolean);
+        const text = [
+            `Autonomy: ${results[0]?.autonomy ?? 'propose-only'}`,
+            `Cycles: ${results.length}`,
+            ...results.map((r) => `  ${r.selectedScenarioId ?? '—'}: ${r.applied
+                ? `AUTHORED + KEPT (${r.gate?.appliedRef})`
+                : r.gate?.accepted
+                    ? 'accepted (propose-only) — re-run with --apply to keep'
+                    : r.gate?.rejectionReason
+                        ? `rejected (${r.gate.rejectionReason})`
+                        : r.notes.join('; ')}`),
+            kept.length
+                ? `Kept: ${kept.join(', ')} (archived + persisted to .codebuddy/self-improvement; reloaded at next start when CODEBUDDY_SELF_IMPROVE=true)`
+                : 'No tool kept this run',
+        ].join('\n');
+        print({ kind: 'self_improvement_tools', cycles: results }, options, text);
+    });
+    improve
+        .command('skills')
+        .description('Author + safety-gate NEW skills for the agent (firewall + coverage)')
+        .option('--json', 'output JSON')
+        .option('--apply', 'install validated skills (overrides propose-only)')
+        .action(async (options) => {
+        const { SkillImprovementEngine } = await import('../../agent/self-improvement/skill-engine.js');
+        const { LlmSkillProposer } = await import('../../agent/self-improvement/skill-proposer.js');
+        const { SEED_SKILL_SCENARIOS } = await import('../../agent/self-improvement/skill-benchmark.js');
+        const engine = new SkillImprovementEngine({
+            scenarios: SEED_SKILL_SCENARIOS,
+            proposer: new LlmSkillProposer(),
+            ...(options.apply ? { autonomy: 'auto-apply' } : {}),
+        });
+        const results = await engine.runLoop();
+        const kept = results.map((r) => (r.applied ? r.gate?.appliedRef : null)).filter(Boolean);
+        const text = [
+            `Autonomy: ${results[0]?.autonomy ?? 'propose-only'}`,
+            `Cycles: ${results.length}`,
+            ...results.map((r) => `  ${r.selectedScenarioId ?? '—'}: ${r.applied
+                ? `AUTHORED + INSTALLED (${r.gate?.appliedRef})`
+                : r.gate?.accepted
+                    ? 'accepted (propose-only) — re-run with --apply to install'
+                    : r.gate?.rejectionReason
+                        ? `rejected (${r.gate.rejectionReason})`
+                        : r.notes.join('; ')}`),
+            kept.length ? `Installed: ${kept.join(', ')} (under .codebuddy/skills/authored)` : 'No skill installed this run',
+        ].join('\n');
+        print({ kind: 'self_improvement_skills', cycles: results }, options, text);
+    });
+    improve
+        .command('skills-list')
+        .description('List installed authored skills (with pinned status)')
+        .option('--json', 'output JSON')
+        .action(async (options) => {
+        const { LiveSkillMutator } = await import('../../agent/self-improvement/skill-mutator.js');
+        const m = new LiveSkillMutator();
+        const skills = m.listAuthored().map((name) => ({ name, pinned: m.isPinned(name) }));
+        const text = skills.length
+            ? skills.map((s) => `  ${s.pinned ? '📌' : '  '} ${s.name}`).join('\n')
+            : 'No authored skills installed';
+        print({ kind: 'authored_skills', skills }, options, text);
+    });
+    improve
+        .command('skills-pin <name>')
+        .description('Pin an authored skill (protect it from curation overwrite/remove/consolidation)')
+        .option('--json', 'output JSON')
+        .action(async (name, options) => {
+        const { LiveSkillMutator } = await import('../../agent/self-improvement/skill-mutator.js');
+        const ok = new LiveSkillMutator().pin(name);
+        print({ kind: 'skill_pin', name, ok }, options, ok ? `Pinned ${name}` : `Skill not found: ${name}`);
+    });
+    improve
+        .command('skills-unpin <name>')
+        .description('Unpin an authored skill')
+        .option('--json', 'output JSON')
+        .action(async (name, options) => {
+        const { LiveSkillMutator } = await import('../../agent/self-improvement/skill-mutator.js');
+        const ok = new LiveSkillMutator().unpin(name);
+        print({ kind: 'skill_unpin', name, ok }, options, ok ? `Unpinned ${name}` : `Skill not found: ${name}`);
+    });
+    improve
+        .command('skills-restore <name>')
+        .description('Restore a previously archived authored skill')
+        .option('--json', 'output JSON')
+        .action(async (name, options) => {
+        const { LiveSkillMutator } = await import('../../agent/self-improvement/skill-mutator.js');
+        const ok = new LiveSkillMutator().restore(name);
+        print({ kind: 'skill_restore', name, ok }, options, ok ? `Restored ${name}` : `No archived skill: ${name}`);
+    });
+    improve
+        .command('skills-consolidate')
+        .description('Merge overlapping authored skills into one umbrella (coverage-gated)')
+        .option('--json', 'output JSON')
+        .option('--apply', 'install the umbrella + archive merged siblings (else preview)')
+        .action(async (options) => {
+        const { LiveSkillMutator } = await import('../../agent/self-improvement/skill-mutator.js');
+        const { consolidateCluster, buildClusterFromInstalled, LlmUmbrellaProposer } = await import('../../agent/self-improvement/skill-consolidator.js');
+        const { SEED_SKILL_SCENARIOS } = await import('../../agent/self-improvement/skill-benchmark.js');
+        const mutator = new LiveSkillMutator();
+        const cluster = buildClusterFromInstalled(mutator, SEED_SKILL_SCENARIOS);
+        const out = await consolidateCluster(cluster, new LlmUmbrellaProposer(), mutator, new EvolutionaryArchive(), {
+            keepOnAccept: options.apply === true,
+        });
+        const text = out.accepted
+            ? out.absorbed.length
+                ? `Consolidated ${out.absorbed.join(', ')} into ${out.umbrellaName}` + (out.skippedPinned.length ? ` (kept pinned: ${out.skippedPinned.join(', ')})` : '')
+                : `Would consolidate into ${out.umbrellaName} — re-run with --apply` + (out.skippedPinned.length ? ` (would keep pinned: ${out.skippedPinned.join(', ')})` : '')
+            : `No consolidation: ${out.rejectionReason} — ${out.reasons.join('; ')}`;
+        print({ kind: 'skill_consolidation', ...out }, options, text);
+    });
     improve
         .command('loop')
         .description('Run improvement cycles until no further validated progress is made')

package/dist/commands/enhanced-command-handler.js

@@ -314,7 +314,7 @@ export class EnhancedCommandHandler {
         ['__ULTRAPLAN__', (args) => handleUltraplan(args)],
         ['__LIST_CHECKPOINTS__', (args) => handleListCheckpoints(args)],
         ['__RESTORE_CHECKPOINT__', (args) => handleRestoreCheckpoint(args)],
-        ['__INIT_GROK__', () => handleInitGrok()],
+        ['__INIT_GROK__', (args) => handleInitGrok(args)],
         ['__REINIT_GROK__', () => handleReinitGrok()],
         ['__FEATURES__', () => handleFeatures()],
         ['__LESSONS__', (args) => handleLessonsCommand(args.join(' '))],

package/dist/commands/handlers/missing-handlers.d.ts

@@ -22,7 +22,7 @@ export declare function handleDiffCheckpoints(args: string[]): Promise<CommandHa
 export declare function handleFeatures(): CommandHandlerResult;
 export declare function handleListCheckpoints(_args: string[]): Promise<CommandHandlerResult>;
 export declare function handleRestoreCheckpoint(args: string[]): Promise<CommandHandlerResult>;
-export declare function handleInitGrok(): Promise<CommandHandlerResult>;
+export declare function handleInitGrok(args?: string[]): Promise<CommandHandlerResult>;
 export declare function handleReinitGrok(): Promise<CommandHandlerResult>;
 export declare function handleStatus(): Promise<CommandHandlerResult>;
 export declare function handleNew(args: string[]): Promise<CommandHandlerResult>;

package/dist/commands/handlers/missing-handlers.js

@@ -660,17 +660,40 @@ Use /checkpoints to see available checkpoints.`,
 // ============================================================================
 // /init - Initialize Code Buddy Project
 // ============================================================================
-export async function handleInitGrok() {
+export async function handleInitGrok(args = []) {
     try {
-        const { initCodeBuddyProject, formatInitResult } = await import('../../utils/init-project.js');
+        const fast = args.some((a) => a === '--fast' || a === '-f');
+        const { initCodeBuddyProject, formatInitResult, buildInitPrompt } = await import('../../utils/init-project.js');
+        // Deterministic scaffolding first (.codebuddy plumbing + template files,
+        // skip-if-exists). This always runs, so the config + a baseline AGENTS.md exist.
         const initResult = await initCodeBuddyProject();
+        if (fast) {
+            // --fast: deterministic template only (the legacy behavior).
+            return {
+                handled: true,
+                entry: { type: 'assistant', content: formatInitResult(initResult), timestamp: new Date() },
+            };
+        }
+        // Default: hand off to the agent to read the code and write a tailored
+        // AGENTS.md, grounded on the RepoProfiler's verified facts.
+        let contextPack = '';
+        try {
+            const { getRepoProfiler } = await import('../../agent/repo-profiler.js');
+            const profile = await getRepoProfiler().getProfile();
+            contextPack = profile.contextPack ?? '';
+        }
+        catch {
+            /* profiler optional — the prompt still works without the facts block */
+        }
         return {
             handled: true,
             entry: {
                 type: 'assistant',
-                content: formatInitResult(initResult),
+                content: `${formatInitResult(initResult)}\n\nNow analyzing the repository to write a tailored \`AGENTS.md\`… (run \`/init --fast\` for the deterministic template only)`,
                 timestamp: new Date(),
             },
+            passToAI: true,
+            prompt: buildInitPrompt(contextPack),
         };
     }
     catch (error) {

package/dist/commands/skills-cli/index.js

@@ -688,6 +688,129 @@ export function registerSkillsCommands(program) {
             console.log(`  ! ${error}`);
         }
     });
+    // ── Import external skills (Hermes / a repository), firewall-gated ──────────
+    skills
+        .command('import')
+        .description('Import external skills from a directory or a named source (firewall-gated)')
+        .option('--dir <path>', 'import from a local directory')
+        .option('--source <name>', 'import from a named source (see `skills sources`)')
+        .option('--apply', 'install (default is a dry run)')
+        .option('--include-review', "also import skills the firewall flags as 'review'")
+        .option('--overwrite', 'overwrite an already-imported skill')
+        .option('--category <c>', 'only import skills whose path contains this')
+        .option('--json', 'output JSON')
+        .action(async (opts) => {
+        const { importSkills } = await import('../../skills/skill-importer.js');
+        const { getSource, resolveSourceDir } = await import('../../skills/skill-sources.js');
+        let dir;
+        let label = 'import';
+        if (opts.dir) {
+            dir = opts.dir.startsWith('~') ? path.join(os.homedir(), opts.dir.slice(1)) : opts.dir;
+            label = path.basename(dir);
+        }
+        else if (opts.source) {
+            const src = getSource(opts.source);
+            if (!src) {
+                console.log(`Unknown source: ${opts.source} (see \`buddy skills sources list\`)`);
+                return;
+            }
+            dir = resolveSourceDir(src);
+            label = src.name;
+        }
+        else {
+            console.log('Specify --dir <path> or --source <name>.');
+            return;
+        }
+        const fs = await import('fs');
+        if (!fs.existsSync(dir)) {
+            console.log(`Directory not found: ${dir}`);
+            return;
+        }
+        const report = importSkills(dir, {
+            source: label,
+            dryRun: opts.apply !== true,
+            includeReview: opts.includeReview === true,
+            overwrite: opts.overwrite === true,
+            ...(opts.category ? { category: opts.category } : {}),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ source: label, report }, null, 2));
+            return;
+        }
+        console.log(report.dryRun ? `Dry run (use --apply to install) — "${label}"` : `Imported from "${label}"`);
+        console.log(`  ${report.dryRun ? 'would import' : 'imported'}: ${report.imported.length} · quarantined: ${report.quarantined.length} · review: ${report.review.length} · skipped: ${report.skipped.length}`);
+        if (report.quarantined.length) {
+            console.log('  ⚠️  quarantined by firewall:');
+            for (const q of report.quarantined.slice(0, 15))
+                console.log(`     - ${q.sourcePath}`);
+        }
+        if (report.imported.length) {
+            console.log(`  ✓ ${report.dryRun ? 'would import' : 'imported'}:`);
+            for (const s of report.imported.slice(0, 30))
+                console.log(`     - ${s.name}`);
+        }
+    });
+    skills
+        .command('imported')
+        .description('List imported skills (with provenance + pinned status)')
+        .option('--json', 'output JSON')
+        .action(async (opts) => {
+        const fs = await import('fs');
+        const { parseSkillFile } = await import('../../skills/parser.js');
+        const root = path.join(os.homedir(), '.codebuddy', 'skills', 'managed');
+        const items = [];
+        if (fs.existsSync(root)) {
+            for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+                if (!e.isDirectory() || !e.name.startsWith('imported-'))
+                    continue;
+                const md = path.join(root, e.name, 'SKILL.md');
+                if (!fs.existsSync(md))
+                    continue;
+                let pinned = false;
+                let source;
+                try {
+                    const sk = parseSkillFile(fs.readFileSync(md, 'utf-8'), md, 'managed');
+                    pinned = sk.metadata.pinned === true;
+                    source = sk.metadata.source;
+                }
+                catch { /* ignore */ }
+                items.push({ name: e.name, pinned, ...(source ? { source } : {}) });
+            }
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ imported: items }, null, 2));
+            return;
+        }
+        console.log(items.length ? items.map((s) => `  ${s.pinned ? '📌' : '  '} ${s.name}${s.source ? ` (source: ${s.source})` : ''}`).join('\n') : 'No imported skills');
+    });
+    const sources = skills.command('sources').description('Manage skill sources (the import referential)');
+    sources
+        .command('list')
+        .option('--json', 'output JSON')
+        .action(async (opts) => {
+        const { listSources } = await import('../../skills/skill-sources.js');
+        const list = listSources();
+        if (opts.json) {
+            console.log(JSON.stringify({ sources: list }, null, 2));
+            return;
+        }
+        console.log(list.length ? list.map((s) => `  ${s.name}  [${s.type}]  ${s.location}`).join('\n') : 'No skill sources configured');
+    });
+    sources
+        .command('add <name> <location>')
+        .description('Register a skill source (a local dir or a git url)')
+        .option('--type <type>', "'dir' or 'git'")
+        .action(async (name, location, opts) => {
+        const { addSource } = await import('../../skills/skill-sources.js');
+        const src = addSource(name, location, opts.type);
+        console.log(`Added source ${src.name} [${src.type}] → ${src.location}`);
+    });
+    sources
+        .command('remove <name>')
+        .action(async (name) => {
+        const { removeSource } = await import('../../skills/skill-sources.js');
+        console.log(removeSource(name) ? `Removed source ${name}` : `No such source: ${name}`);
+    });
 }
 async function toggleSkill(name, enabled, opts) {
     const { getSkillsHub } = await import('../../skills/hub.js');

package/dist/commands/slash/builtin-commands.js

@@ -42,7 +42,7 @@ const coreCommands = [
     },
     {
         name: 'init',
-        description: 'Initialize .codebuddy directory with templates',
+        description: 'Scaffold .codebuddy, then analyze the repo and write a tailored AGENTS.md (use `--fast` for the deterministic template only)',
         prompt: '__INIT_GROK__',
         filePath: '',
         isBuiltin: true

package/dist/companion/percepts.js

@@ -1,4 +1,4 @@
-import { appendFile, mkdir, readFile, stat } from 'fs/promises';
+import { appendFile, mkdir, readFile, rename, stat } from 'fs/promises';
 import * as crypto from 'crypto';
 import * as path from 'path';
 const DEFAULT_RECENT_LIMIT = 10;
@@ -138,6 +138,16 @@ export async function recordCompanionPercept(input, options = {}) {
         }
         : percept;
     await mkdir(path.dirname(storePath), { recursive: true });
+    // Rotate when large (the disk-guard lesson, mirroring dreams.jsonl): a long-running
+    // companion appends a percept per event, so cap growth + keep one backup.
+    try {
+        const info = await stat(storePath);
+        if (info.size > 1024 * 1024)
+            await rename(storePath, `${storePath}.1`);
+    }
+    catch {
+        /* no file yet */
+    }
     await appendFile(storePath, `${JSON.stringify(storedPercept)}\n`, 'utf8');
     return percept;
 }

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/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
 // ============================================================================