@kentwynn/kgraph 0.2.0 → 0.2.2

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:
 
@@ -73,6 +74,8 @@ That shows matched files/symbols, files importing the target, known callers/call
 
 ## Install
 
+The official npm package is `@kentwynn/kgraph`; the official repository is `github.com/kentwynn/KGraph`.
+
 Use the published CLI:
 
 ```bash
@@ -89,6 +92,8 @@ npx @kentwynn/kgraph@latest "auth token refresh"
 
 KGraph requires Node.js 20 or newer.
 
+KGraph's core functionality is free and local-first. It does not require accounts, telemetry, cloud services, API keys, or source-code upload.
+
 ## Quick Start
 
 From the root of a repository:
@@ -103,7 +108,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 +125,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 +172,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 +181,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 +207,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 +225,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
@@ -289,7 +306,7 @@ All runtime data lives under `.kgraph/`:
 └── context/
 ```
 
-The files are local, inspectable, and human-readable. There is no database, telemetry, cloud service, account, API key, embedding service, or model provider.
+The files are local, inspectable, and human-readable. Core KGraph functionality is free. There is no database, telemetry, cloud service, account, API key, embedding service, model provider, or source-code upload.
 
 ## Language Support
 
@@ -358,14 +375,25 @@ npm run release:pack
 
 ## Release
 
-Releases are tag-driven:
+Releases are PR-first because `main` is protected. Use the Makefile helper to bump the version on a release branch, push it, and open a pull request when the GitHub CLI is available:
+
+```bash
+make release
+```
+
+Use `RELEASE=minor` or `RELEASE=major` when needed:
+
+```bash
+make release RELEASE=minor
+```
+
+After the PR is merged, tag the merged commit from an up-to-date `main`:
 
 ```bash
-npm version patch
-git push origin main --follow-tags
+make release-tag VERSION=v0.2.2
 ```
 
-The release workflow builds, tests, packs, publishes the npm package on version tags, creates a GitHub Release, and uploads the tarball artifact.
+The release workflow builds, tests, packs, publishes the npm package on version tags, creates a GitHub Release, and uploads the tarball artifact. Do not push directly to `main` for releases.
 
 ## Design Principles
 
@@ -378,8 +406,9 @@ The release workflow builds, tests, packs, publishes the npm package on version
 
 ## Roadmap
 
+- Better Git-aware token saving and diff context.
 - Smarter cross-file symbol and call relationship inference.
 - Stronger TypeScript path alias and package export resolution.
 - Richer graph filtering for large repositories.
-- Optional MCP server for editor tool-call access.
-- Team workflows for shared committed cognition.
+- Optional MCP and editor integration.
+- Team-friendly shared cognition workflows that stay local-first.

package/dist/cli/commands/context.js

@@ -27,7 +27,7 @@ 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} (${item.reasons.join(', ')})`)));
+    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;
@@ -37,7 +37,7 @@ export function renderContextMarkdown(response) {
         ]
             .filter(Boolean)
             .join(', ');
-        return `- ${f.path}${meta ? ` [${meta}]` : ''}`;
+        return `- ${f.path}${meta ? ` [${meta}]` : ''} because ${formatReasons(item.reasons)}`;
     })));
     lines.push('', '## Relevant Symbols', '');
     lines.push(...formatList(response.relevantSymbols.map((item) => {
@@ -46,25 +46,29 @@ export function renderContextMarkdown(response) {
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`;
+        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}]`)));
+    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));
+    lines.push(...formatGroupedRelationships(response.relationships, response.relationshipExplanations));
     lines.push('', '## Nearby Symbols (1-hop imports)', '');
-    lines.push(...formatList((response.nearbySymbols ?? []).map((s) => {
+    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}`;
+        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');
 }
-function formatGroupedRelationships(relationships) {
+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');
@@ -77,26 +81,62 @@ function formatGroupedRelationships(relationships) {
     const lines = [];
     if (imports.length > 0) {
         lines.push('Imports:');
-        for (const r of imports)
-            lines.push(`  ${r.sourceId} → ${r.targetId}`);
+        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}`);
+        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}`);
+        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}`);
+        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'];
 }
+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/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'),
         '',

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
@@ -95,6 +102,13 @@ export async function queryContext(workspace, config, maps, query) {
         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,
@@ -102,8 +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/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

@@ -38,7 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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"