@kentwynn/kgraph 0.1.17 → 0.1.19

package/README.md

@@ -100,6 +100,17 @@ kgraph doctor
 
 After useful AI work, assistants can save durable notes into `.kgraph/inbox/`. The next `kgraph` run processes those notes automatically. You can also process them directly with `kgraph update`.
 
+Normal agent flow is intentionally small:
+
+```bash
+kgraph "topic"
+# work normally
+# if repo files changed, write an inbox note when the change has future value
+kgraph
+```
+
+Use `kgraph doctor --quality` and `kgraph repair --dry-run` only when stale or noisy cognition references start making context harder to trust.
+
 ## Main Commands
 
 ```bash
@@ -128,9 +139,17 @@ Refreshes maps and cognition without returning topic-specific context.
 
 ```bash
 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.
+
+```bash
+kgraph repair --dry-run
+kgraph repair
 ```
 
-Checks whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files.
+`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.
 
 ## Optional Step Commands
 
@@ -255,6 +274,8 @@ Run the local TypeScript CLI without installing globally:
 npm run kgraph -- init
 npm run kgraph -- "auth token refresh"
 npm run kgraph -- doctor
+npm run kgraph -- doctor --quality
+npm run kgraph -- repair --dry-run
 ```
 
 Test the built package as a global local install:
@@ -265,6 +286,7 @@ npm install -g .
 kgraph --version
 kgraph doctor
 kgraph "auth token refresh"
+kgraph repair --dry-run
 ```
 
 Package checks:

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

@@ -1,2 +1,4 @@
 import type { Command } from 'commander';
+import { type CognitionQualityReport } from '../../cognition/cognition-quality.js';
 export declare function registerDoctorCommand(program: Command): void;
+export declare function printQualityReport(report: CognitionQualityReport): void;

package/dist/cli/commands/doctor.js

@@ -1,5 +1,6 @@
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { analyzeCognitionQuality, } from '../../cognition/cognition-quality.js';
 import { loadConfig } from '../../config/config.js';
 import { listIntegrations } from '../../integrations/integration-store.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
@@ -9,7 +10,8 @@ export function registerDoctorCommand(program) {
     program
         .command('doctor')
         .description('Check KGraph workspace health and next actions')
-        .action(() => runCommand(async () => {
+        .option('--quality', 'Report stale or noisy cognition references')
+        .action((options) => runCommand(async () => {
         const rootPath = process.cwd();
         const workspace = resolveWorkspace(rootPath);
         const checks = [];
@@ -37,8 +39,8 @@ export function registerDoctorCommand(program) {
             ok: mapStatus,
             detail: mapStatus ? 'structural maps are present' : 'run `kgraph scan` or just `kgraph`',
         });
-        if (mapStatus) {
-            const maps = await readMaps(workspace);
+        const maps = mapStatus ? await readMaps(workspace) : undefined;
+        if (maps) {
             checks.push({
                 label: 'scan result',
                 ok: true,
@@ -79,6 +81,12 @@ export function registerDoctorCommand(program) {
                     .join('; '),
         });
         printChecks(checks);
+        if (options.quality && maps) {
+            console.log('');
+            console.log('KGraph Cognition Quality');
+            console.log('');
+            printQualityReport(await analyzeCognitionQuality(workspace, maps));
+        }
         if (checks.some((check) => !check.ok)) {
             process.exitCode = 1;
         }
@@ -98,3 +106,23 @@ function printChecks(checks) {
         console.log(`${check.ok ? 'OK' : 'FAIL'}  ${check.label}: ${check.detail}`);
     }
 }
+export function printQualityReport(report) {
+    console.log(`Notes: ${report.noteCount}`);
+    console.log(`Mixed/stale/unresolved notes: ${report.mixedOrStaleCount}`);
+    console.log(`Noisy file refs: ${report.noisyFileRefCount}`);
+    console.log(`Noisy symbol refs: ${report.noisySymbolRefCount}`);
+    if (report.changes.length === 0) {
+        return;
+    }
+    console.log('');
+    for (const change of report.changes) {
+        console.log(`- ${change.title}`);
+        for (const ref of change.removedFileRefs) {
+            console.log(`  remove file ref: ${ref}`);
+        }
+        for (const ref of change.removedSymbolRefs) {
+            console.log(`  remove symbol ref: ${ref}`);
+        }
+        console.log(`  next status: ${change.nextStatus}`);
+    }
+}

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

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

package/dist/cli/commands/repair.js

@@ -0,0 +1,31 @@
+import { repairCognition } from '../../cognition/cognition-quality.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+import { printQualityReport } from './doctor.js';
+export function registerRepairCommand(program) {
+    program
+        .command('repair')
+        .description('Clean noisy stale references from KGraph cognition')
+        .option('--dry-run', 'Show proposed cognition cleanup without writing files')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        if (!(await mapsExist(workspace))) {
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+        }
+        const maps = await readMaps(workspace);
+        const report = await repairCognition(workspace, maps, Boolean(options.dryRun));
+        console.log(options.dryRun
+            ? 'KGraph Repair Dry Run'
+            : 'KGraph Repair');
+        console.log('');
+        printQualityReport(report);
+        if (report.changes.length === 0) {
+            console.log('No noisy cognition references found.');
+        }
+        else if (options.dryRun) {
+            console.log('');
+            console.log('Run `kgraph repair` to apply these changes.');
+        }
+    }));
+}

package/dist/cli/commands/workflow.js

@@ -3,13 +3,19 @@ import { refreshCognitionReferenceStatuses } from '../../cognition/cognition-upd
 import { loadConfig } from '../../config/config.js';
 import { queryContext } from '../../context/context-query.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
-import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { readMaps, writeMaps } from '../../storage/map-store.js';
 import { runCommand } from '../errors.js';
+import { renderRootHelp, renderWorkflowBanner } from '../help.js';
 import { renderContextMarkdown } from './context.js';
 export async function runDefaultWorkflow(query) {
     await runCommand(async () => {
         const topic = query?.trim();
+        const candidateWorkspace = resolveWorkspace(process.cwd());
+        if (!topic && !(await pathExists(candidateWorkspace.kgraphPath))) {
+            console.log(renderRootHelp());
+            return;
+        }
         const workspace = await assertWorkspace(process.cwd());
         const config = await loadConfig(workspace);
         const previousMaps = await readMaps(workspace);
@@ -26,12 +32,16 @@ export async function runDefaultWorkflow(query) {
             symbols: scan.symbols,
         });
         const update = await updateCognition(workspace, { files: scan.files, symbols: scan.symbols }, false);
-        console.log(`KGraph refreshed ${scan.files.length} files, ${scan.symbols.length} symbols, and ${update.processed.length} cognition notes.`);
+        console.log(renderWorkflowBanner({
+            files: scan.files.length,
+            symbols: scan.symbols.length,
+            cognitionNotes: update.processed.length,
+        }));
+        console.log('');
         for (const warning of [...scan.warnings, ...update.warnings]) {
             console.warn(`Warning: ${warning}`);
         }
         if (!topic) {
-            console.log('Add a topic to return compact context, for example: kgraph "auth token refresh"');
             return;
         }
         const maps = await readMaps(workspace);

package/dist/cli/help.d.ts

@@ -1 +1,8 @@
 export declare function renderRootHelp(useColor?: boolean): string;
+interface WorkflowBannerStats {
+    files: number;
+    symbols: number;
+    cognitionNotes: number;
+}
+export declare function renderWorkflowBanner(stats: WorkflowBannerStats, useColor?: boolean): string;
+export {};

package/dist/cli/help.js

@@ -30,6 +30,9 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('context "auth token refresh"', 'Optional: return context without scanning or updating'),
         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'),
         '',
@@ -51,6 +54,27 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
     ].join('\n');
 }
+export function renderWorkflowBanner(stats, useColor = supportsColor()) {
+    const theme = new Chalk({ level: useColor ? 3 : 0 });
+    const command = (name, description) => `  ${theme.green(name.padEnd(30))} ${description}`;
+    return [
+        '',
+        theme.hex('#7dd3fc').bold(renderLogo()),
+        '',
+        `  ${theme.bold('KGraph')} ${theme.dim('repo intelligence refreshed')}`,
+        '',
+        theme.bold('Refresh Complete'),
+        command('files', String(stats.files)),
+        command('symbols', String(stats.symbols)),
+        command('cognition notes processed', String(stats.cognitionNotes)),
+        '',
+        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 --help', 'Show all commands'),
+    ].join('\n');
+}
 function renderLogo() {
     try {
         return figlet.textSync('KGraph', {

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { registerDoctorCommand } from './commands/doctor.js';
 import { registerHistoryCommand } from './commands/history.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 { registerUpdateCommand } from './commands/update.js';
 import { registerVisualizeCommand } from './commands/visualize.js';
@@ -42,6 +43,7 @@ export function createProgram() {
     registerVisualizeCommand(program);
     registerHistoryCommand(program);
     registerDoctorCommand(program);
+    registerRepairCommand(program);
     return program;
 }
 if (isCliEntrypoint()) {

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

@@ -0,0 +1,25 @@
+import type { KGraphWorkspace } from '../types/config.js';
+import type { ReferenceStatus } from '../types/cognition.js';
+import type { FileMap, SymbolMap } from '../types/maps.js';
+export interface CognitionRepairChange {
+    noteId: string;
+    title: string;
+    removedFileRefs: string[];
+    removedSymbolRefs: string[];
+    nextStatus: ReferenceStatus;
+}
+export interface CognitionQualityReport {
+    noteCount: number;
+    mixedOrStaleCount: number;
+    noisyFileRefCount: number;
+    noisySymbolRefCount: number;
+    changes: CognitionRepairChange[];
+}
+export declare function analyzeCognitionQuality(workspace: KGraphWorkspace, maps: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+}): Promise<CognitionQualityReport>;
+export declare function repairCognition(workspace: KGraphWorkspace, maps: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+}, dryRun?: boolean): Promise<CognitionQualityReport>;

package/dist/cognition/cognition-quality.js

@@ -0,0 +1,111 @@
+import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
+export async function analyzeCognitionQuality(workspace, maps) {
+    const notes = await readCognitionNotes(workspace);
+    const changes = notes
+        .map((note) => analyzeNote(note, maps))
+        .filter((change) => change.removedFileRefs.length > 0 ||
+        change.removedSymbolRefs.length > 0);
+    return {
+        noteCount: notes.length,
+        mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
+        noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
+        noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
+        changes,
+    };
+}
+export async function repairCognition(workspace, maps, dryRun = false) {
+    const notes = await readCognitionNotes(workspace);
+    const nextNotes = [];
+    const changes = [];
+    for (const note of notes) {
+        const change = analyzeNote(note, maps);
+        const nextNote = applyChange(note, change);
+        nextNotes.push(nextNote);
+        if (change.removedFileRefs.length > 0 ||
+            change.removedSymbolRefs.length > 0) {
+            changes.push(change);
+            if (!dryRun) {
+                await writeCognitionNote(workspace, nextNote);
+            }
+        }
+    }
+    if (!dryRun && changes.length > 0) {
+        await repairDomainRecords(workspace, nextNotes, maps);
+    }
+    return {
+        noteCount: notes.length,
+        mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
+        noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
+        noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
+        changes,
+    };
+}
+function analyzeNote(note, maps) {
+    const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
+    const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));
+    const removedFileRefs = note.relatedFiles.filter((ref) => !filePaths.has(ref) && isNoisyFileRef(ref));
+    const removedSymbolRefs = note.relatedSymbols.filter((ref) => !symbolNames.has(ref) && isNoisySymbolRef(ref));
+    const nextFiles = note.relatedFiles.filter((ref) => !removedFileRefs.includes(ref));
+    const nextSymbols = note.relatedSymbols.filter((ref) => !removedSymbolRefs.includes(ref));
+    return {
+        noteId: note.id,
+        title: note.title,
+        removedFileRefs,
+        removedSymbolRefs,
+        nextStatus: evaluateReferenceStatus(nextFiles, nextSymbols, maps),
+    };
+}
+function applyChange(note, change) {
+    return {
+        ...note,
+        relatedFiles: note.relatedFiles.filter((ref) => !change.removedFileRefs.includes(ref)),
+        relatedSymbols: note.relatedSymbols.filter((ref) => !change.removedSymbolRefs.includes(ref)),
+        referencesStatus: change.nextStatus,
+    };
+}
+async function repairDomainRecords(workspace, notes, maps) {
+    const domains = await readDomainRecords(workspace);
+    const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
+    const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));
+    const notesById = new Map(notes.map((note) => [note.id, note]));
+    for (const domain of domains) {
+        const relatedNotes = domain.cognitionNotes
+            .map((id) => notesById.get(id))
+            .filter((note) => Boolean(note));
+        const next = {
+            ...domain,
+            pathHints: unique(relatedNotes.flatMap((note) => note.relatedFiles)),
+            files: unique(relatedNotes
+                .flatMap((note) => note.relatedFiles)
+                .filter((file) => filePaths.has(file))),
+            symbols: unique(relatedNotes
+                .flatMap((note) => note.relatedSymbols)
+                .filter((symbol) => symbolNames.has(symbol))),
+        };
+        await overwriteDomainRecord(workspace, next);
+    }
+}
+function evaluateReferenceStatus(relatedFiles, relatedSymbols, maps) {
+    const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
+    const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));
+    const references = [
+        ...relatedFiles.map((file) => filePaths.has(file)),
+        ...relatedSymbols.map((symbol) => symbolNames.has(symbol)),
+    ];
+    if (references.length === 0)
+        return 'unresolved';
+    if (references.every(Boolean))
+        return 'current';
+    if (references.every((value) => !value))
+        return 'stale';
+    return 'mixed';
+}
+function isNoisyFileRef(ref) {
+    return !ref.includes('/') && /^[A-Z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(ref);
+}
+function isNoisySymbolRef(ref) {
+    return /^[a-z][A-Za-z0-9_$]*$/.test(ref);
+}
+function unique(items) {
+    return [...new Set(items)];
+}

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

@@ -14,33 +14,41 @@ Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intell
 1. Infer the topic from the user's request.
 2. Run \`kgraph "<topic>"\`. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
-4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
-5. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
-6. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph\` or \`kgraph scan\` and report the summary. Skip it otherwise.
-7. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-8. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+5. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+6. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+7. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+8. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+10. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+11. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown
 # <Short Title>
 
 ## Summary
-One or two sentences describing what was done.
+One or two sentences describing the durable change or finding.
 
 ## Key Files
-- \`path/to/file.ts\` — what it does
+- \`path/to/file.ts\` — what changed or why it matters
 
 ## Key Symbols
-- \`FunctionName\` — what it does
+- \`FunctionName\` — what changed or why it matters
 
 ## Decisions
-Any architectural or implementation decisions made.
+Any implementation or product decision future sessions should know.
 \`\`\`
 `,
         },
         {
             path: '.claude/commands/kgraph-doctor.md',
-            content: `Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Summarize any failed checks and the next command to run.
+            content: `Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-repair.md',
+            content: `Run \`kgraph repair --dry-run\` first and summarize the proposed cognition cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
 `,
         },
         {

package/dist/integrations/adapters/codex.js

@@ -21,27 +21,30 @@ Workflow:
 1. Infer the current topic from the user request.
 2. Run \`kgraph "<topic>"\` before broad repo exploration. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
 3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
-4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
-5. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
-6. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph\` or \`kgraph scan\`. Skip it otherwise.
-7. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-8. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+5. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+6. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+7. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+8. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+10. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+11. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown
 # <Short Title>
 
 ## Summary
-One or two sentences describing what was done.
+One or two sentences describing the durable change or finding.
 
 ## Key Files
-- \`path/to/file.ts\` — what it does
+- \`path/to/file.ts\` — what changed or why it matters
 
 ## Key Symbols
-- \`FunctionName\` — what it does
+- \`FunctionName\` — what changed or why it matters
 
 ## Decisions
-Any architectural or implementation decisions made.
+Any implementation or product decision future sessions should know.
 \`\`\`
 `,
         },

package/dist/integrations/adapters/copilot.js

@@ -5,9 +5,12 @@ export const copilotAdapter = {
     instructions: `## KGraph Workflow
 
 1. **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
-2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
-3. **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, architectural constraint, non-obvious decision, or bug. For routine or read-only sessions where nothing new was found, skip capture entirely. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
-4. If you created, moved, deleted, or renamed files or symbols, run \`kgraph\` or \`kgraph scan\`.
+2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+3. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+4. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+5. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+6. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -34,7 +37,18 @@ description: Check KGraph workspace health and next actions
 agent: agent
 ---
 
-Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Summarize any failed checks and the next command to run.
+Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-repair.prompt.md',
+            content: `---
+description: Preview or clean stale/noisy KGraph cognition references
+agent: agent
+argument-hint: "--dry-run or apply"
+---
+
+Run \`kgraph repair --dry-run\` first and summarize the proposed cognition cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
 `,
         },
         {
@@ -77,9 +91,10 @@ argument-hint: "Brief description of what was done"
 
 Capture this session into KGraph cognition.
 
-1. Write a Markdown note to \`.kgraph/inbox/<slug>.md\` using the structure below. Use the user's message as the summary if provided.
-2. Immediately run \`kgraph update\`.
-3. If files or symbols were created, moved, deleted, or renamed, also run \`kgraph scan\`.
+1. For any completed code or repo-file change, check whether it has future value before finishing.
+2. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+3. Write one Markdown note to \`.kgraph/inbox/<slug>.md\` using the structure below. Use the user's message as context, but keep the note factual and concise.
+4. Run \`kgraph\` once to process the note and refresh maps. Use \`kgraph update\` only when you intentionally want inbox processing without a scan.
 
 Note structure:
 \`\`\`markdown

package/dist/integrations/adapters/cursor.js

@@ -10,9 +10,12 @@ alwaysApply: true
 ## KGraph Workflow
 
 - **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
-- **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` (title, Key Files, Key Symbols, Decisions sections) **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
-- If you created, moved, deleted, or renamed files or symbols, run \`kgraph\` or \`kgraph scan\`.
+- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
+- At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
+- If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
+- Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+- Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 `,

package/dist/scanner/ts-symbol-extractor.js

@@ -73,6 +73,12 @@ export function extractTsSymbols(sourceText, filePath) {
                 }
             });
         }
