@kentwynn/kgraph 0.2.15 → 0.2.17

package/README.md

@@ -4,6 +4,8 @@ Persistent repository intelligence for AI coding tools.
 
 KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable knowledge atoms from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
 
+The CLI presents this as **Atom Core**: lightweight local atoms plus deterministic repo maps, context packs, and session history that remain inspectable under `.kgraph/`.
+
 ## The Workflow
 
 Use KGraph in two steps:
@@ -119,12 +121,14 @@ After useful AI work, assistants save durable runtime-capture notes into `.kgrap
 Normal agent flow is intentionally small:
 
 ```bash
-kgraph "topic"
+kgraph pack "topic" --budget 8000 --json
 # work normally
 # if repo files changed, write an inbox note before the final refresh
 kgraph
 ```
 
+`kgraph "<topic>"` remains the human-readable briefing. Agents should prefer `kgraph pack "<topic>" --budget 8000 --json` because it returns the stable `ContextPack` contract with atoms, source ranges, git changes, omitted items, token estimates, and inclusion reasons.
+
 Use `kgraph doctor` after setup and before trusting a repo's saved intelligence. It checks initialization, maps, pending inbox notes, integration targets, and actionable quality problems. Use `kgraph doctor --quality` and `kgraph repair --dry-run` when stale or noisy atom references start making context harder to trust.
 
 Agents can also report session activity so KGraph can estimate token waste:
@@ -247,7 +251,7 @@ kgraph pack "auth token refresh" --budget 8000
 kgraph pack "auth token refresh" --budget 8000 --json
 ```
 
-Build a budget-aware context pack from files, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents.
+Build a budget-aware context pack from files, source ranges, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents; text output is an Atom Core briefing for humans.
 
 ```bash
 kgraph compact --dry-run

package/dist/cli/commands/context.js

@@ -25,11 +25,20 @@ export function registerContextCommand(program) {
     }));
 }
 export function renderContextMarkdown(response) {
-    const lines = [`# KGraph Context`, ``, `Query: ${response.query}`, ``];
-    lines.push('## Matched Domains', '');
-    lines.push(...formatList(response.matchedDomains.map((item) => `- ${item.item.name} because ${formatReasons(item.reasons)}`)));
-    lines.push('', '## Relevant Files', '');
-    lines.push(...formatList(response.relevantFiles.map((item) => {
+    const lines = [
+        `KGraph Context · ${response.query}`,
+        `local-first · deterministic · inspectable`,
+        ``,
+        `● Signal`,
+        `  confidence   ${contextConfidence(response)}`,
+        `  source       ${contextSources(response).join(' + ') || 'file map'}`,
+        `  warnings     ${response.warnings.length > 0 ? response.warnings.length : 'none'}`,
+        ``,
+    ];
+    lines.push('● Matched Domains', '');
+    lines.push(...formatList(response.matchedDomains.map((item) => atomLine(item.item.name, formatReasons(item.reasons)))));
+    lines.push('', '● Source', '');
+    lines.push(...formatList(limited(response.relevantFiles, 5).map((item) => {
         const f = item.item;
         const meta = [
             f.language,
@@ -37,32 +46,34 @@ export function renderContextMarkdown(response) {
         ]
             .filter(Boolean)
             .join(', ');
-        return `- ${f.path}${meta ? ` [${meta}]` : ''} because ${formatReasons(item.reasons)}`;
+        return atomLine(`${f.path}${meta ? ` [${meta}]` : ''}`, formatReasons(item.reasons));
     })));
-    lines.push('', '## Relevant Symbols', '');
-    lines.push(...formatList(response.relevantSymbols.map((item) => {
+    appendMore(lines, response.relevantFiles.length, 5, 'source item');
+    lines.push('', '● Symbols', '');
+    lines.push(...formatList(limited(response.relevantSymbols, 6).map((item) => {
         const s = item.item;
         const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(item.reasons)}`;
+        return atomLine(`${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`, formatReasons(item.reasons));
     })));
-    lines.push('', '## Relevant Cognition', '');
-    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}] because ${formatReasons(item.reasons)}`)));
-    lines.push('', '## Relationships', '');
-    lines.push(...formatGroupedRelationships(response.relationships, response.relationshipExplanations));
-    lines.push('', '## Nearby Symbols (1-hop imports)', '');
+    appendMore(lines, response.relevantSymbols.length, 6, 'symbol');
+    lines.push('', '● Atoms', '');
+    lines.push(...formatList(response.relevantCognition.map((item) => atomLine(`${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}]`, formatReasons(item.reasons)))));
+    lines.push('', '● Graph', '');
+    lines.push(...formatGroupedRelationships(relevantGraphRelationships(response), response.relationshipExplanations));
+    lines.push('', '● Nearby Symbols (1-hop imports)', '');
     lines.push(...formatList(nearbySymbolItems(response).map(({ symbol: s, reasons }) => {
         const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(reasons)}`;
+        return atomLine(`${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`, formatReasons(reasons));
     })));
-    lines.push('', '## Stale References', '');
-    lines.push(...formatList(response.staleReferences.map((ref) => `- ${ref}`)));
-    lines.push('', '## Recent Git Changes', '');
+    lines.push('', '● Stale References', '');
+    lines.push(...formatList(response.staleReferences.map((ref) => `  ◌ ${ref}`)));
+    lines.push('', '● Recent Git Changes', '');
     if (response.gitChanges && response.gitChanges.length > 0) {
         const staged = response.gitChanges.filter((c) => c.status === 'staged');
         const unstaged = response.gitChanges.filter((c) => c.status === 'unstaged');
@@ -70,22 +81,29 @@ export function renderContextMarkdown(response) {
         if (staged.length > 0) {
             lines.push('Staged:');
             for (const c of staged)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
         if (unstaged.length > 0) {
             lines.push('Unstaged:');
             for (const c of unstaged)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
         if (recent.length > 0) {
             lines.push('Recent commits:');
             for (const c of recent)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
     }
     else {
         lines.push('- None');
     }
+    lines.push('', '● Next', '');
+    if (response.relevantFiles.some((item) => (item.item.tokenEstimate ?? 0) > 4000)) {
+        lines.push(`  use budgeted source ranges: kgraph pack "${response.query}" --budget 4000`);
+    }
+    else {
+        lines.push(`  read the ranked source, edit, verify, conclude only if durable knowledge changed`);
+    }
     return lines.join('\n');
 }
 function formatGroupedRelationships(relationships, explanations) {
@@ -105,33 +123,49 @@ function formatGroupedRelationships(relationships, explanations) {
     const lines = [];
     if (imports.length > 0) {
         lines.push('Imports:');
-        for (const r of imports) {
+        for (const r of imports.slice(0, 6)) {
             lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, imports.length, 6, 'import edge');
     }
     if (calls.length > 0) {
         lines.push('Calls:');
-        for (const r of calls) {
+        for (const r of calls.slice(0, 6)) {
             lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, calls.length, 6, 'call edge');
     }
     if (contains.length > 0) {
         lines.push('Contains:');
-        for (const r of contains) {
+        for (const r of contains.slice(0, 6)) {
             lines.push(`  ${r.sourceId} contains ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, contains.length, 6, 'containment edge');
     }
     if (other.length > 0) {
         lines.push('Other:');
-        for (const r of other) {
+        for (const r of other.slice(0, 6)) {
             lines.push(`  ${r.sourceId} ${r.relationshipType} ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, other.length, 6, 'graph edge');
     }
     return lines.length > 0 ? lines : ['- None'];
 }
 function formatList(items) {
     return items.length > 0 ? items : ['- None'];
 }
+function limited(items, count) {
+    return items.slice(0, count);
+}
+function appendMore(lines, total, shown, label) {
+    const remaining = total - shown;
+    if (remaining > 0) {
+        lines.push(`  ◌ ${remaining} more ${label}${remaining === 1 ? '' : 's'} omitted from display`);
+    }
+}
+function atomLine(title, detail) {
+    return `  ● ${title}\n    because ${detail}`;
+}
 function formatReasons(reasons) {
     if (reasons.length === 0) {
         return 'it is near the query';
@@ -151,6 +185,39 @@ function nearbySymbolItems(response) {
         reasons: ['exported symbol from 1-hop import'],
     }));
 }
+function relevantGraphRelationships(response) {
+    const anchorPaths = response.relevantFiles
+        .filter((item) => !item.reasons.some((reason) => reason.includes('generic path-only match penalty')))
+        .slice(0, 3)
+        .map((item) => item.item.path);
+    const paths = anchorPaths.length > 0
+        ? anchorPaths
+        : response.relevantFiles.slice(0, 1).map((item) => item.item.path);
+    if (paths.length === 0)
+        return response.relationships;
+    return response.relationships.filter((relationship) => paths.some((path) => relationship.sourceId.includes(path) ||
+        relationship.targetId.includes(path)));
+}
+function contextConfidence(response) {
+    const confidence = response.relevantCognition
+        .map((item) => item.item.confidence)
+        .find(Boolean);
+    return confidence ?? (response.relevantFiles.length > 0 ? 'medium' : 'low');
+}
+function contextSources(response) {
+    const sources = [];
+    if (response.relevantCognition.length > 0)
+        sources.push('atom');
+    if ((response.gitChanges ?? []).length > 0)
+        sources.push('git change');
+    if (response.relevantSymbols.length > 0)
+        sources.push('symbol');
+    if (relevantGraphRelationships(response).length > 0)
+        sources.push('graph');
+    if (response.relevantFiles.length > 0)
+        sources.push('file');
+    return sources;
+}
 function formatRelationshipReason(relationship, reasonsByRelationship) {
     const reasons = reasonsByRelationship.get(relationshipKey(relationship));
     return reasons && reasons.length > 0

package/dist/cli/commands/pack.d.ts

@@ -1,2 +1,4 @@
 import type { Command } from 'commander';
+import type { ContextPack } from '../../types/knowledge.js';
 export declare function registerPackCommand(program: Command): void;
+export declare function renderPackText(pack: ContextPack): string;

package/dist/cli/commands/pack.js

@@ -31,19 +31,66 @@ export function registerPackCommand(program) {
             console.log(JSON.stringify(pack, null, 2));
             return;
         }
-        console.log(`# KGraph Context Pack`);
-        console.log('');
-        console.log(`Task: ${pack.task}`);
-        console.log(`Budget: ${pack.budget}`);
-        console.log(`Used: ${pack.usedTokens}`);
-        console.log('');
-        for (const item of pack.items) {
-            console.log(`- [${item.kind}] ${item.title} (~${item.tokenEstimate} tokens)`);
-            console.log(`  because ${item.reasons.slice(0, 3).join('; ')}`);
+        console.log(renderPackText(pack));
+    }));
+}
+export function renderPackText(pack) {
+    const lines = [
+        `KGraph Pack · ${pack.task}`,
+        `local-first · budget-aware · machine contract: --json`,
+        ``,
+        `● Budget`,
+        `  used        ${pack.usedTokens} / ${pack.budget}`,
+        `  included    ${pack.items.length}`,
+        `  omitted     ${pack.omitted.length}`,
+        ``,
+    ];
+    appendGroup(lines, 'Atoms', pack.items.filter((item) => item.kind === 'atom'));
+    appendGroup(lines, 'Git Changes', pack.items.filter((item) => item.kind === 'git-change'));
+    appendGroup(lines, 'Source Ranges', pack.items.filter((item) => item.kind === 'file-range'));
+    appendGroup(lines, 'Symbols', pack.items.filter((item) => item.kind === 'symbol'));
+    appendGroup(lines, 'Files', pack.items.filter((item) => item.kind === 'file'));
+    appendGroup(lines, 'Graph', pack.items.filter((item) => item.kind === 'relationship'));
+    lines.push(`● Omitted`);
+    const omitted = pack.omitted.slice(0, 8);
+    if (omitted.length === 0) {
+        lines.push('- None');
+    }
+    else {
+        for (const item of omitted) {
+            lines.push(`  ◌ ${item.kind} ${item.title} (~${item.tokenEstimate} tokens)`);
         }
-        if (pack.omitted.length > 0) {
-            console.log('');
-            console.log(`Omitted: ${pack.omitted.length} item(s) over budget`);
+        if (pack.omitted.length > omitted.length) {
+            lines.push(`  ◌ ${pack.omitted.length - omitted.length} more omitted items`);
         }
-    }));
+    }
+    lines.push('', '● Next', '  agents should consume this command with --json for the full ContextPack contract');
+    return lines.join('\n');
+}
+function appendGroup(lines, title, items) {
+    lines.push(`● ${title}`);
+    if (items.length === 0) {
+        lines.push('- None', '');
+        return;
+    }
+    for (const item of items.slice(0, 6)) {
+        lines.push(`  ● ${item.title} (~${item.tokenEstimate} tokens)`);
+        lines.push(`    because ${formatReasons(item.reasons)}`);
+        if (item.kind === 'file-range') {
+            const data = item.data;
+            if (data.path && data.startLine != null && data.endLine != null) {
+                lines.push(`    range ${data.path}:${data.startLine}-${data.endLine}`);
+            }
+        }
+    }
+    if (items.length > 6)
+        lines.push(`  ◌ ${items.length - 6} more ${title.toLowerCase()} omitted from display`);
+    lines.push('');
+}
+function formatReasons(reasons) {
+    if (reasons.length === 0)
+        return 'included by pack ranking';
+    const shown = reasons.slice(0, 3);
+    const remaining = reasons.length - shown.length;
+    return remaining > 0 ? `${shown.join('; ')}; and ${remaining} more` : shown.join('; ');
 }

package/dist/cli/help.js

@@ -1,31 +1,32 @@
 import { Chalk } from 'chalk';
-import figlet from 'figlet';
 export function renderRootHelp(useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
-    const logo = renderLogo();
+    const accent = atomAccent(theme);
     return [
         '',
-        theme.hex('#7dd3fc').bold(logo),
+        renderAtomLogo(theme),
         '',
-        `  ${theme.bold('KGraph')} ${theme.dim('Persistent repo intelligence for AI coding tools')}`,
+        renderSignalPanel(theme, [
+            ['purpose', 'durable engineering memory for AI coding tools'],
+            ['storage', '.kgraph/ atoms, maps, indexes, and session history'],
+            ['stance', 'local-first · deterministic-first · inspectable'],
+            ['agents', 'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline'],
+        ]),
         '',
-        `  ${theme.hex('#c084fc')('Build a local knowledge layer that helps Codex, Copilot, Cursor,')}`,
-        `  ${theme.hex('#c084fc')('Claude Code, Gemini, Windsurf, and Cline reuse repo intelligence.')}`,
-        '',
-        theme.bold('Usage'),
+        sectionTitle(theme, `${accent} Usage`),
         '  kgraph [topic]',
         '  kgraph <command> [options]',
         '',
-        theme.bold('Start'),
+        sectionTitle(theme, `${accent} Start`),
         command('init', 'Required once: create .kgraph/ workspace'),
         command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
         '',
-        theme.bold('Daily workflow'),
+        sectionTitle(theme, `${accent} Daily workflow`),
         command('kgraph', 'Refresh scan maps and process pending capture notes'),
         command('kgraph "auth token refresh"', 'Refresh everything and return compact context for a topic'),
         '',
-        theme.bold('Workflows'),
+        sectionTitle(theme, `${accent} Workflows`),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
         command('session', 'Show agent read/write activity and token estimates'),
         command('session read src/auth.ts --agent codex', 'Record an agent file read'),
@@ -48,7 +49,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
         '',
-        theme.bold('Integrations'),
+        sectionTitle(theme, `${accent} Integrations`),
         command('integrate list', 'Show configured AI tool integrations'),
         command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
         command('integrate add copilot --mode smart', 'Run KGraph for repo-specific Copilot work only'),
@@ -56,21 +57,24 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
         '',
-        theme.bold('Options'),
+        sectionTitle(theme, `${accent} Options`),
         command('-V, --version', 'Show version'),
         command('-h, --help', 'Show this help'),
         '',
-        `${theme.yellow('Examples')}`,
+        sectionTitle(theme, `${accent} Examples`),
         '  kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline',
         '  kgraph "blog admin token usage"',
+        '  kgraph pack "about page update" --budget 4000',
         '  kgraph doctor',
         '',
         theme.dim('Docs: https://github.com/kentwynn/KGraph#readme'),
+        theme.dim('Powered by Kent Wynn: https://kentwynn.com'),
         '',
     ].join('\n');
 }
 export function renderWorkflowBanner(stats, useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
+    const accent = atomAccent(theme);
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
     const integrationLine = stats.integrations && stats.integrations.length > 0
         ? stats.integrations
@@ -81,11 +85,11 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         : 'none configured';
     return [
         '',
-        theme.hex('#7dd3fc').bold(renderLogo()),
+        renderAtomLogo(theme),
         '',
-        `  ${theme.bold('KGraph')} ${theme.dim('repo intelligence refreshed')}`,
+        `  ${theme.bold('KGraph')} ${theme.dim('· repo intelligence refreshed')}`,
         '',
-        theme.bold('Refresh Complete'),
+        sectionTitle(theme, `${accent} Refresh Complete`),
         command('files', String(stats.files) +
             (stats.skippedFiles
                 ? ` (${stats.skippedFiles} unchanged, skipped)`
@@ -94,7 +98,7 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('capture notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),
         '',
-        theme.bold('Next'),
+        sectionTitle(theme, `${accent} Next`),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
         command('kgraph doctor --quality', 'Check atom quality'),
@@ -104,17 +108,27 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('kgraph --help', 'Show all commands'),
     ].join('\n');
 }
-function renderLogo() {
-    try {
-        return figlet.textSync('KGraph', {
-            font: 'ANSI Shadow',
-            horizontalLayout: 'default',
-            verticalLayout: 'default',
-        });
-    }
-    catch {
-        return 'KGraph';
-    }
+function renderAtomLogo(theme) {
+    const title = `${theme.hex('#38bdf8').bold('KGraph')} ${theme.dim('·')} ${theme.hex('#c084fc').bold('Atom Core')}`;
+    const atom = theme.hex('#22d3ee').bold('⚛');
+    const memory = theme.hex('#a78bfa')('persistent repo intelligence for AI coding tools');
+    return [
+        `  ${atom}  ${theme.dim('atoms · evidence · context packs')}`,
+        `     ${title}`,
+        `     ${memory}`,
+    ].join('\n');
+}
+function renderSignalPanel(theme, rows) {
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    return rows
+        .map(([label, value]) => `  ${theme.hex('#22d3ee')('●')} ${theme.bold(label.padEnd(labelWidth))}  ${theme.dim(value)}`)
+        .join('\n');
+}
+function sectionTitle(theme, title) {
+    return theme.bold(title);
+}
+function atomAccent(theme) {
+    return theme.hex('#22d3ee')('●');
 }
 function supportsColor() {
     return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;

package/dist/context/context-pack.js

@@ -53,10 +53,15 @@ export function buildContextPack(response, budget, rootPath) {
         })),
     ];
     const orderedCandidates = candidates.sort(comparePackCandidates);
+    const strongPaths = strongPackPaths(candidates);
     const items = [];
     const omitted = [];
     let usedTokens = 0;
     for (const candidate of orderedCandidates) {
+        if (isLowSignalCandidate(candidate, strongPaths)) {
+            omitted.push(candidate);
+            continue;
+        }
         if (usedTokens + candidate.tokenEstimate <= budget) {
             items.push(candidate);
             usedTokens += candidate.tokenEstimate;
@@ -102,6 +107,60 @@ function packPriority(item) {
     score -= Math.floor(item.tokenEstimate / 2000);
     return score;
 }
+function strongPackPaths(candidates) {
+    const paths = new Set();
+    for (const candidate of candidates) {
+        if (candidate.kind === 'file-range' || candidate.kind === 'git-change') {
+            const pathValue = candidatePath(candidate);
+            if (pathValue)
+                paths.add(pathValue);
+        }
+        if (candidate.kind === 'file' && hasStrongReason(candidate)) {
+            const pathValue = candidatePath(candidate);
+            if (pathValue)
+                paths.add(pathValue);
+        }
+        if (candidate.kind === 'atom') {
+            const atom = candidate.data;
+            for (const file of atom?.relatedFiles ?? [])
+                paths.add(file);
+        }
+    }
+    return paths;
+}
+function isLowSignalCandidate(candidate, strongPaths) {
+    if (strongPaths.size === 0)
+        return false;
+    if (candidate.kind === 'atom' || candidate.kind === 'git-change' || candidate.kind === 'file-range') {
+        return false;
+    }
+    if (hasStrongReason(candidate))
+        return false;
+    if (candidateTouchesStrongPath(candidate, strongPaths))
+        return false;
+    return candidate.kind === 'file' || candidate.kind === 'symbol' || candidate.kind === 'relationship';
+}
+function hasStrongReason(candidate) {
+    return candidate.reasons.some((reason) => reason.includes('matched atom') ||
+        reason.includes('current git change') ||
+        reason.includes('changed in recent commits') ||
+        reason.includes('unstaged change') ||
+        reason.includes('staged change'));
+}
+function candidateTouchesStrongPath(candidate, strongPaths) {
+    const pathValue = candidatePath(candidate);
+    if (pathValue && strongPaths.has(pathValue))
+        return true;
+    if (candidate.kind !== 'relationship')
+        return false;
+    const relationship = candidate.data;
+    return [...strongPaths].some((strongPath) => relationship.sourceId?.includes(strongPath) ||
+        relationship.targetId?.includes(strongPath));
+}
+function candidatePath(candidate) {
+    const data = candidate.data;
+    return data?.path ?? data?.filePath;
+}
 const GENERIC_RANGE_TOKENS = new Set([
     'app',
     'code',

package/dist/integrations/instruction-blocks.js

@@ -36,17 +36,17 @@ export function applyContextPolicy(content, mode) {
         .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy());
 }
 export function renderContextPolicy(mode) {
-    const useResultBoundary = 'Use the returned KGraph candidate files as the first-pass source of truth. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file is identified, do not retry malformed shell commands with broader variants, and do not run broad `find`, recursive `grep`, or repeated full-file dumps after KGraph has narrowed the target.';
+    const useResultBoundary = 'Use the returned KGraph ContextPack items as the first-pass source of truth. Prefer source ranges, atoms, git changes, and inclusion reasons from the pack before broad repository search. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file or range is identified, do not retry malformed shell commands with broader variants, and do not run broad `find`, recursive `grep`, or repeated full-file dumps after KGraph has narrowed the target.';
     switch (mode) {
         case 'always':
-            return `Every chat in this repository must start by running \`kgraph "<topic>"\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. ${useResultBoundary}`;
+            return `Every chat in this repository must start by running \`kgraph pack "<topic>" --budget 8000 --json\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
         case 'manual':
-            return 'Do not run KGraph automatically. Run `kgraph "<topic>"` only when the user explicitly asks for KGraph context or invokes the KGraph command.';
+            return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack.';
         case 'off':
             return 'KGraph is disabled for this integration.';
         case 'smart':
         default:
-            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`kgraph "<topic>"\` before broad repository exploration. Infer the topic from the user's message. Skip KGraph for simple conversational requests that do not depend on repo knowledge. ${useResultBoundary}`;
+            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`kgraph pack "<topic>" --budget 8000 --json\` before broad repository exploration. Infer the topic from the user's message. Skip KGraph for simple conversational requests that do not depend on repo knowledge. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
     }
 }
 export function renderCapturePolicy() {
@@ -56,7 +56,7 @@ export function renderCapturePolicy() {
 - Use \`.kgraph/inbox/<slug>.md\` only when a longer structured note is clearer than a single \`kgraph conclude\` command.
 - A \`.kgraph/inbox/*.md\` note is KGraph runtime capture, not project documentation. It is allowed by this workflow unless the user explicitly says not to capture to KGraph.
 - Do not skip capture for meaningful UI text, button, link, route, styling, or small file edits. Skip capture only when no reusable repository knowledge was created.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph pack "<topic>" --budget 8000 --json\` for agent-readable context. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
 - After the final \`kgraph\` run, mention whether durable cognition was stored or processed.
 
 When using an inbox note, use this structure:

package/dist/integrations/workflow-steps.js

@@ -8,7 +8,7 @@ const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/n
 const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks duplicated, noisy, or stale. Run \`kgraph compact\` only when the user asks to merge/archive cognition.`;
 const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.`;
 const KNOWLEDGE_STEP = `Run \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\` when the user asks what KGraph remembers or atom provenance/lifecycle matters.`;
-const PACK_STEP = `Run \`kgraph pack "<task>" --budget 8000 --json\` when an agent needs a machine-readable, token-budgeted context pack instead of human Markdown context.`;
+const PACK_STEP = `Treat \`kgraph pack "<task>" --budget 8000 --json\` as the primary agent contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. Use human \`kgraph "<topic>"\` output only when the user explicitly wants a briefing.`;
 const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
 const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files. Use \`rg --files\` and quoted paths when a path must be located.`;
 const VERIFY_EDIT_STEP = `After editing, verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -47,7 +47,6 @@
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
-    "figlet": "^1.11.0",
     "tree-sitter-c": "^0.24.1",
     "tree-sitter-c-sharp": "^0.23.5",
     "tree-sitter-cpp": "^0.23.4",