@kentwynn/kgraph 0.1.27 → 0.2.1

package/README.md

@@ -62,6 +62,7 @@ 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.
+Each context item explains why it was returned, such as a path/name match, a matched cognition reference, a domain match, or a nearby import relationship.
 
 When you need change impact instead of broad context:
 
@@ -103,7 +104,7 @@ kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
 # 3. Run the normal workflow for a topic
 kgraph "auth token refresh"
 
-# 4. Check health if something feels off
+# 4. Verify the setup and use doctor as the quality gate
 kgraph doctor
 ```
 
@@ -120,7 +121,7 @@ kgraph "topic"
 kgraph
 ```
 
-Use `kgraph doctor --quality` and `kgraph repair --dry-run` only when stale or noisy cognition references start making context harder to trust.
+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 cognition references start making context harder to trust.
 
 Agents can also report session activity so KGraph can estimate token waste:
 
@@ -167,6 +168,8 @@ 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, unresolved local imports, unresolved call edges, duplicate cognition titles, or generated files in the scan.
 
+The default doctor result is the main quality gate. It fails on actionable hygiene issues such as stale/noisy cognition, duplicate cognition titles, generated integration files leaking into scans, missing maps, or broken integration targets. Scanner coverage counts such as unresolved local imports or unresolved call edges remain visible in `--quality`, but they do not fail the gate by themselves because they often reflect current parser limits.
+
 ```bash
 kgraph repair --dry-run
 kgraph repair
@@ -174,6 +177,14 @@ 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 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 uninstall
+kgraph uninstall --yes
+kgraph uninstall --keep-integrations --yes
+```
+
+`uninstall` previews repo-local removal and does not delete anything unless `--yes` is passed. `uninstall --yes` removes `.kgraph/` and KGraph-managed integration blocks/files while preserving source files and user-authored text outside managed blocks. Use `--keep-integrations --yes` to remove only `.kgraph/` while leaving AI tool instruction files in place. After uninstalling, `kgraph init` can be run again for a fresh setup.
+
 ```bash
 kgraph impact "Button"
 kgraph impact "createSession" --json
@@ -192,6 +203,7 @@ kgraph session end --agent codex
 ```
 
 Track agent-reported read/write activity, repeated reads, and estimated token cost. Supported agents are `codex`, `claude-code`, `copilot`, `cursor`, `gemini`, `windsurf`, and `cline`.
+The text report now includes next actions, such as using `kgraph context "<topic>"` before repeated broad file inspection.
 
 ## Optional Step Commands
 
@@ -209,6 +221,7 @@ kgraph context "auth token refresh" --json
 ```
 
 Return context from existing maps and cognition without scanning or updating first.
+Markdown output includes the reason each file, symbol, cognition note, nearby symbol, or relationship was selected. Use `--json` when an agent or script needs the same explanation data programmatically.
 
 ```bash
 kgraph update

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

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
-import type { ContextResponse } from "../../types/cognition.js";
+import type { Command } from 'commander';
+import type { ContextResponse } from '../../types/cognition.js';
 export declare function registerContextCommand(program: Command): void;
 export declare function renderContextMarkdown(response: ContextResponse): string;

package/dist/cli/commands/context.js

