@kentwynn/kgraph 0.1.18 → 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,13 +14,14 @@ 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.
+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 visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-10. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+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
@@ -42,7 +43,12 @@ 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,13 +21,14 @@ 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.
+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 visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-10. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+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

package/dist/integrations/adapters/copilot.js

@@ -5,11 +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.
+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
@@ -36,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.
 `,
         },
         {

package/dist/integrations/adapters/cursor.js

@@ -10,11 +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.
+- 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.18",
+  "version": "0.1.19",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {