@kentwynn/kgraph 0.1.21 → 0.1.23

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:
@@ -112,6 +120,18 @@ kgraph
 
 Use `kgraph doctor --quality` and `kgraph repair --dry-run` only when stale or noisy cognition references start making context harder to trust.
 
+Agents can also report session activity so KGraph can estimate token waste:
+
+```bash
+kgraph session start --agent codex
+kgraph session read src/auth.ts --agent codex
+kgraph session write src/auth.ts --agent codex
+kgraph session end --agent codex
+kgraph session
+```
+
+This is optional. Claude Code can use generated hook scripts for automatic capture; other agents use the same commands through their managed instructions, rules, or prompts.
+
 ## Main Commands
 
 ```bash
@@ -143,14 +163,33 @@ 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.
+
+```bash
+kgraph session
+kgraph session --json
+kgraph session reset
+kgraph session start --agent codex
+kgraph session read src/auth.ts --agent codex
+kgraph session write src/auth.ts --agent codex
+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`.
 
 ## Optional Step Commands
 
@@ -187,10 +226,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
 
@@ -198,10 +238,21 @@ KGraph integrations are local files. They do not start background agents, call A
 
 ```bash
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
+kgraph integrate add copilot --mode always
+kgraph integrate set copilot --mode manual
 kgraph integrate list
 kgraph integrate remove cursor
 ```
 
+New integrations default to `always` mode because coding agents often under-classify small UI, route, button, and link changes as not needing repo context.
+
+| Mode | Behavior |
+| --- | --- |
+| `always` | Every chat in the repository starts with `kgraph "<topic>"`, even simple or conversational requests. |
+| `smart` | Runs KGraph automatically for repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests. Skips simple conversational requests that do not depend on repo knowledge. |
+| `manual` | Exposes KGraph commands and instructions, but the agent runs KGraph only when the user explicitly asks. |
+| `off` | Disables that integration and removes generated KGraph instruction blocks/command files. |
+
 | Tool | Files KGraph manages |
 | --- | --- |
 | Codex | `AGENTS.md`, `.agents/skills/kgraph/SKILL.md` |
@@ -232,6 +283,7 @@ All runtime data lives under `.kgraph/`:
 ├── cognition/
 ├── domains/
 ├── interactions/processed/
+├── sessions/
 └── context/
 ```
 
@@ -319,6 +371,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,14 @@ 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}`);
+    console.log(`Expensive files: ${report.expensiveFileCount}`);
+    console.log(`Session repeated reads: ${report.sessionRepeatedReadCount}`);
+    console.log(`Session estimated read tokens: ${report.sessionEstimatedReadTokens}`);
+    console.log(`Session repeated-read tokens: ${report.sessionEstimatedRepeatedReadTokens}`);
     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/commands/init.js

@@ -2,13 +2,14 @@ import { writeDefaultConfig } from "../../config/config.js";
 import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
 import { addIntegrations } from "../../integrations/integration-store.js";
 import { ensureWorkspace } from "../../storage/kgraph-paths.js";
-import { runCommand } from "../errors.js";
+import { KGraphError, runCommand } from "../errors.js";
 export function registerInitCommand(program) {
     program
         .command("init")
         .description("Initialize a .kgraph workspace")
         .option("--integration <name>", "Configure an AI tool integration", collectOption, [])
         .option("--integrations <names>", "Configure comma-separated AI tool integrations")
+        .option("--mode <mode>", "Integration mode: smart, always, manual, or off", "always")
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         const wroteConfig = await writeDefaultConfig(workspace);
@@ -18,8 +19,9 @@ export function registerInitCommand(program) {
             ...(options.integrations ? [options.integrations] : [])
         ]);
         if (names.length > 0) {
-            const changed = await addIntegrations(workspace, names);
-            console.log(`Configured integrations: ${changed.map((item) => item.name).join(", ")}`);
+            const mode = normalizeIntegrationMode(options.mode);
+            const changed = await addIntegrations(workspace, names, mode);
+            console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
         }
     }));
 }
@@ -27,3 +29,9 @@ function collectOption(value, previous) {
     previous.push(value);
     return previous;
 }
+function normalizeIntegrationMode(value) {
+    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+        return value;
+    }
+    throw new KGraphError("--mode must be smart, always, manual, or off.");
+}

package/dist/cli/commands/integrate.js

@@ -1,4 +1,4 @@
-import { addIntegrations, listIntegrations, removeIntegrations } from "../../integrations/integration-store.js";
+import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode } from "../../integrations/integration-store.js";
 import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
 import { assertWorkspace } from "../../storage/kgraph-paths.js";
 import { KGraphError, runCommand } from "../errors.js";
@@ -12,17 +12,38 @@ export function registerIntegrateCommand(program) {
             return;
         }
         for (const integration of integrations) {
-            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
+            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.mode} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
         }
     }));
-    integrate.command("add").description("Add AI tool integrations").argument("<names...>").action((names) => runCommand(async () => {
+    integrate
+        .command("add")
+        .description("Add AI tool integrations")
+        .argument("<names...>")
+        .option("--mode <mode>", "smart, always, manual, or off", "always")
+        .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
             throw new KGraphError("Provide at least one integration name.");
         }
-        const changed = await addIntegrations(workspace, normalized);
-        console.log(`Configured integrations: ${changed.map((item) => item.name).join(", ")}`);
+        const mode = normalizeIntegrationMode(options.mode);
+        const changed = await addIntegrations(workspace, normalized, mode);
+        console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+    }));
+    integrate
+        .command("set")
+        .description("Set AI tool integration mode")
+        .argument("<names...>")
+        .requiredOption("--mode <mode>", "smart, always, manual, or off")
+        .action((names, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const normalized = normalizeIntegrationNames(names);
+        if (normalized.length === 0) {
+            throw new KGraphError("Provide at least one integration name.");
+        }
+        const mode = normalizeIntegrationMode(options.mode);
+        const changed = await setIntegrationMode(workspace, normalized, mode);
+        console.log(`Updated integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
     }));
     integrate.command("remove").description("Remove AI tool integrations").argument("<names...>").action((names) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
@@ -34,3 +55,9 @@ export function registerIntegrateCommand(program) {
         console.log(`Removed integrations: ${removed.join(", ")}`);
     }));
 }
+function normalizeIntegrationMode(value) {
+    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+        return value;
+    }
+    throw new KGraphError("--mode must be smart, always, manual, or off.");
+}

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

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { buildSessionReport } from '../../session/session-store.js';
+export declare function registerSessionCommand(program: Command): void;
+export declare function renderSessionReport(report: Awaited<ReturnType<typeof buildSessionReport>>): string;

package/dist/cli/commands/session.js

@@ -0,0 +1,112 @@
+import { assertSessionAgent, buildSessionReport, recordSessionEvent, resetSession, } from '../../session/session-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerSessionCommand(program) {
+    const session = program
+        .command('session')
+        .description('Track agent read/write session activity and token estimates')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const report = await buildSessionReport(workspace);
+        console.log(options.json ? JSON.stringify(report, null, 2) : renderSessionReport(report));
+    }));
+    session
+        .command('start')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'start',
+            captureSource: normalizeSource(options.source),
+        });
+        console.log(`KGraph session started for ${event.agent}.`);
+    }));
+    session
+        .command('read <path>')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((filePath, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const maps = await readMaps(workspace);
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'read',
+            path: filePath,
+            captureSource: normalizeSource(options.source),
+            fileMap: maps.fileMap,
+        });
+        console.log(`KGraph recorded read: ${event.path}${event.repeated ? ' (repeated)' : ''}${event.tokenEstimate !== undefined ? ` ~${event.tokenEstimate} tokens` : ''}.`);
+    }));
+    session
+        .command('write <path>')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((filePath, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const maps = await readMaps(workspace);
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'write',
+            path: filePath,
+            captureSource: normalizeSource(options.source),
+            fileMap: maps.fileMap,
+        });
+        console.log(`KGraph recorded write: ${event.path}${event.tokenEstimate !== undefined ? ` ~${event.tokenEstimate} tokens` : ''}.`);
+    }));
+    session
+        .command('end')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'end',
+            captureSource: normalizeSource(options.source),
+        });
+        console.log(`KGraph session ended for ${event.agent}.`);
+    }));
+    session
+        .command('reset')
+        .description('Clear the current session tracker')
+        .action(() => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        await resetSession(workspace);
+        console.log('KGraph current session reset.');
+    }));
+}
+export function renderSessionReport(report) {
+    const lines = ['', 'KGraph Session', ''];
+    lines.push(`Active agents: ${report.activeAgents.length === 0 ? 'none' : report.activeAgents.map((agent) => agent.agent).join(', ')}`);
+    lines.push(`Reads: ${report.readCount}`);
+    lines.push(`Writes: ${report.writeCount}`);
+    lines.push(`Repeated reads: ${report.repeatedReadCount}`);
+    lines.push(`Estimated read tokens: ${report.estimatedReadTokens}`);
+    lines.push(`Estimated repeated-read tokens: ${report.estimatedRepeatedReadTokens}`);
+    lines.push('', 'Top Repeated Reads');
+    lines.push(...formatList(report.topRepeatedReads.map((item) => `- ${item.path} read ${item.count} times (~${item.estimatedTokens} tokens)`)));
+    lines.push('', 'Recent Events');
+    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`)));
+    return lines.join('\n');
+}
+function requireAgent(value) {
+    if (!value) {
+        throw new KGraphError('--agent is required.');
+    }
+    return assertSessionAgent(value);
+}
+function normalizeSource(value) {
+    if (value === 'automatic' || value === 'agent-reported' || value === 'manual') {
+        return value;
+    }
+    throw new KGraphError('--source must be automatic, agent-reported, or manual.');
+}
+function formatList(items) {
+    return items.length > 0 ? items : ['- None'];
+}

package/dist/cli/commands/workflow.js

@@ -36,6 +36,11 @@ export async function runDefaultWorkflow(query) {
             files: scan.files.length,
             symbols: scan.symbols.length,
             cognitionNotes: update.processed.length,
+            integrations: config.integrations.map((integration) => ({
+                name: integration.name,
+                mode: integration.mode,
+                enabled: integration.enabled,
+            })),
         }));
         console.log('');
         for (const warning of [...scan.warnings, ...update.warnings]) {

package/dist/cli/help.d.ts

@@ -3,6 +3,12 @@ interface WorkflowBannerStats {
     files: number;
     symbols: number;
     cognitionNotes: number;
+    integrations?: WorkflowBannerIntegration[];
+}
+interface WorkflowBannerIntegration {
+    name: string;
+    mode: string;
+    enabled: boolean;
 }
 export declare function renderWorkflowBanner(stats: WorkflowBannerStats, useColor?: boolean): string;
 export {};

package/dist/cli/help.js

@@ -27,19 +27,25 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         theme.bold('Workflows'),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
+        command('session', 'Show agent read/write activity and token estimates'),
+        command('session read src/auth.ts --agent codex', 'Record an agent file read'),
         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'),
-        command('integrate add gemini windsurf cline', 'Write KGraph instructions for AI tools'),
+        command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
+        command('integrate add copilot --mode always', 'Every Copilot chat starts with kgraph "<topic>"'),
+        command('integrate set copilot --mode manual', 'Only run KGraph when explicitly requested'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
+        command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
         '',
         theme.bold('Options'),
         command('-V, --version', 'Show version'),
@@ -57,6 +63,13 @@ export function renderRootHelp(useColor = supportsColor()) {
 export function renderWorkflowBanner(stats, useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
+    const integrationLine = stats.integrations && stats.integrations.length > 0
+        ? stats.integrations
+            .map((integration) => integration.enabled
+            ? `${integration.name}:${integration.mode}`
+            : `${integration.name}:off`)
+            .join(', ')
+        : 'none configured';
     return [
         '',
         theme.hex('#7dd3fc').bold(renderLogo()),
@@ -67,11 +80,13 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('files', String(stats.files)),
         command('symbols', String(stats.symbols)),
         command('cognition notes processed', String(stats.cognitionNotes)),
+        command('integration modes', integrationLine),
         '',
         theme.bold('Next'),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
         command('kgraph doctor --quality', 'Check cognition quality'),
+        command('kgraph session', 'Check session token waste'),
         command('kgraph --help', 'Show all commands'),
     ].join('\n');
 }

package/dist/cli/index.js

@@ -6,10 +6,12 @@ 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';
 import { registerScanCommand } from './commands/scan.js';
+import { registerSessionCommand } from './commands/session.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerVisualizeCommand } from './commands/visualize.js';
 import { runDefaultWorkflow } from './commands/workflow.js';
@@ -37,8 +39,10 @@ export function createProgram() {
     });
     registerInitCommand(program);
     registerScanCommand(program);
+    registerSessionCommand(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,25 @@ export interface CognitionQualityReport {
     mixedOrStaleCount: number;
     noisyFileRefCount: number;
     noisySymbolRefCount: number;
+    unresolvedLocalImportCount: number;
+    unresolvedCallCount: number;
+    duplicateTitleCount: number;
+    generatedFileScanCount: number;
+    expensiveFileCount: number;
+    sessionRepeatedReadCount: number;
+    sessionEstimatedReadTokens: number;
+    sessionEstimatedRepeatedReadTokens: 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>;