@@ -1,43 +1,142 @@
-import { loadConfig } from "../../config/config.js";
-import { queryContext } from "../../context/context-query.js";
-import { assertWorkspace } from "../../storage/kgraph-paths.js";
-import { mapsExist, readMaps } from "../../storage/map-store.js";
-import { KGraphError, runCommand } from "../errors.js";
+import { loadConfig } from '../../config/config.js';
+import { queryContext } from '../../context/context-query.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
 export function registerContextCommand(program) {
     program
-        .command("context <query>")
-        .description("Return compact repo context for a query")
-        .option("--json", "Print JSON output")
+        .command('context <query>')
+        .description('Return compact repo context for a query')
+        .option('--json', 'Print JSON output')
         .action((query, options) => runCommand(async () => {
         if (!query.trim()) {
-            throw new KGraphError("Query cannot be empty.");
+            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.");
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
         const config = await loadConfig(workspace);
         const maps = await readMaps(workspace);
         const response = await queryContext(workspace, config, maps, query);
-        console.log(options.json ? JSON.stringify(response, null, 2) : renderContextMarkdown(response));
+        console.log(options.json
+            ? JSON.stringify(response, null, 2)
+            : renderContextMarkdown(response));
     }));
 }
 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} (${item.reasons.join(", ")})`)));
-    lines.push("", "## Relevant Files", "");
-    lines.push(...formatList(response.relevantFiles.map((item) => `- ${item.item.path} (${item.reasons.join(", ")})`)));
-    lines.push("", "## Relevant Symbols", "");
-    lines.push(...formatList(response.relevantSymbols.map((item) => `- ${item.item.name} in ${item.item.filePath}`)));
-    lines.push("", "## Relevant Cognition", "");
-    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.referencesStatus}]`)));
-    lines.push("", "## Relationships", "");
-    lines.push(...formatList(response.relationships.map((relationship) => `- ${relationship.sourceId} ${relationship.relationshipType} ${relationship.targetId} (${relationship.confidence})`)));
-    lines.push("", "## Stale References", "");
+    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 f = item.item;
+        const meta = [
+            f.language,
+            f.tokenEstimate ? `~${f.tokenEstimate} tokens` : '',
+        ]
+            .filter(Boolean)
+            .join(', ');
+        return `- ${f.path}${meta ? ` [${meta}]` : ''} because ${formatReasons(item.reasons)}`;
+    })));
+    lines.push('', '## Relevant Symbols', '');
+    lines.push(...formatList(response.relevantSymbols.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)}`;
+    })));
+    lines.push('', '## Relevant Cognition', '');
+    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.referencesStatus}] because ${formatReasons(item.reasons)}`)));
+    lines.push('', '## Relationships', '');
+    lines.push(...formatGroupedRelationships(response.relationships, 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)}`;
+    })));
+    lines.push('', '## Stale References', '');
     lines.push(...formatList(response.staleReferences.map((ref) => `- ${ref}`)));
-    return lines.join("\n");
+    return lines.join('\n');
+}
+function formatGroupedRelationships(relationships, explanations) {
+    const reasonsByRelationship = new Map((explanations ?? []).map((item) => [
+        relationshipKey(item.relationship),
+        item.reasons,
+    ]));
+    const imports = relationships.filter((r) => r.relationshipType === 'import');
+    const calls = relationships.filter((r) => r.relationshipType === 'calls');
+    const contains = relationships.filter((r) => r.relationshipType === 'symbol-contains');
+    const other = relationships.filter((r) => r.relationshipType !== 'import' &&
+        r.relationshipType !== 'calls' &&
+        r.relationshipType !== 'symbol-contains' &&
+        r.relationshipType !== 'mentions' &&
+        r.relationshipType !== 'belongs-to-domain' &&
+        r.relationshipType !== 'stale-reference');
+    const lines = [];
+    if (imports.length > 0) {
+        lines.push('Imports:');
+        for (const r of imports) {
+            lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
+        }
+    }
+    if (calls.length > 0) {
+        lines.push('Calls:');
+        for (const r of calls) {
+            lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
+        }
+    }
+    if (contains.length > 0) {
+        lines.push('Contains:');
+        for (const r of contains) {
+            lines.push(`  ${r.sourceId} contains ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
+        }
+    }
+    if (other.length > 0) {
+        lines.push('Other:');
+        for (const r of other) {
+            lines.push(`  ${r.sourceId} ${r.relationshipType} ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
+        }
+    }
+    return lines.length > 0 ? lines : ['- None'];
 }
 function formatList(items) {
-    return items.length > 0 ? items : ["- None"];
+    return items.length > 0 ? items : ['- None'];
+}
+function formatReasons(reasons) {
+    if (reasons.length === 0) {
+        return 'it is near the query';
+    }
+    const visible = reasons.slice(0, 3);
+    const remaining = reasons.length - visible.length;
+    return remaining > 0
+        ? `${visible.join('; ')}; and ${remaining} more`
+        : visible.join('; ');
+}
+function nearbySymbolItems(response) {
+    if (response.nearbySymbolExplanations) {
+        return response.nearbySymbolExplanations;
+    }
+    return (response.nearbySymbols ?? []).map((symbol) => ({
+        symbol,
+        reasons: ['exported symbol from 1-hop import'],
+    }));
+}
+function formatRelationshipReason(relationship, reasonsByRelationship) {
+    const reasons = reasonsByRelationship.get(relationshipKey(relationship));
+    return reasons && reasons.length > 0
+        ? ` because ${formatReasons(reasons)}`
+        : '';
+}
+function relationshipKey(relationship) {
+    return [
+        relationship.sourceId,
+        relationship.targetId,
+        relationship.relationshipType,
+    ].join('\0');
 }

package/dist/cli/commands/doctor.js

@@ -80,12 +80,28 @@ export function registerDoctorCommand(program) {
                     : `${integration.name}: missing ${integration.targetPath}`)
                     .join('; '),
         });
+        let qualityReport;
+        if (maps) {
+            qualityReport = await analyzeCognitionQuality(workspace, maps);
+            const qualityFindings = summarizeQualityFindings(qualityReport);
+            const coverageNotes = summarizeCoverageNotes(qualityReport);
+            checks.push({
+                label: 'quality gate',
+                ok: qualityFindings.length === 0,
+                detail: qualityFindings.length === 0
+                    ? [
+                        'no stale/noisy cognition, generated scan noise, or duplicate titles',
+                        ...coverageNotes,
+                    ].join('; ')
+                    : qualityFindings.join('; '),
+            });
+        }
         printChecks(checks);
         if (options.quality && maps) {
             console.log('');
             console.log('KGraph Cognition Quality');
             console.log('');
-            printQualityReport(await analyzeCognitionQuality(workspace, maps));
+            printQualityReport(qualityReport ?? (await analyzeCognitionQuality(workspace, maps)));
         }
         if (checks.some((check) => !check.ok)) {
             process.exitCode = 1;
@@ -134,3 +150,29 @@ export function printQualityReport(report) {
         console.log(`  next status: ${change.nextStatus}`);
     }
 }
+function summarizeQualityFindings(report) {
+    const findings = [];
+    if (report.mixedOrStaleCount > 0) {
+        findings.push(`${report.mixedOrStaleCount} stale/mixed/unresolved note(s)`);
+    }
+    if (report.noisyFileRefCount > 0 || report.noisySymbolRefCount > 0) {
+        findings.push(`${report.noisyFileRefCount + report.noisySymbolRefCount} noisy cognition ref(s); run \`kgraph repair --dry-run\``);
+    }
+    if (report.duplicateTitleCount > 0) {
+        findings.push(`${report.duplicateTitleCount} duplicate cognition title(s)`);
+    }
+    if (report.generatedFileScanCount > 0) {
+        findings.push(`${report.generatedFileScanCount} generated/integration file(s) scanned; update excludes`);
+    }
+    return findings;
+}
+function summarizeCoverageNotes(report) {
+    const notes = [];
+    if (report.unresolvedLocalImportCount > 0) {
+        notes.push(`${report.unresolvedLocalImportCount} unresolved local import(s) visible in --quality`);
+    }
+    if (report.unresolvedCallCount > 0) {
+        notes.push(`${report.unresolvedCallCount} unresolved call edge(s) visible in --quality`);
+    }
+    return notes;
+}

package/dist/cli/commands/integrate.js

@@ -5,7 +5,8 @@ import { KGraphError, runCommand } from '../errors.js';
 export function registerIntegrateCommand(program) {
     const integrate = program
         .command('integrate')
-        .description('Manage AI tool integrations');
+        .description('Manage AI tool integrations')
+        .helpOption('-h, --help', 'Show help');
     integrate
         .command('list')
         .description('List configured integrations')

package/dist/cli/commands/session.js

@@ -6,6 +6,7 @@ export function registerSessionCommand(program) {
     const session = program
         .command('session')
         .description('Track agent read/write session activity and token estimates')
+        .helpOption('-h, --help', 'Show help')
         .option('--json', 'Print JSON output')
         .action((options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
@@ -93,6 +94,8 @@ export function renderSessionReport(report) {
     lines.push(...formatList(report.recentEvents.map((event) => `- ${event.agent} ${event.type}${event.path ? ` ${event.path}` : ''} [${event.captureSource}]`)));
     lines.push('', 'Recent Ledger');
     lines.push(...formatList(report.ledger.map((entry) => `- ${entry.agent} ${entry.readCount} reads, ${entry.writeCount} writes, ${entry.repeatedReadCount} repeated`)));
+    lines.push('', 'Next');
+    lines.push(...sessionNextActions(report));
     return lines.join('\n');
 }
 function requireAgent(value) {
@@ -110,3 +113,20 @@ function normalizeSource(value) {
 function formatList(items) {
     return items.length > 0 ? items : ['- None'];
 }
+function sessionNextActions(report) {
+    if (report.readCount === 0 && report.writeCount === 0) {
+        return [
+            '- Start tracking with `kgraph session start --agent <name>`.',
+            '- Record meaningful reads/writes with `kgraph session read <path> --agent <name>` and `kgraph session write <path> --agent <name>`.',
+        ];
+    }
+    if (report.repeatedReadCount > 0) {
+        return [
+            '- Repeated reads are present; run `kgraph context "<topic>"` before broad file inspection.',
+            '- End the tracked work with `kgraph session end --agent <name>` when the coding session is done.',
+        ];
+    }
+    return [
+        '- End the tracked work with `kgraph session end --agent <name>` when the coding session is done.',
+    ];
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerUninstallCommand(program: Command): void;

package/dist/cli/commands/uninstall.js

@@ -0,0 +1,69 @@
+import { rm } from 'node:fs/promises';
+import { loadConfig } from '../../config/config.js';
+import { removeIntegrations } from '../../integrations/integration-store.js';
+import { pathExists, resolveWorkspace } from '../../storage/kgraph-paths.js';
+import { runCommand } from '../errors.js';
+export function registerUninstallCommand(program) {
+    program
+        .command('uninstall')
+        .description('Remove KGraph from this repository')
+        .option('--yes', 'Apply the uninstall after previewing what will be removed')
+        .option('--keep-integrations', 'Remove only .kgraph/ and preserve generated AI tool instruction files')
+        .action((options) => runCommand(async () => {
+        const workspace = resolveWorkspace(process.cwd());
+        const initialized = await pathExists(workspace.kgraphPath);
+        const configuredIntegrations = initialized
+            ? (await loadConfig(workspace)).integrations.map((integration) => integration.name)
+            : [];
+        printUninstallPreview({
+            initialized,
+            integrations: configuredIntegrations,
+            keepIntegrations: options.keepIntegrations === true,
+            applying: options.yes === true,
+        });
+        if (!options.yes) {
+            return;
+        }
+        if (initialized &&
+            !options.keepIntegrations &&
+            configuredIntegrations.length > 0) {
+            await removeIntegrations(workspace, configuredIntegrations);
+        }
+        if (initialized) {
+            await rm(workspace.kgraphPath, { recursive: true, force: true });
+        }
+        console.log('');
+        console.log('KGraph uninstall complete.');
+        console.log('Run `kgraph init` to set up this repository again.');
+    }));
+}
+function printUninstallPreview(input) {
+    console.log('KGraph Uninstall Preview');
+    console.log('');
+    console.log('Will remove:');
+    if (input.initialized) {
+        console.log('- .kgraph/ runtime workspace');
+    }
+    else {
+        console.log('- Nothing: .kgraph/ does not exist in this repository');
+    }
+    if (!input.keepIntegrations) {
+        if (input.integrations.length > 0) {
+            console.log(`- KGraph-managed integration blocks/files for: ${input.integrations.join(', ')}`);
+        }
+        else {
+            console.log('- No configured integration blocks/files found');
+        }
+    }
+    console.log('');
+    console.log('Will preserve:');
+    console.log('- Repository source files');
+    console.log('- User-authored content outside KGraph managed blocks');
+    if (input.keepIntegrations) {
+        console.log('- KGraph-managed integration instruction files');
+    }
+    if (!input.applying) {
+        console.log('');
+        console.log('No files were removed. Run `kgraph uninstall --yes` to apply.');
+    }
+}

package/dist/cli/commands/workflow.js

@@ -1,5 +1,4 @@
-import { updateCognition } from '../../cognition/cognition-updater.js';
-import { refreshCognitionReferenceStatuses } from '../../cognition/cognition-updater.js';
+import { refreshCognitionReferenceStatuses, updateCognition, } from '../../cognition/cognition-updater.js';
 import { loadConfig } from '../../config/config.js';
 import { queryContext } from '../../context/context-query.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
@@ -35,6 +34,7 @@ export async function runDefaultWorkflow(query) {
         console.log(renderWorkflowBanner({
             files: scan.files.length,
             symbols: scan.symbols.length,
+            skippedFiles: scan.skippedFiles,
             cognitionNotes: update.processed.length,
             integrations: config.integrations.map((integration) => ({
                 name: integration.name,

package/dist/cli/help.d.ts

@@ -3,6 +3,7 @@ interface WorkflowBannerStats {
     files: number;
     symbols: number;
     cognitionNotes: number;
+    skippedFiles?: number;
     integrations?: WorkflowBannerIntegration[];
 }
 interface WorkflowBannerIntegration {

package/dist/cli/help.js

@@ -36,6 +36,8 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('doctor --quality', 'Report stale/noisy cognition references'),
         command('repair --dry-run', 'Preview cognition reference cleanup'),
         command('repair', 'Clean noisy stale cognition references'),
+        command('uninstall', 'Preview repo-local KGraph removal'),
+        command('uninstall --yes', 'Remove .kgraph/ and managed integrations'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
         '',
@@ -77,7 +79,10 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         `  ${theme.bold('KGraph')} ${theme.dim('repo intelligence refreshed')}`,
         '',
         theme.bold('Refresh Complete'),
-        command('files', String(stats.files)),
+        command('files', String(stats.files) +
+            (stats.skippedFiles
+                ? ` (${stats.skippedFiles} unchanged, skipped)`
+                : '')),
         command('symbols', String(stats.symbols)),
         command('cognition notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),

package/dist/cli/index.d.ts

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 export declare function createProgram(): Command;
+export declare function shouldRenderRootHelpBeforeParse(argv: string[]): boolean;

package/dist/cli/index.js

@@ -12,6 +12,7 @@ import { registerIntegrateCommand } from './commands/integrate.js';
 import { registerRepairCommand } from './commands/repair.js';
 import { registerScanCommand } from './commands/scan.js';
 import { registerSessionCommand } from './commands/session.js';
+import { registerUninstallCommand } from './commands/uninstall.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerVisualizeCommand } from './commands/visualize.js';
 import { runDefaultWorkflow } from './commands/workflow.js';
@@ -25,7 +26,6 @@ export function createProgram() {
         .description('Persistent repo intelligence for AI coding assistants')
         .argument('[topic...]', 'Run the default refresh workflow and optionally return context for a topic')
         .version(version)
-        .addHelpText('beforeAll', renderRootHelp())
         .helpOption(false)
         .action(async (topicParts = []) => {
         await runDefaultWorkflow(topicParts.join(' '));
@@ -48,17 +48,44 @@ export function createProgram() {
     registerHistoryCommand(program);
     registerDoctorCommand(program);
     registerRepairCommand(program);
+    registerUninstallCommand(program);
     return program;
 }
 if (isCliEntrypoint()) {
     const program = createProgram();
-    if (process.argv.includes('-h') || process.argv.includes('--help')) {
+    const helpTarget = findExplicitHelpTarget(program, process.argv.slice(2));
+    if (helpTarget === program || shouldRenderRootHelpBeforeParse(process.argv)) {
         console.log(renderRootHelp());
     }
+    else if (helpTarget) {
+        helpTarget.outputHelp();
+    }
     else {
         await program.parseAsync(process.argv);
     }
 }
+export function shouldRenderRootHelpBeforeParse(argv) {
+    const args = argv.slice(2);
+    return args.length === 1 && (args[0] === '-h' || args[0] === '--help');
+}
+function findExplicitHelpTarget(program, args) {
+    let command = program;
+    let matchedSubcommand = false;
+    for (const arg of args) {
+        if (arg === '-h' || arg === '--help') {
+            return matchedSubcommand ? command : program;
+        }
+        if (arg.startsWith('-')) {
+            continue;
+        }
+        const next = command.commands.find((candidate) => candidate.name() === arg || candidate.aliases().includes(arg));
+        if (next) {
+            command = next;
+            matchedSubcommand = true;
+        }
+    }
+    return undefined;
+}
 function isCliEntrypoint() {
     if (!process.argv[1]) {
         return false;

package/dist/context/context-query.js

@@ -59,6 +59,13 @@ export async function queryContext(workspace, config, maps, query) {
     ].filter((relationship, index, all) => all.findIndex((candidate) => candidate.sourceId === relationship.sourceId &&
         candidate.targetId === relationship.targetId &&
         candidate.relationshipType === relationship.relationshipType) === index);
+    const relationshipExplanations = explainRelationships(relationships, {
+        rankedRelationships,
+        relevantFiles,
+        relevantSymbols,
+        relevantCognition,
+        matchedDomains,
+    });
     const filePaths = new Set(maps.fileMap.files.map((f) => f.path));
     const symbolNames = new Set(maps.symbolMap.symbols.map((s) => s.name));
     const staleReferences = cognition
@@ -73,6 +80,35 @@ export async function queryContext(workspace, config, maps, query) {
             .filter((s) => !symbolNames.has(s))
             .map((ref) => `${note.title}: ${ref}`),
     ]);
+    // Collect nearby symbols: exported symbols from files 1-hop imported by matched files
+    const matchedFilePaths = new Set([
+        ...relevantFiles.map((f) => f.item.path),
+        ...relevantSymbols.map((s) => s.item.filePath),
+    ]);
+    const matchedSymbolIds = new Set(relevantSymbols.map((s) => s.item.id));
+    const importedFilePaths = new Set();
+    for (const dep of maps.dependencyMap.dependencies) {
+        if (dep.kind === 'local' &&
+            dep.resolvedFile &&
+            matchedFilePaths.has(dep.fromFile)) {
+            importedFilePaths.add(dep.resolvedFile);
+        }
+    }
+    // Remove files already in the matched set
+    for (const p of matchedFilePaths)
+        importedFilePaths.delete(p);
+    const nearbySymbols = maps.symbolMap.symbols
+        .filter((s) => s.exported &&
+        importedFilePaths.has(s.filePath) &&
+        !matchedSymbolIds.has(s.id))
+        .slice(0, max);
+    const nearbySymbolExplanations = nearbySymbols.map((symbol) => ({
+        symbol,
+        reasons: [
+            `exported symbol from 1-hop import ${symbol.filePath}`,
+            ...dependenciesForImportedSymbol(symbol, maps.dependencyMap.dependencies),
+        ],
+    }));
     return {
         query,
         matchedDomains,
@@ -80,7 +116,71 @@ export async function queryContext(workspace, config, maps, query) {
         relevantSymbols,
         relevantCognition,
         relationships: relationships.slice(0, max),
+        relationshipExplanations: relationshipExplanations.slice(0, max),
+        nearbySymbols,
+        nearbySymbolExplanations,
         staleReferences,
         warnings: [],
     };
 }
+function explainRelationships(relationships, context) {
+    const rankedReasons = new Map(context.rankedRelationships.map((ranked) => [
+        relationshipKey(ranked.item),
+        ranked.reasons,
+    ]));
+    return relationships.map((relationship) => {
+        const reasons = new Set();
+        for (const reason of rankedReasons.get(relationshipKey(relationship)) ?? []) {
+            reasons.add(reason);
+        }
+        for (const file of context.relevantFiles) {
+            if (relationship.sourceId === file.item.path ||
+                relationship.targetId === file.item.path) {
+                reasons.add(`connected to matched file ${file.item.path}`);
+            }
+        }
+        for (const symbol of context.relevantSymbols) {
+            if (relationship.sourceId === symbol.item.id ||
+                relationship.targetId === symbol.item.id ||
+                relationship.sourceId === symbol.item.name ||
+                relationship.targetId === symbol.item.name ||
+                relationship.sourceId === symbol.item.filePath ||
+                relationship.targetId === symbol.item.filePath) {
+                reasons.add(`connected to matched symbol ${symbol.item.name}`);
+            }
+        }
+        for (const note of context.relevantCognition) {
+            if (note.item.relatedFiles.includes(relationship.sourceId) ||
+                note.item.relatedFiles.includes(relationship.targetId) ||
+                note.item.relatedSymbols.includes(relationship.sourceId) ||
+                note.item.relatedSymbols.includes(relationship.targetId)) {
+                reasons.add(`referenced by cognition "${note.item.title}"`);
+            }
+        }
+        for (const domain of context.matchedDomains) {
+            if (domain.item.files.includes(relationship.sourceId) ||
+                domain.item.files.includes(relationship.targetId) ||
+                domain.item.symbols.includes(relationship.sourceId) ||
+                domain.item.symbols.includes(relationship.targetId)) {
+                reasons.add(`inside matched domain ${domain.item.name}`);
+            }
+        }
+        if (reasons.size === 0) {
+            reasons.add(`nearby ${relationship.relationshipType} relationship`);
+        }
+        return { relationship, reasons: [...reasons] };
+    });
+}
+function dependenciesForImportedSymbol(symbol, dependencies) {
+    return dependencies
+        .filter((dependency) => dependency.kind === 'local' &&
+        dependency.resolvedFile === symbol.filePath)
+        .map((dependency) => `imported by ${dependency.fromFile} via ${dependency.specifier}`);
+}
+function relationshipKey(relationship) {
+    return [
+        relationship.sourceId,
+        relationship.targetId,
+        relationship.relationshipType,
+    ].join('\0');
+}

package/dist/scanner/repo-scanner.js

@@ -46,21 +46,71 @@ export async function scanRepository(rootPath, config, previous) {
         unique: true,
         ignore: buildFastGlobIgnore(allExcludes),
     });
+    // Build lookup maps from previous scan for incremental skip
+    const prevFileByPath = new Map((previous?.files ?? []).map((f) => [f.path, f]));
+    const prevSymbolsByFile = new Map();
+    const prevDepsByFile = new Map();
+    const prevRelsBySource = new Map();
+    if (previous) {
+        for (const sym of previous.symbols) {
+            const arr = prevSymbolsByFile.get(sym.filePath) ?? [];
+            arr.push(sym);
+            prevSymbolsByFile.set(sym.filePath, arr);
+        }
+        for (const dep of previous.dependencies) {
+            const arr = prevDepsByFile.get(dep.fromFile) ?? [];
+            arr.push(dep);
+            prevDepsByFile.set(dep.fromFile, arr);
+        }
+        for (const rel of previous.relationships) {
+            if (rel.relationshipType !== 'import' &&
+                rel.relationshipType !== 'moved-from') {
+                const arr = prevRelsBySource.get(rel.sourceId) ?? [];
+                arr.push(rel);
+                prevRelsBySource.set(rel.sourceId, arr);
+            }
+        }
+    }
     const files = [];
     const symbols = [];
     const dependencies = [];
     const relationships = [];
     const warnings = [];
+    let skippedFiles = 0;
     for (const repoPath of entries.sort()) {
         if (shouldExclude(repoPath, mergedConfig)) {
             continue;
         }
         const absolutePath = path.join(rootPath, repoPath);
         try {
-            const [info, content] = await Promise.all([
-                stat(absolutePath),
-                readFile(absolutePath),
-            ]);
+            const info = await stat(absolutePath);
+            // Incremental skip: if mtime and size match previous, carry forward
+            const prevFile = prevFileByPath.get(repoPath);
+            if (prevFile &&
+                prevFile.sizeBytes === info.size &&
+                prevFile.modifiedAt === info.mtime.toISOString()) {
+                files.push({ ...prevFile, modifiedAt: info.mtime.toISOString() });
+                const prevSyms = prevSymbolsByFile.get(repoPath);
+                if (prevSyms)
+                    symbols.push(...prevSyms);
+                const prevDeps = prevDepsByFile.get(repoPath);
+                if (prevDeps)
+                    dependencies.push(...prevDeps);
+                const prevRels = prevRelsBySource.get(repoPath);
+                if (prevRels)
+                    relationships.push(...prevRels);
+                // Also carry forward symbol-sourced relationships
+                if (prevSyms) {
+                    for (const sym of prevSyms) {
+                        const symRels = prevRelsBySource.get(sym.id);
+                        if (symRels)
+                            relationships.push(...symRels);
+                    }
+                }
+                skippedFiles++;
+                continue;
+            }
+            const content = await readFile(absolutePath);
             const text = content.toString('utf8');
             const contentHash = crypto
                 .createHash('sha256')
@@ -105,7 +155,14 @@ export async function scanRepository(rootPath, config, previous) {
     resolveLocalDependencies(dependencies, files);
     relationships.push(...buildImportRelationships(dependencies));
     relationships.push(...detectMovedFiles(previous?.files ?? [], files));
-    return { files, symbols, dependencies, relationships, warnings };
+    return {
+        files,
+        symbols,
+        dependencies,
+        relationships,
+        warnings,
+        skippedFiles,
+    };
 }
 const SOURCE_EXTENSIONS = [
     '.ts',

package/dist/storage/kgraph-paths.js

@@ -37,7 +37,11 @@ export async function pathExists(targetPath) {
 export async function assertWorkspace(rootPath = process.cwd()) {
     const workspace = resolveWorkspace(rootPath);
     if (!(await pathExists(workspace.kgraphPath))) {
-        throw new KGraphError("KGraph is not initialized. Run `kgraph init` first.");
+        throw new KGraphError([
+            "KGraph is not initialized for this repository.",
+            "Run `kgraph init` first, or use `kgraph init --integrations codex,copilot,cursor,claude-code` to initialize and connect common AI tools.",
+            "After init, run `kgraph doctor` to verify maps, integrations, and cognition quality.",
+        ].join("\n"));
     }
     const info = await stat(workspace.kgraphPath);
     if (!info.isDirectory()) {

package/dist/types/cognition.d.ts

@@ -1,5 +1,5 @@
-import type { CodeSymbol, Relationship, RepositoryFile } from "./maps.js";
-export type ReferenceStatus = "current" | "stale" | "unresolved" | "mixed";
+import type { CodeSymbol, Relationship, RepositoryFile } from './maps.js';
+export type ReferenceStatus = 'current' | 'stale' | 'unresolved' | 'mixed';
 export interface ParsedCognitionNote {
     title: string;
     domain?: string;
@@ -38,6 +38,15 @@ export interface ContextResponse {
     relevantSymbols: RankedItem<CodeSymbol>[];
     relevantCognition: RankedItem<CognitionNote>[];
     relationships: Relationship[];
+    relationshipExplanations?: Array<{
+        relationship: Relationship;
+        reasons: string[];
+    }>;
+    nearbySymbols?: CodeSymbol[];
+    nearbySymbolExplanations?: Array<{
+        symbol: CodeSymbol;
+        reasons: string[];
+    }>;
     staleReferences: string[];
     warnings: string[];
 }

package/dist/types/maps.d.ts

@@ -1,7 +1,7 @@
-export type ScanStatus = "mapped" | "generic" | "failed";
-export type DependencyKind = "local" | "package" | "unknown";
-export type SymbolKind = "function" | "class" | "method" | "type" | "interface" | "export" | "import";
-export type RelationshipType = "import" | "contains" | "symbol-contains" | "calls" | "mentions" | "belongs-to-domain" | "stale-reference" | "moved-from";
+export type ScanStatus = 'mapped' | 'generic' | 'failed';
+export type DependencyKind = 'local' | 'package' | 'unknown';
+export type SymbolKind = 'function' | 'class' | 'method' | 'type' | 'interface' | 'export' | 'import';
+export type RelationshipType = 'import' | 'contains' | 'symbol-contains' | 'calls' | 'mentions' | 'belongs-to-domain' | 'stale-reference' | 'moved-from';
 export interface RepositoryFile {
     id: string;
     path: string;
@@ -36,7 +36,7 @@ export interface Relationship {
     targetType: string;
     targetId: string;
     relationshipType: RelationshipType;
-    confidence: "high" | "medium" | "low";
+    confidence: 'high' | 'medium' | 'low';
 }
 export interface FileMap {
     generatedAt: string;
@@ -60,4 +60,5 @@ export interface ScanResult {
     dependencies: Dependency[];
     relationships: Relationship[];
     warnings: string[];
+    skippedFiles?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.27",
+  "version": "0.2.1",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -59,7 +59,7 @@
   "devDependencies": {
     "@types/node": "^20.17.10",
     "tsx": "^4.19.2",
-    "vitest": "^2.1.8"
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=20"