@kentwynn/kgraph 0.1.21 → 0.1.22

package/README.md

@@ -63,6 +63,14 @@ kgraph "blog admin token usage"
 
 Instead of reading the whole repo, it gets a compact starting point: relevant files, symbols, relationships, domains, prior notes, and stale references to watch.
 
+When you need change impact instead of broad context:
+
+```bash
+kgraph impact Button
+```
+
+That shows matched files/symbols, files importing the target, known callers/callees, related cognition, and simple risk signals.
+
 ## Install
 
 Use the published CLI:
@@ -143,14 +151,21 @@ kgraph doctor
 kgraph doctor --quality
 ```
 
-Checks whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use `--quality` when context shows stale/noisy cognition references.
+Checks whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use `--quality` when context shows stale/noisy cognition references, unresolved local imports, unresolved call edges, duplicate cognition titles, or generated files in the scan.
 
 ```bash
 kgraph repair --dry-run
 kgraph repair
 ```
 
-`repair --dry-run` previews cleanup for noisy cognition references, such as framework names recorded as files or local variables recorded as symbols. `repair` applies that cleanup. Run repair intentionally when stale references make context noisy; it is not part of every normal workflow.
+`repair --dry-run` previews cleanup for noisy cognition references, such as framework names recorded as files or local variables recorded as symbols. `repair` applies only the safe noisy-reference cleanup; broader quality findings stay report-only. Run repair intentionally when stale references make context noisy; it is not part of every normal workflow.
+
+```bash
+kgraph impact "Button"
+kgraph impact "createSession" --json
+```
+
+Show practical impact for a file, symbol, or topic: matched files/symbols, import users, callers, callees, ownership edges, related cognition, and risk hints.
 
 ## Optional Step Commands
 
@@ -187,10 +202,11 @@ Open the local interactive dependency graph at `http://localhost:4242`.
 ```bash
 kgraph history
 kgraph history --last 10
+kgraph history "blog button"
 kgraph history --json
 ```
 
-Show processed cognition sessions.
+Show processed cognition sessions. Add a query to find historical work by title, summary, file, symbol, or note body.
 
 ## AI Tool Integrations
 
@@ -319,6 +335,7 @@ The release workflow builds, tests, packs, publishes the npm package on version
 - Explicit: no daemon and no hidden background process.
 - Inspectable: generated knowledge is JSON, YAML, and Markdown.
 - Deterministic first: useful ranking without requiring embeddings or a model.
+- Practical impact: context, history, quality, and impact commands should answer coding questions directly from local maps.
 - Assistant-friendly: one normal command, with lower-level commands available when needed.
 
 ## Roadmap

package/dist/cli/commands/doctor.js

@@ -111,6 +111,10 @@ export function printQualityReport(report) {
     console.log(`Mixed/stale/unresolved notes: ${report.mixedOrStaleCount}`);
     console.log(`Noisy file refs: ${report.noisyFileRefCount}`);
     console.log(`Noisy symbol refs: ${report.noisySymbolRefCount}`);
+    console.log(`Unresolved local imports: ${report.unresolvedLocalImportCount}`);
+    console.log(`Unresolved call edges: ${report.unresolvedCallCount}`);
+    console.log(`Duplicate cognition titles: ${report.duplicateTitleCount}`);
+    console.log(`Generated files scanned: ${report.generatedFileScanCount}`);
     if (report.changes.length === 0) {
         return;
     }

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

@@ -3,6 +3,8 @@ export interface HistoryEntry {
     timestamp: Date;
     filename: string;
     title: string;
+    summary?: string;
+    text?: string;
     author?: string;
 }
 export declare function registerHistoryCommand(program: Command): void;
@@ -13,4 +15,4 @@ export declare function readHistoryEntries(processedPath: string, rootPath: stri
  * (colons and dot replaced by dashes when written to disk)
  */
 export declare function parseTimestampFromFilename(filename: string): Date | undefined;
-export declare function renderHistory(entries: HistoryEntry[], useColor?: boolean): string;
+export declare function renderHistory(entries: HistoryEntry[], useColor?: boolean, query?: string): string;

package/dist/cli/commands/history.js

@@ -4,32 +4,43 @@ import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { assertWorkspace, pathExists } from '../../storage/kgraph-paths.js';
+import { rankByFields } from '../../context/ranking.js';
 import { KGraphError, runCommand } from '../errors.js';
 const execFileAsync = promisify(execFile);
 export function registerHistoryCommand(program) {
     program
-        .command('history')
+        .command('history [query...]')
         .description('Show a timeline of processed cognition sessions')
         .option('--last <n>', 'Show only the last N entries')
         .option('--json', 'Print JSON output')
-        .action((options) => runCommand(async () => {
+        .action((queryParts = [], options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const entries = await readHistoryEntries(workspace.processedInteractionsPath, workspace.rootPath);
+        const query = queryParts.join(' ').trim();
         const limit = options.last !== undefined ? parseInt(options.last, 10) : 0;
         if (options.last !== undefined && (isNaN(limit) || limit < 1)) {
             throw new KGraphError('--last must be a positive integer.');
         }
-        const shown = limit > 0 ? entries.slice(-limit) : entries;
+        const matched = query
+            ? rankByFields(query, entries, [
+                { name: 'title', value: (entry) => entry.title },
+                { name: 'summary', value: (entry) => entry.summary },
+                { name: 'content', value: (entry) => entry.text },
+                { name: 'filename', value: (entry) => entry.filename },
+            ]).map((entry) => entry.item)
+            : entries;
+        const shown = limit > 0 ? matched.slice(-limit) : matched;
         if (options.json) {
             console.log(JSON.stringify(shown.map((e) => ({
                 timestamp: e.timestamp.toISOString(),
                 filename: e.filename,
                 title: e.title,
+                ...(e.summary !== undefined ? { summary: e.summary } : {}),
                 ...(e.author !== undefined ? { author: e.author } : {}),
             })), null, 2));
         }
         else {
-            console.log(renderHistory(shown));
+            console.log(renderHistory(shown, undefined, query));
         }
     }));
 }
@@ -50,9 +61,10 @@ export async function readHistoryEntries(processedPath, rootPath) {
         const filePath = path.join(processedPath, filename);
         const content = await readFile(filePath, 'utf8');
         const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? filename;
+        const summary = content.match(/^## Summary\s+([\s\S]*?)(?:\n## |\n# |$)/m)?.[1]?.trim();
         const relPath = path.relative(rootPath, filePath);
         const author = await getGitAuthor(rootPath, relPath);
-        entries.push({ timestamp, filename, title, author });
+        entries.push({ timestamp, filename, title, summary, text: content, author });
     }
     return entries;
 }
@@ -69,14 +81,14 @@ export function parseTimestampFromFilename(filename) {
     const d = new Date(iso);
     return isNaN(d.getTime()) ? undefined : d;
 }
-export function renderHistory(entries, useColor = supportsColor()) {
+export function renderHistory(entries, useColor = supportsColor(), query = '') {
     const chalk = new Chalk({ level: useColor ? 3 : 0 });
     if (entries.length === 0) {
         return ('\n' +
             chalk.dim('  No processed cognition notes found. Write Markdown notes to .kgraph/inbox/ and run `kgraph update`.') +
             '\n');
     }
-    const header = `  ${chalk.bold('KGraph History')}  ${chalk.dim(`· ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`)}`;
+    const header = `  ${chalk.bold('KGraph History')}  ${chalk.dim(`· ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}${query ? ` matching "${query}"` : ''}`)}`;
     const lines = ['', header, ''];
     const titleWidth = Math.max(...entries.map((e) => e.title.length));
     for (const entry of entries) {
@@ -86,6 +98,9 @@ export function renderHistory(entries, useColor = supportsColor()) {
             ? chalk.cyan(`by ${entry.author}`)
             : chalk.dim('(uncommitted)');
         lines.push(`  ${when}   ${title}  ${who}`);
+        if (entry.summary) {
+            lines.push(`  ${chalk.dim(entry.summary.split('\n')[0])}`);
+        }
     }
     lines.push('');
     return lines.join('\n');

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

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { type ImpactResponse } from '../../context/impact.js';
+export declare function registerImpactCommand(program: Command): void;
+export declare function renderImpactMarkdown(response: ImpactResponse): string;

package/dist/cli/commands/impact.js

@@ -0,0 +1,51 @@
+import { loadConfig } from '../../config/config.js';
+import { analyzeImpact } from '../../context/impact.js';
+import { readCognitionNotes } from '../../storage/cognition-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerImpactCommand(program) {
+    program
+        .command('impact <query>')
+        .description('Show practical impact for a file, symbol, or topic')
+        .option('--json', 'Print JSON output')
+        .action((query, options) => runCommand(async () => {
+        if (!query.trim()) {
+            throw new KGraphError('Query cannot be empty.');
+        }
+        const workspace = await assertWorkspace(process.cwd());
+        if (!(await mapsExist(workspace))) {
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+        }
+        const [config, maps, cognition] = await Promise.all([
+            loadConfig(workspace),
+            readMaps(workspace),
+            readCognitionNotes(workspace),
+        ]);
+        const response = analyzeImpact(query, maps, cognition, config.maxContextItems);
+        console.log(options.json ? JSON.stringify(response, null, 2) : renderImpactMarkdown(response));
+    }));
+}
+export function renderImpactMarkdown(response) {
+    const lines = [`# KGraph Impact`, ``, `Query: ${response.query}`, ``];
+    lines.push('## Matched Files', '');
+    lines.push(...formatList(response.files.map((file) => `- ${file.item.path} (${file.reasons.join(', ')})`)));
+    lines.push('', '## Matched Symbols', '');
+    lines.push(...formatList(response.symbols.map((symbol) => `- ${symbol.item.name} in ${symbol.item.filePath}`)));
+    lines.push('', '## Imported By', '');
+    lines.push(...formatList(response.importedBy.map((file) => `- ${file}`)));
+    lines.push('', '## Called By', '');
+    lines.push(...formatList(response.callers.map((rel) => `- ${rel.sourceId} calls ${rel.targetId} (${rel.confidence})`)));
+    lines.push('', '## Calls', '');
+    lines.push(...formatList(response.calls.map((rel) => `- ${rel.sourceId} calls ${rel.targetId} (${rel.confidence})`)));
+    lines.push('', '## Ownership', '');
+    lines.push(...formatList(response.ownership.map((rel) => `- ${rel.sourceId} owns ${rel.targetId} (${rel.confidence})`)));
+    lines.push('', '## Related Cognition', '');
+    lines.push(...formatList(response.relatedCognition.map((note) => `- ${note.title} [${note.referencesStatus}]`)));
+    lines.push('', '## Risk', '');
+    lines.push(...formatList(response.risk.map((item) => `- ${item}`)));
+    return lines.join('\n');
+}
+function formatList(items) {
+    return items.length > 0 ? items : ['- None'];
+}

package/dist/cli/help.js

@@ -28,13 +28,14 @@ export function renderRootHelp(useColor = supportsColor()) {
         theme.bold('Workflows'),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
         command('context "auth token refresh"', 'Optional: return context without scanning or updating'),
+        command('impact "Button"', 'Show imports, callers, calls, cognition, and risk'),
         command('update', 'Optional: process only .kgraph/inbox Markdown cognition notes'),
         command('doctor', 'Check workspace health and next actions'),
         command('doctor --quality', 'Report stale/noisy cognition references'),
         command('repair --dry-run', 'Preview cognition reference cleanup'),
         command('repair', 'Clean noisy stale cognition references'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
-        command('history', 'Timeline of processed cognition sessions'),
+        command('history "blog button"', 'Search processed cognition sessions'),
         '',
         theme.bold('Integrations'),
         command('integrate list', 'Show configured AI tool integrations'),

package/dist/cli/index.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { registerContextCommand } from './commands/context.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerHistoryCommand } from './commands/history.js';
+import { registerImpactCommand } from './commands/impact.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
 import { registerRepairCommand } from './commands/repair.js';
@@ -39,6 +40,7 @@ export function createProgram() {
     registerScanCommand(program);
     registerUpdateCommand(program);
     registerContextCommand(program);
+    registerImpactCommand(program);
     registerIntegrateCommand(program);
     registerVisualizeCommand(program);
     registerHistoryCommand(program);

package/dist/cognition/cognition-quality.d.ts

@@ -1,6 +1,6 @@
 import type { KGraphWorkspace } from '../types/config.js';
 import type { ReferenceStatus } from '../types/cognition.js';
-import type { FileMap, SymbolMap } from '../types/maps.js';
+import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from '../types/maps.js';
 export interface CognitionRepairChange {
     noteId: string;
     title: string;
@@ -13,13 +13,21 @@ export interface CognitionQualityReport {
     mixedOrStaleCount: number;
     noisyFileRefCount: number;
     noisySymbolRefCount: number;
+    unresolvedLocalImportCount: number;
+    unresolvedCallCount: number;
+    duplicateTitleCount: number;
+    generatedFileScanCount: number;
     changes: CognitionRepairChange[];
 }
 export declare function analyzeCognitionQuality(workspace: KGraphWorkspace, maps: {
     fileMap: FileMap;
     symbolMap: SymbolMap;
+    dependencyMap?: DependencyMap;
+    relationshipMap?: RelationshipMap;
 }): Promise<CognitionQualityReport>;
 export declare function repairCognition(workspace: KGraphWorkspace, maps: {
     fileMap: FileMap;
     symbolMap: SymbolMap;
+    dependencyMap?: DependencyMap;
+    relationshipMap?: RelationshipMap;
 }, dryRun?: boolean): Promise<CognitionQualityReport>;

package/dist/cognition/cognition-quality.js

@@ -10,6 +10,10 @@ export async function analyzeCognitionQuality(workspace, maps) {
         mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
+        unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
+        unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
+        duplicateTitleCount: countDuplicateTitles(notes),
+        generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         changes,
     };
 }
@@ -37,9 +41,51 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
+        unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
+        unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
+        duplicateTitleCount: countDuplicateTitles(nextNotes),
+        generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         changes,
     };
 }
+function countUnresolvedLocalImports(dependencyMap) {
+    return (dependencyMap?.dependencies.filter((dependency) => dependency.kind === 'local' && !dependency.resolvedFile).length ?? 0);
+}
+function countUnresolvedCalls(symbolMap, relationshipMap) {
+    const symbolIds = new Set(symbolMap.symbols.map((symbol) => symbol.id));
+    const symbolNames = new Set(symbolMap.symbols.map((symbol) => symbol.name));
+    return (relationshipMap?.relationships.filter((relationship) => relationship.relationshipType === 'calls' &&
+        relationship.targetType === 'symbol' &&
+        !symbolIds.has(relationship.targetId) &&
+        !symbolNames.has(relationship.targetId) &&
+        ![...symbolNames].some((name) => relationship.targetId.endsWith(`#${name}`))).length ?? 0);
+}
+function countDuplicateTitles(notes) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const note of notes) {
+        const key = note.title.trim().toLowerCase();
+        if (!key)
+            continue;
+        if (seen.has(key))
+            duplicates.add(key);
+        seen.add(key);
+    }
+    return duplicates.size;
+}
+function countGeneratedScannedFiles(fileMap) {
+    return fileMap.files.filter((file) => [
+        '.agents/',
+        '.claude/',
+        '.cursor/',
+        '.windsurf/',
+        '.clinerules/',
+        '.github/prompts/',
+        'AGENTS.md',
+        'CLAUDE.md',
+        'GEMINI.md',
+    ].some((prefix) => file.path === prefix || file.path.startsWith(prefix))).length;
+}
 function analyzeNote(note, maps) {
     const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
     const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));

package/dist/context/context-query.js

@@ -12,6 +12,7 @@ export async function queryContext(workspace, config, maps, query) {
         { name: 'name', value: (symbol) => symbol.name },
         { name: 'path', value: (symbol) => symbol.filePath },
         { name: 'kind', value: (symbol) => symbol.kind },
+        { name: 'parent', value: (symbol) => symbol.parentName },
     ]).slice(0, max);
     const relevantCognition = rankByFields(query, cognition, [
         { name: 'title', value: (note) => note.title },

package/dist/context/impact.d.ts

@@ -0,0 +1,20 @@
+import type { CognitionNote } from '../types/cognition.js';
+import type { DependencyMap, FileMap, Relationship, RelationshipMap, SymbolMap } from '../types/maps.js';
+import { type Ranked } from './ranking.js';
+export interface ImpactResponse {
+    query: string;
+    files: Ranked<FileMap['files'][number]>[];
+    symbols: Ranked<SymbolMap['symbols'][number]>[];
+    importedBy: string[];
+    callers: Relationship[];
+    calls: Relationship[];
+    ownership: Relationship[];
+    relatedCognition: CognitionNote[];
+    risk: string[];
+}
+export declare function analyzeImpact(query: string, maps: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+    dependencyMap: DependencyMap;
+    relationshipMap: RelationshipMap;
+}, cognition: CognitionNote[], max?: number): ImpactResponse;

package/dist/context/impact.js

@@ -0,0 +1,72 @@
+import { rankByFields } from './ranking.js';
+export function analyzeImpact(query, maps, cognition, max = 8) {
+    const files = rankByFields(query, maps.fileMap.files, [
+        { name: 'path', value: (file) => file.path },
+        { name: 'language', value: (file) => file.language },
+    ]).slice(0, max);
+    const symbols = rankByFields(query, maps.symbolMap.symbols, [
+        { name: 'name', value: (symbol) => symbol.name },
+        { name: 'path', value: (symbol) => symbol.filePath },
+        { name: 'kind', value: (symbol) => symbol.kind },
+        { name: 'parent', value: (symbol) => symbol.parentName },
+    ]).slice(0, max);
+    const filePaths = new Set([
+        ...files.map((file) => file.item.path),
+        ...symbols.map((symbol) => symbol.item.filePath),
+    ]);
+    const symbolIds = new Set(symbols.map((symbol) => symbol.item.id));
+    const symbolNames = new Set(symbols.map((symbol) => symbol.item.name));
+    const importHints = new Set([
+        ...[...filePaths].map((file) => basenameWithoutExtension(file).toLowerCase()),
+        ...[...symbolNames].map((name) => name.toLowerCase()),
+    ]);
+    const importedBy = unique(maps.dependencyMap.dependencies
+        .filter((dep) => (dep.resolvedFile && filePaths.has(dep.resolvedFile)) ||
+        [...importHints].some((hint) => hint && dep.specifier.toLowerCase().includes(hint)))
+        .map((dep) => dep.fromFile)).slice(0, max);
+    const calls = maps.relationshipMap.relationships
+        .filter((rel) => rel.relationshipType === 'calls' &&
+        (symbolIds.has(rel.sourceId) || symbolNames.has(rel.sourceId)))
+        .slice(0, max);
+    const callers = maps.relationshipMap.relationships
+        .filter((rel) => rel.relationshipType === 'calls' &&
+        (symbolIds.has(rel.targetId) || symbolNames.has(rel.targetId) || [...symbolNames].some((name) => rel.targetId.endsWith(`#${name}`))))
+        .slice(0, max);
+    const ownership = maps.relationshipMap.relationships
+        .filter((rel) => rel.relationshipType === 'symbol-contains' &&
+        (symbolIds.has(rel.sourceId) || symbolIds.has(rel.targetId)))
+        .slice(0, max);
+    const relatedCognition = cognition
+        .filter((note) => note.relatedFiles.some((file) => filePaths.has(file)) ||
+        note.relatedSymbols.some((symbol) => symbolNames.has(symbol) || symbolIds.has(symbol)))
+        .slice(0, max);
+    const risk = [];
+    if (importedBy.length > 2)
+        risk.push(`Shared file imported by ${importedBy.length} files`);
+    if (callers.length > 2)
+        risk.push(`Symbol called by ${callers.length} known callers`);
+    if (relatedCognition.some((note) => note.referencesStatus !== 'current')) {
+        risk.push('Related cognition has stale or mixed references');
+    }
+    if (calls.some((rel) => rel.confidence === 'low') || callers.some((rel) => rel.confidence === 'low')) {
+        risk.push('Some call relationships are low confidence');
+    }
+    return {
+        query,
+        files,
+        symbols,
+        importedBy,
+        callers,
+        calls,
+        ownership,
+        relatedCognition,
+        risk,
+    };
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+function basenameWithoutExtension(filePath) {
+    const basename = filePath.split('/').pop() ?? filePath;
+    return basename.replace(/\.[^.]+$/, '');
+}

package/dist/context/ranking.js

@@ -1,9 +1,9 @@
 export function tokenize(query) {
-    return query
+    return expandTokens(query
         .toLowerCase()
         .split(/[^a-z0-9_$./-]+/)
         .map((token) => token.trim())
-        .filter(Boolean);
+        .filter(Boolean));
 }
 export function rankByFields(query, items, fields) {
     const tokens = tokenize(query);
@@ -14,14 +14,19 @@ export function rankByFields(query, items, fields) {
         for (const field of fields) {
             const value = field.value(item);
             const values = Array.isArray(value) ? value : value ? [value] : [];
-            const haystack = values.join(' ').toLowerCase();
+            const haystack = values.flatMap((value) => [value, splitIdentifier(value).join(' ')]).join(' ').toLowerCase();
             for (const token of tokens) {
                 if (haystack.includes(token)) {
-                    const baseScore = field.name === 'path' || field.name === 'name' ? 3 : 1;
+                    const baseScore = field.name === 'path' || field.name === 'name'
+                        ? 4
+                        : field.name === 'summary' || field.name === 'title'
+                            ? 2
+                            : 1;
                     const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
                     const wordBoundary = new RegExp(`\\b${escaped}\\b`).test(haystack);
-                    score += baseScore + (wordBoundary ? 2 : 0);
-                    reasons.push(`${field.name} matched "${token}"${wordBoundary ? ' (exact)' : ''}`);
+                    const exactValue = values.some((value) => value.toLowerCase() === token);
+                    score += baseScore + (wordBoundary ? 2 : 0) + (exactValue ? 4 : 0);
+                    reasons.push(`${field.name} matched "${token}"${wordBoundary || exactValue ? ' (exact)' : ''}`);
                 }
             }
         }
@@ -30,3 +35,13 @@ export function rankByFields(query, items, fields) {
         .filter((ranked) => ranked.score > 0)
         .sort((a, b) => b.score - a.score);
 }
+function expandTokens(tokens) {
+    return [...new Set(tokens.flatMap((token) => [token, ...splitIdentifier(token)]))];
+}
+function splitIdentifier(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^A-Za-z0-9_$]+/)
+        .map((part) => part.toLowerCase())
+        .filter((part) => part.length > 1);
+}

package/dist/integrations/adapters/claude-code.js

@@ -15,13 +15,14 @@ Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intell
 2. Run \`kgraph "<topic>"\`. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
 4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-6. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-7. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-8. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
-9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-10. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-11. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+5. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+6. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+7. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+8. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+9. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+10. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+11. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+12. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -64,11 +65,16 @@ Any implementation or product decision future sessions should know.
         {
             path: '.claude/commands/kgraph-visualize.md',
             content: `Run \`kgraph visualize\` to start an interactive dependency graph at http://localhost:4242. Opens in browser automatically. Use \`--no-open\` to print URL only, \`--port <n>\` for a custom port.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-impact.md',
+            content: `Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
 `,
         },
         {
             path: '.claude/commands/kgraph-history.md',
-            content: `Run \`kgraph history\` to show a timeline of all processed cognition sessions. Includes git author attribution when available. Use \`--last <n>\` to limit entries, \`--json\` for machine-readable output.
+            content: `Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to show processed cognition sessions. Includes git author attribution when available. Use \`--last <n>\` to limit entries, \`--json\` for machine-readable output.
 `,
         },
     ],

package/dist/integrations/adapters/cline.js

@@ -6,12 +6,13 @@ export const clineAdapter = {
 
 - **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
 - At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
 - If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
 - Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
 - Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
 };

package/dist/integrations/adapters/codex.js

@@ -22,13 +22,14 @@ Workflow:
 2. Run \`kgraph "<topic>"\` before broad repo exploration. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
 3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
 4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-6. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-7. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-8. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
-9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-10. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-11. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+5. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+6. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+7. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+8. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+9. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+10. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+11. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+12. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown

package/dist/integrations/adapters/copilot.js

@@ -6,11 +6,12 @@ export const copilotAdapter = {
 
 1. **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
 2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-3. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-4. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-5. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-6. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
-7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+3. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+4. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+5. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+6. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+7. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+8. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -112,6 +113,17 @@ One or two sentences describing what was done.
 ## Decisions
 Any architectural or implementation decisions made.
 \`\`\`
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-impact.prompt.md',
+            content: `---
+description: Show KGraph change impact for a file, symbol, or topic
+agent: agent
+argument-hint: "File, symbol, or topic"
+---
+
+Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
 `,
         },
         {
@@ -119,9 +131,10 @@ Any architectural or implementation decisions made.
             content: `---
 description: Show timeline of KGraph cognition sessions with git attribution
 agent: agent
+argument-hint: "Optional topic"
 ---
 
-Run \`kgraph history\` to display the timeline of all processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
+Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
 `,
         },
     ],

package/dist/integrations/adapters/cursor.js

@@ -11,13 +11,14 @@ alwaysApply: true
 
 - **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
 - At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
 - If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
 - Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
 - Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
     obsoleteCommandFiles: ['.cursor/rules/kgraph-commands.mdc'],
 };

package/dist/integrations/adapters/gemini.js

@@ -6,12 +6,13 @@ export const geminiAdapter = {
 
 - **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
 - At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
 - If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
 - Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
 - Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
 };

package/dist/integrations/adapters/windsurf.js

@@ -6,12 +6,13 @@ export const windsurfAdapter = {
 
 - **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
 - At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
 - If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
 - Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
 - Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {