@kentwynn/kgraph 0.1.18 → 0.1.20

package/README.md

@@ -2,7 +2,7 @@
 
 Persistent repository intelligence for AI coding tools.
 
-KGraph gives Codex, GitHub Copilot, Cursor, and Claude Code a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable notes from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
+KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable notes from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
 
 ## The Workflow
 
@@ -10,7 +10,7 @@ Use KGraph in two steps:
 
 ```bash
 # Required once per repository
-kgraph init --integrations codex,copilot,cursor,claude-code
+kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline
 
 # Normal daily command
 kgraph "auth token refresh"
@@ -89,7 +89,7 @@ From the root of a repository:
 kgraph init
 
 # 2. Optional: connect AI tools so they know the KGraph workflow
-kgraph integrate add codex copilot cursor claude-code
+kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
 
 # 3. Run the normal workflow for a topic
 kgraph "auth token refresh"
@@ -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
@@ -109,7 +120,7 @@ kgraph init
 Required once per repo. Creates `.kgraph/` and the local config.
 
 ```bash
-kgraph init --integrations codex,copilot,cursor,claude-code
+kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline
 ```
 
 Initializes KGraph and writes local instruction files for supported AI tools.
@@ -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.
+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
+```
+
+`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
 
@@ -177,7 +196,7 @@ Show processed cognition sessions.
 KGraph integrations are local files. They do not start background agents, call AI providers, or send data anywhere.
 
 ```bash