+        if (ts.isInterfaceDeclaration(node)) {
+            addSymbol(node.name.text, "interface", node, isExported(node), parentName);
+        }
+        if (ts.isTypeAliasDeclaration(node)) {
+            addSymbol(node.name.text, "type", node, isExported(node), parentName);
+        }
         ts.forEachChild(node, (child) => visit(child, parentName));
     };
     try {

package/dist/storage/cognition-store.d.ts

@@ -4,6 +4,7 @@ export declare function listInboxNotes(workspace: KGraphWorkspace): Promise<stri
 export declare function archiveInboxNote(workspace: KGraphWorkspace, inboxPath: string, timestamp: string): Promise<string>;
 export declare function writeCognitionNote(workspace: KGraphWorkspace, note: CognitionNote): Promise<string>;
 export declare function writeDomainRecord(workspace: KGraphWorkspace, domain: DomainRecord): Promise<string>;
+export declare function overwriteDomainRecord(workspace: KGraphWorkspace, domain: DomainRecord): Promise<string>;
 export declare function readCognitionNotes(workspace: KGraphWorkspace): Promise<CognitionNote[]>;
 export declare function readDomainRecords(workspace: KGraphWorkspace): Promise<DomainRecord[]>;
 export declare function slugify(value: string): string;

package/dist/storage/cognition-store.js

@@ -33,6 +33,12 @@ export async function writeDomainRecord(workspace, domain) {
     await writeFile(filePath, renderDomainRecord(merged), "utf8");
     return filePath;
 }
+export async function overwriteDomainRecord(workspace, domain) {
+    await mkdir(workspace.domainsPath, { recursive: true });
+    const filePath = path.join(workspace.domainsPath, `${slugify(domain.name)}.md`);
+    await writeFile(filePath, renderDomainRecord(domain), "utf8");
+    return filePath;
+}
 export async function readCognitionNotes(workspace) {
     if (!(await pathExists(workspace.cognitionPath))) {
         return [];

package/dist/types/maps.d.ts

@@ -1,6 +1,6 @@
 export type ScanStatus = "mapped" | "generic" | "failed";
 export type DependencyKind = "local" | "package" | "unknown";
-export type SymbolKind = "function" | "class" | "method" | "export" | "import";
+export type SymbolKind = "function" | "class" | "method" | "type" | "interface" | "export" | "import";
 export type RelationshipType = "import" | "contains" | "mentions" | "belongs-to-domain" | "stale-reference" | "moved-from";
 export interface RepositoryFile {
     id: string;

package/package.json

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