-kgraph integrate add codex copilot cursor claude-code
+kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
 kgraph integrate list
 kgraph integrate remove cursor
 ```
@@ -188,6 +207,11 @@ kgraph integrate remove cursor
 | GitHub Copilot | `.github/copilot-instructions.md`, `.github/prompts/*` |
 | Cursor | `.cursor/rules/kgraph.mdc` |
 | Claude Code | `CLAUDE.md`, `.claude/commands/*` |
+| Gemini CLI | `GEMINI.md` |
+| Windsurf | `.windsurf/rules/kgraph.md` |
+| Cline | `.clinerules/kgraph.md` |
+
+Antigravity is supported through the existing agent instruction surfaces it can read, especially `AGENTS.md` and `GEMINI.md`; it does not need a separate KGraph adapter yet.
 
 KGraph preserves existing user-authored content and updates only its marked instruction blocks or generated command files.
 
@@ -255,6 +279,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 +291,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

@@ -2,7 +2,7 @@ import { Chalk } from 'chalk';
 import figlet from 'figlet';
 export function renderRootHelp(useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
-    const command = (name, description) => `  ${theme.green(name.padEnd(30))} ${description}`;
+    const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
     const logo = renderLogo();
     return [
         '',
@@ -11,7 +11,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         `  ${theme.bold('KGraph')} ${theme.dim('Persistent repo intelligence for AI coding tools')}`,
         '',
         `  ${theme.hex('#c084fc')('Build a local knowledge layer that helps Codex, Copilot, Cursor,')}`,
-        `  ${theme.hex('#c084fc')('and Claude Code reuse repo structure, decisions, and debugging history.')}`,
+        `  ${theme.hex('#c084fc')('Claude Code, Gemini, Windsurf, and Cline reuse repo intelligence.')}`,
         '',
         theme.bold('Usage'),
         '  kgraph [topic]',
@@ -19,7 +19,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         theme.bold('Start'),
         command('init', 'Required once: create .kgraph/ workspace'),
-        command('init --integrations codex,cursor', 'Initialize and connect AI tools'),
+        command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
         '',
         theme.bold('Daily workflow'),
         command('kgraph', 'Refresh scan maps and process pending cognition notes'),
@@ -30,12 +30,15 @@ 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'),
         '',
         theme.bold('Integrations'),
         command('integrate list', 'Show configured AI tool integrations'),
-        command('integrate add codex copilot', 'Write KGraph instructions for AI tools'),
+        command('integrate add gemini windsurf cline', 'Write KGraph instructions for AI tools'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         '',
         theme.bold('Options'),
@@ -43,7 +46,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('-h, --help', 'Show this help'),
         '',
         `${theme.yellow('Examples')}`,
-        '  kgraph init --integrations codex,copilot,cursor',
+        '  kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline',
         '  kgraph "blog admin token usage"',
         '  kgraph doctor',
         '',
@@ -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(42))} ${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/config/config.js

@@ -25,10 +25,13 @@ export const DEFAULT_CONFIG = {
         'specs',
         '.cursor',
         '.claude',
+        '.windsurf',
+        '.clinerules',
         '.github/copilot-instructions.md',
         '.github/prompts',
         'AGENTS.md',
         'CLAUDE.md',
+        'GEMINI.md',
         'REQUIREMENTS.md',
         '*.log',
         '*.tgz',
@@ -132,7 +135,15 @@ function normalizeIntegrations(value) {
             seen.has(candidate.name)) {
             continue;
         }
-        if (!['claude-code', 'codex', 'copilot', 'cursor'].includes(candidate.name)) {
+        if (![
+            'claude-code',
+            'cline',
+            'codex',
+            'copilot',
+            'cursor',
+            'gemini',
+            'windsurf',
+        ].includes(candidate.name)) {
             continue;
         }
         seen.add(candidate.name);

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/cline.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from '../integration-registry.js';
+export declare const clineAdapter: IntegrationAdapter;

package/dist/integrations/adapters/cline.js

@@ -0,0 +1,17 @@
+export const clineAdapter = {
+    name: 'cline',
+    label: 'Cline',
+    targetPath: '.clinerules/kgraph.md',
+    instructions: `# 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 --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/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/integrations/adapters/gemini.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from '../integration-registry.js';
+export declare const geminiAdapter: IntegrationAdapter;

package/dist/integrations/adapters/gemini.js

@@ -0,0 +1,17 @@
+export const geminiAdapter = {
+    name: 'gemini',
+    label: 'Gemini CLI',
+    targetPath: 'GEMINI.md',
+    instructions: `## 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 --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/integrations/adapters/windsurf.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationAdapter } from '../integration-registry.js';
+export declare const windsurfAdapter: IntegrationAdapter;

package/dist/integrations/adapters/windsurf.js

@@ -0,0 +1,17 @@
+export const windsurfAdapter = {
+    name: 'windsurf',
+    label: 'Windsurf',
+    targetPath: '.windsurf/rules/kgraph.md',
+    instructions: `# 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 --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/integrations/integration-registry.js

@@ -1,12 +1,18 @@
 import { claudeCodeAdapter } from "./adapters/claude-code.js";
+import { clineAdapter } from "./adapters/cline.js";
 import { codexAdapter } from "./adapters/codex.js";
 import { copilotAdapter } from "./adapters/copilot.js";
 import { cursorAdapter } from "./adapters/cursor.js";
+import { geminiAdapter } from "./adapters/gemini.js";
+import { windsurfAdapter } from "./adapters/windsurf.js";
 const ADAPTERS = [
     claudeCodeAdapter,
+    clineAdapter,
     codexAdapter,
     copilotAdapter,
-    cursorAdapter
+    cursorAdapter,
+    geminiAdapter,
+    windsurfAdapter
 ].sort((left, right) => left.name.localeCompare(right.name));
 export function listIntegrationAdapters() {
     return ADAPTERS;

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/config.d.ts

@@ -12,7 +12,7 @@ export interface DomainHint {
     paths?: string[];
     tags?: string[];
 }
-export type IntegrationName = "claude-code" | "codex" | "copilot" | "cursor";
+export type IntegrationName = "claude-code" | "cline" | "codex" | "copilot" | "cursor" | "gemini" | "windsurf";
 export interface IntegrationConfig {
     name: IntegrationName;
     enabled: boolean;

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.20",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {