@kentwynn/kgraph 0.2.3 → 0.2.5

package/README.md

@@ -267,7 +267,7 @@ kgraph integrate list
 kgraph integrate remove cursor
 ```
 
-New integrations default to `always` mode because coding agents often under-classify small UI, route, button, and link changes as not needing repo context.
+New integrations default to `smart` mode. Use `--mode always` to force KGraph on every chat, or `--mode manual` to run only when explicitly asked.
 
 | Mode     | Behavior                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/dist/cli/commands/doctor.js

@@ -3,6 +3,7 @@ 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 { getCurrentCommit, isGitRepo } from '../../scanner/git-utils.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { mapPaths, mapsExist, readMaps } from '../../storage/map-store.js';
 import { runCommand } from '../errors.js';
@@ -37,7 +38,9 @@ export function registerDoctorCommand(program) {
         checks.push({
             label: 'maps',
             ok: mapStatus,
-            detail: mapStatus ? 'structural maps are present' : 'run `kgraph scan` or just `kgraph`',
+            detail: mapStatus
+                ? 'structural maps are present'
+                : 'run `kgraph scan` or just `kgraph`',
         });
         const maps = mapStatus ? await readMaps(workspace) : undefined;
         if (maps) {
@@ -46,6 +49,19 @@ export function registerDoctorCommand(program) {
                 ok: true,
                 detail: `${maps.fileMap.files.length} files, ${maps.symbolMap.symbols.length} symbols, ${maps.dependencyMap.dependencies.length} dependencies`,
             });
+            // Detect whether the repo has advanced past the commit that was scanned
+            if (maps.fileMap.scannedAtCommit && (await isGitRepo(rootPath))) {
+                const headCommit = await getCurrentCommit(rootPath);
+                const stale = headCommit !== null &&
+                    headCommit !== maps.fileMap.scannedAtCommit;
+                checks.push({
+                    label: 'scan freshness',
+                    ok: !stale,
+                    detail: stale
+                        ? `scanned at ${maps.fileMap.scannedAtCommit.slice(0, 7)}, HEAD is ${headCommit.slice(0, 7)} — run \`kgraph scan\``
+                        : `maps current at ${maps.fileMap.scannedAtCommit.slice(0, 7)}`,
+                });
+            }
         }
         else {
             const paths = mapPaths(workspace);
@@ -125,6 +141,7 @@ function printChecks(checks) {
 export function printQualityReport(report) {
     console.log(`Notes: ${report.noteCount}`);
     console.log(`Mixed/stale/unresolved notes: ${report.mixedOrStaleCount}`);
+    console.log(`Orphaned notes (all refs dead): ${report.orphanedNoteCount}`);
     console.log(`Noisy file refs: ${report.noisyFileRefCount}`);
     console.log(`Noisy symbol refs: ${report.noisySymbolRefCount}`);
     console.log(`Unresolved local imports: ${report.unresolvedLocalImportCount}`);
@@ -152,6 +169,9 @@ export function printQualityReport(report) {
 }
 function summarizeQualityFindings(report) {
     const findings = [];
+    if (report.orphanedNoteCount > 0) {
+        findings.push(`${report.orphanedNoteCount} orphaned cognition note(s) (all refs dead); run \`kgraph repair\` to archive`);
+    }
     if (report.mixedOrStaleCount > 0) {
         findings.push(`${report.mixedOrStaleCount} stale/mixed/unresolved note(s)`);
     }

package/dist/cli/commands/init.js

@@ -14,7 +14,7 @@ export function registerInitCommand(program) {
         .description('Initialize a .kgraph workspace')
         .option('--integration <name>', 'Configure an AI tool integration', collectOption, [])
         .option('--integrations <names>', 'Configure comma-separated AI tool integrations')
-        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
+        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'smart')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         const wroteConfig = await writeDefaultConfig(workspace);
@@ -53,7 +53,7 @@ export function registerInitCommand(program) {
         })) {
             const selected = await promptForInitIntegrations(recommendedIntegrations);
             if (selected.length > 0) {
-                const changed = await addIntegrations(workspace, selected, 'always');
+                const changed = await addIntegrations(workspace, selected, 'smart');
                 console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
                 config = await loadConfig(workspace);
                 recommendedIntegrations = recommendedIntegrationsForInit({

package/dist/cli/commands/integrate.js

@@ -25,7 +25,7 @@ export function registerIntegrateCommand(program) {
         .command('add')
         .description('Add AI tool integrations')
         .argument('<names...>')
-        .option('--mode <mode>', 'always, smart, manual, or off', 'always')
+        .option('--mode <mode>', 'always, smart, manual, or off', 'smart')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);

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

@@ -1,5 +1,5 @@
-import type { KGraphWorkspace } from '../types/config.js';
 import type { ReferenceStatus } from '../types/cognition.js';
+import type { KGraphWorkspace } from '../types/config.js';
 import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from '../types/maps.js';
 export interface CognitionRepairChange {
     noteId: string;
@@ -21,6 +21,7 @@ export interface CognitionQualityReport {
     sessionRepeatedReadCount: number;
     sessionEstimatedReadTokens: number;
     sessionEstimatedRepeatedReadTokens: number;
+    orphanedNoteCount: number;
     changes: CognitionRepairChange[];
 }
 export declare function analyzeCognitionQuality(workspace: KGraphWorkspace, maps: {

package/dist/cognition/cognition-quality.js

@@ -1,5 +1,7 @@
-import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
+import { mkdir, rename } from 'node:fs/promises';
+import path from 'node:path';
 import { buildSessionReport } from '../session/session-store.js';
+import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
 export async function analyzeCognitionQuality(workspace, maps) {
     const notes = await readCognitionNotes(workspace);
     const session = await buildSessionReport(workspace);
@@ -7,6 +9,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         .map((note) => analyzeNote(note, maps))
         .filter((change) => change.removedFileRefs.length > 0 ||
         change.removedSymbolRefs.length > 0);
+    const orphanedNoteCount = notes.filter((note) => note.referencesStatus === 'stale').length;
     return {
         noteCount: notes.length,
         mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
@@ -20,6 +23,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         sessionRepeatedReadCount: session.repeatedReadCount,
         sessionEstimatedReadTokens: session.estimatedReadTokens,
         sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
+        orphanedNoteCount,
         changes,
     };
 }
@@ -40,9 +44,18 @@ export async function repairCognition(workspace, maps, dryRun = false) {
             }
         }
     }
-    if (!dryRun && changes.length > 0) {
-        await repairDomainRecords(workspace, nextNotes, maps);
+    // Archive fully-orphaned notes (all refs dead) so they no longer appear in context
+    const orphanedNotes = nextNotes.filter((note) => note.referencesStatus === 'stale');
+    if (!dryRun && (changes.length > 0 || orphanedNotes.length > 0)) {
+        // Exclude fully-orphaned notes from domain records — they are being archived
+        await repairDomainRecords(workspace, nextNotes.filter((n) => n.referencesStatus !== 'stale'), maps);
+    }
+    if (!dryRun) {
+        for (const note of orphanedNotes) {
+            await archiveOrphanedNote(workspace, note);
+        }
     }
+    const orphanedNoteCount = orphanedNotes.length;
     return {
         noteCount: notes.length,
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
@@ -56,6 +69,7 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         sessionRepeatedReadCount: session.repeatedReadCount,
         sessionEstimatedReadTokens: session.estimatedReadTokens,
         sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
+        orphanedNoteCount,
         changes,
     };
 }
@@ -98,7 +112,8 @@ function countGeneratedScannedFiles(fileMap) {
     ].some((prefix) => file.path === prefix || file.path.startsWith(prefix))).length;
 }
 function countExpensiveFiles(fileMap) {
-    return fileMap.files.filter((file) => (file.tokenEstimate ?? 0) >= 1000).length;
+    return fileMap.files.filter((file) => (file.tokenEstimate ?? 0) >= 1000)
+        .length;
 }
 function analyzeNote(note, maps) {
     const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
@@ -161,11 +176,27 @@ function evaluateReferenceStatus(relatedFiles, relatedSymbols, maps) {
     return 'mixed';
 }
 function isNoisyFileRef(ref) {
-    return !ref.includes('/') && /^[A-Z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(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);
+    // Only treat as noise if the ref is a short all-lowercase word (no camelCase, no _ or $).
+    // Preserve camelCase refs even when unresolved — the symbol may have been renamed.
+    if (/[A-Z_$]/.test(ref))
+        return false;
+    return ref.length <= 5;
 }
 function unique(items) {
     return [...new Set(items)];
 }
+async function archiveOrphanedNote(workspace, note) {
+    const archivedDir = path.join(workspace.cognitionPath, 'archived');
+    await mkdir(archivedDir, { recursive: true });
+    const source = path.join(workspace.cognitionPath, `${note.id}.md`);
+    const target = path.join(archivedDir, `${note.id}.md`);
+    try {
+        await rename(source, target);
+    }
+    catch {
+        // source file may already be missing — ignore
+    }
+}

package/dist/cognition/cognition-updater.js

@@ -11,7 +11,11 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
             const raw = await readFile(inboxPath, 'utf8');
             const parsed = parseMarkdownNote(raw);
             const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-            const id = `${timestamp}-${slugify(parsed.title) || path.basename(inboxPath, '.md')}`;
+            // Always include the inbox basename as a per-note unique suffix so two notes with
+            // the same title processed in the same millisecond never receive the same ID.
+            const base = path.basename(inboxPath, '.md');
+            const slug = slugify(parsed.title);
+            const id = slug ? `${timestamp}-${slug}-${base}` : `${timestamp}-${base}`;
             const archivedPath = path.join(workspace.processedInteractionsPath, `${timestamp}-${path.basename(inboxPath)}`);
             const note = {
                 ...parsed,
@@ -39,6 +43,11 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
             warnings.push(`${path.basename(inboxPath)}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    // Refresh reference statuses on all existing notes so that notes which
+    // became stale since the last scan reflect the current map state.
+    if (!dryRun) {
+        await refreshCognitionReferenceStatuses(workspace, currentMaps);
+    }
     return { processed, warnings };
 }
 export async function refreshCognitionReferenceStatuses(workspace, currentMaps) {

package/dist/cognition/markdown-note-parser.js

@@ -14,7 +14,7 @@ export function parseMarkdownNote(markdown) {
         tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
         summary: sections.Summary,
         sections,
-        relatedFiles: unique(extractMatches(combined, PATH_REF)),
+        relatedFiles: unique(extractMatches(stripCodeFences(combined), PATH_REF)),
         relatedSymbols: unique(extractSymbolRefs(sections)),
         warnings,
     };
@@ -70,3 +70,8 @@ function extractSymbolRefs(sections) {
 function unique(items) {
     return [...new Set(items)];
 }
+function stripCodeFences(text) {
+    // Remove triple-backtick code blocks so paths inside code examples are not
+    // mistaken for real file references, which would create phantom stale refs.
+    return text.replace(/```[\s\S]*?```/g, '');
+}

package/dist/context/context-query.js

@@ -5,10 +5,16 @@ export async function queryContext(workspace, config, maps, query) {
     const cognition = await readCognitionNotes(workspace);
     const domains = await readDomainRecords(workspace);
     const max = config.maxContextItems;
-    const relevantFiles = rankByFields(query, maps.fileMap.files, [
+    let relevantFiles = rankByFields(query, maps.fileMap.files, [
         { name: 'path', value: (file) => file.path },
         { name: 'language', value: (file) => file.language },
-    ]).slice(0, max);
+    ])
+        .map((ranked) => ({
+        ...ranked,
+        score: ranked.score - Math.floor((ranked.item.tokenEstimate ?? 0) / 2000),
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, max);
     const relevantSymbols = rankByFields(query, maps.symbolMap.symbols, [
         { name: 'name', value: (symbol) => symbol.name },
         { name: 'path', value: (symbol) => symbol.filePath },
@@ -28,6 +34,57 @@ export async function queryContext(workspace, config, maps, query) {
         { name: 'tags', value: (domain) => domain.tags },
         { name: 'path', value: (domain) => domain.pathHints },
     ]).slice(0, max);
+    // Inject files linked by matched cognition notes/domains that didn't score on name alone
+    const rankedFilePaths = new Set(relevantFiles.map((f) => f.item.path));
+    const cognitionLinkedMap = new Map();
+    for (const ranked of relevantCognition) {
+        for (const fp of ranked.item.relatedFiles) {
+            if (!rankedFilePaths.has(fp)) {
+                const reasons = cognitionLinkedMap.get(fp) ?? [];
+                reasons.push(`linked by cognition note "${ranked.item.title}"`);
+                cognitionLinkedMap.set(fp, reasons);
+            }
+        }
+    }
+    for (const ranked of matchedDomains) {
+        for (const fp of ranked.item.files) {
+            if (!rankedFilePaths.has(fp)) {
+                const reasons = cognitionLinkedMap.get(fp) ?? [];
+                reasons.push(`in domain "${ranked.item.name}"`);
+                cognitionLinkedMap.set(fp, reasons);
+            }
+        }
+    }
+    // Apply domainHints from config: inject paths for hints whose name matches the query
+    const queryTokens = new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+    for (const [hintName, hint] of Object.entries(config.domainHints)) {
+        const hintWords = hintName
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(Boolean);
+        if (!hintWords.some((w) => queryTokens.has(w)))
+            continue;
+        for (const fp of hint.paths ?? []) {
+            if (!rankedFilePaths.has(fp)) {
+                const reasons = cognitionLinkedMap.get(fp) ?? [];
+                reasons.push(`in configured domain hint "${hintName}"`);
+                cognitionLinkedMap.set(fp, reasons);
+            }
+        }
+    }
+    relevantFiles = [
+        ...relevantFiles,
+        ...maps.fileMap.files
+            .filter((f) => cognitionLinkedMap.has(f.path))
+            .map((f) => ({
+            item: f,
+            score: 1,
+            reasons: cognitionLinkedMap.get(f.path),
+        })),
+    ];
     const relatedIds = new Set([
         ...relevantFiles.map((file) => file.item.path),
         ...relevantSymbols.map((symbol) => symbol.item.id),
@@ -69,10 +126,12 @@ export async function queryContext(workspace, config, maps, query) {
     });
     const filePaths = new Set(maps.fileMap.files.map((f) => f.path));
     const symbolNames = new Set(maps.symbolMap.symbols.map((s) => s.name));
+    const matchedCognitionIds = new Set(relevantCognition.map((r) => r.item.id));
     const staleReferences = cognition
-        .filter((note) => note.referencesStatus === 'stale' ||
-        note.referencesStatus === 'unresolved' ||
-        note.referencesStatus === 'mixed')
+        .filter((note) => matchedCognitionIds.has(note.id) &&
+        (note.referencesStatus === 'stale' ||
+            note.referencesStatus === 'unresolved' ||
+            note.referencesStatus === 'mixed'))
         .flatMap((note) => [
         ...note.relatedFiles
             .filter((f) => !filePaths.has(f))
@@ -98,9 +157,18 @@ export async function queryContext(workspace, config, maps, query) {
     // Remove files already in the matched set
     for (const p of matchedFilePaths)
         importedFilePaths.delete(p);
+    // Skip generic utility/barrel files with many exports — surface only focused modules
+    const exportCountByFile = new Map();
+    for (const s of maps.symbolMap.symbols) {
+        if (s.exported) {
+            exportCountByFile.set(s.filePath, (exportCountByFile.get(s.filePath) ?? 0) + 1);
+        }
+    }
+    const MAX_NEARBY_FILE_EXPORTS = 15;
+    const relevantImportedFilePaths = new Set([...importedFilePaths].filter((fp) => (exportCountByFile.get(fp) ?? 0) <= MAX_NEARBY_FILE_EXPORTS));
     const nearbySymbols = maps.symbolMap.symbols
         .filter((s) => s.exported &&
-        importedFilePaths.has(s.filePath) &&
+        relevantImportedFilePaths.has(s.filePath) &&
         !matchedSymbolIds.has(s.id))
         .slice(0, max);
     const nearbySymbolExplanations = nearbySymbols.map((symbol) => ({

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

@@ -1,3 +1,4 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const claudeCodeAdapter = {
     name: 'claude-code',
     label: 'Claude Code',
@@ -11,18 +12,7 @@ export const claudeCodeAdapter = {
             path: '.claude/commands/kgraph.md',
             content: `Use KGraph persistent repo intelligence for the current request.
 
-1. Infer the topic from the user's request.
-2. {{KGRAPH_CONTEXT_POLICY}}
-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. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. Track meaningful session activity with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code\` when native hooks are unavailable.
-6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-
-{{KGRAPH_CAPTURE_POLICY}}
-
-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.
-8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are unavailable' })}
 `,
         },
         {

package/dist/integrations/adapters/cline.js

@@ -1,16 +1,10 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const clineAdapter = {
     name: 'cline',
     label: 'Cline',
     targetPath: '.clinerules/kgraph.md',
     instructions: `# KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent cline\`, \`kgraph session read <path> --agent cline\`, \`kgraph session write <path> --agent cline\`, and \`kgraph session end --agent cline\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('cline')}
 `,
 };

package/dist/integrations/adapters/codex.js

@@ -1,3 +1,4 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const codexAdapter = {
     name: 'codex',
     label: 'Codex',
@@ -18,23 +19,12 @@ description: Use KGraph persistent repo intelligence according to the configured
 
 Workflow:
 
-1. Infer the current topic from the user request.
-2. {{KGRAPH_CONTEXT_POLICY}}
-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. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. Track meaningful session activity with \`kgraph session start --agent codex\`, \`kgraph session read <path> --agent codex\`, \`kgraph session write <path> --agent codex\`, and \`kgraph session end --agent codex\`.
-6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-
-{{KGRAPH_CAPTURE_POLICY}}
-
-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.
-8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${numberedWorkflow('codex')}
 `,
         },
     ],
     obsoleteCommandFiles: [
-        '.agents/skills/kgraph-update',
-        '.agents/skills/kgraph-scan',
+        '.agents/skills/kgraph-scan/SKILL.md',
+        '.agents/skills/kgraph-update/SKILL.md',
     ],
 };

package/dist/integrations/adapters/copilot.js

@@ -1,19 +1,33 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const copilotAdapter = {
     name: 'copilot',
     label: 'GitHub Copilot',
     targetPath: '.github/copilot-instructions.md',
     instructions: `## KGraph Workflow
 
-1. {{KGRAPH_CONTEXT_POLICY}}
-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. Track meaningful session activity with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot\`.
-4. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+${numberedWorkflow('copilot')}
+`,
+    commandFiles: [
+        {
+            path: '.github/agents/kgraph.agent.md',
+            content: `---
+name: kgraph
+description: Use KGraph persistent repo intelligence to answer questions about this codebase. Runs kgraph context, scan, update, impact, history, and session commands to ground responses in durable local knowledge.
+tools:
+  - run_in_terminal
+  - read_file
+  - file_search
+  - grep_search
+  - semantic_search
+---
 
-{{KGRAPH_CAPTURE_POLICY}}
+## KGraph Agent
+
+You are a KGraph-powered agent. Before exploring the repository freely, always:
 
-5. 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.
+${numberedWorkflow('copilot')}
 `,
-    commandFiles: [
+        },
         {
             path: '.github/prompts/kgraph-doctor.prompt.md',
             content: `---
@@ -112,5 +126,8 @@ Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed c
 `,
         },
     ],
-    obsoleteCommandFiles: ['.github/prompts/kgraph.prompt.md'],
+    obsoleteCommandFiles: [
+        '.github/prompts/kgraph.prompt.md',
+        '.github/kgraph.agent.md',
+    ],
 };

package/dist/integrations/adapters/cursor.js

@@ -1,3 +1,4 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const cursorAdapter = {
     name: 'cursor',
     label: 'Cursor',
@@ -9,14 +10,7 @@ alwaysApply: true
 
 ## KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent cursor\`, \`kgraph session read <path> --agent cursor\`, \`kgraph session write <path> --agent cursor\`, and \`kgraph session end --agent cursor\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('cursor')}
 `,
     obsoleteCommandFiles: ['.cursor/rules/kgraph-commands.mdc'],
 };

package/dist/integrations/adapters/gemini.js

@@ -1,16 +1,10 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const geminiAdapter = {
     name: 'gemini',
     label: 'Gemini CLI',
     targetPath: 'GEMINI.md',
     instructions: `## KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent gemini\`, \`kgraph session read <path> --agent gemini\`, \`kgraph session write <path> --agent gemini\`, and \`kgraph session end --agent gemini\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('gemini')}
 `,
 };

package/dist/integrations/adapters/windsurf.js

@@ -1,16 +1,10 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const windsurfAdapter = {
     name: 'windsurf',
     label: 'Windsurf',
     targetPath: '.windsurf/rules/kgraph.md',
     instructions: `# KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent windsurf\`, \`kgraph session read <path> --agent windsurf\`, \`kgraph session write <path> --agent windsurf\`, and \`kgraph session end --agent windsurf\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('windsurf')}
 `,
 };

package/dist/integrations/integration-store.js

@@ -15,7 +15,7 @@ export async function listIntegrations(workspace) {
     })));
     return statuses.sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function addIntegrations(workspace, names, mode = 'always') {
+export async function addIntegrations(workspace, names, mode = 'smart') {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];

package/dist/integrations/workflow-steps.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared KGraph workflow step strings used across all AI tool adapters.
+ * Update here once instead of in each adapter file.
+ */
+export interface WorkflowOptions {
+    /** Qualifier appended to the session step, e.g. "when native hooks are unavailable" */
+    sessionQualifier?: string;
+}
+/**
+ * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Used by: copilot (agent file), codex (skill file), claude-code (command file).
+ */
+export declare function numberedWorkflow(agentName: string, options?: WorkflowOptions): string;
+/**
+ * Returns the bullet-list workflow for rules files.
+ * Used by: cursor, cline, windsurf, gemini.
+ */
+export declare function bulletWorkflow(agentName: string, options?: WorkflowOptions): string;

package/dist/integrations/workflow-steps.js

@@ -0,0 +1,44 @@
+/**
+ * Shared KGraph workflow step strings used across all AI tool adapters.
+ * Update here once instead of in each adapter file.
+ */
+const DOCTOR_STEP = `Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.`;
+const IMPACT_STEP = `Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.`;
+const REPAIR_STEP = `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.`;
+const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.`;
+function sessionStep(agentName, qualifier) {
+    const base = `Track meaningful session activity with \`kgraph session start --agent ${agentName}\`, \`kgraph session read <path> --agent ${agentName}\`, \`kgraph session write <path> --agent ${agentName}\`, and \`kgraph session end --agent ${agentName}\``;
+    return qualifier ? `${base} ${qualifier}.` : `${base}.`;
+}
+/**
+ * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Used by: copilot (agent file), codex (skill file), claude-code (command file).
+ */
+export function numberedWorkflow(agentName, options = {}) {
+    return `1. Infer the topic from the user's request.
+2. {{KGRAPH_CONTEXT_POLICY}}
+3. Use the returned files, symbols, relationships, and cognition before broad exploration.
+4. ${DOCTOR_STEP}
+5. ${sessionStep(agentName, options.sessionQualifier)}
+6. ${IMPACT_STEP}
+
+{{KGRAPH_CAPTURE_POLICY}}
+
+7. ${REPAIR_STEP}
+8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+9. ${HISTORY_STEP}`;
+}
+/**
+ * Returns the bullet-list workflow for rules files.
+ * Used by: cursor, cline, windsurf, gemini.
+ */
+export function bulletWorkflow(agentName, options = {}) {
+    return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${DOCTOR_STEP}
+- ${sessionStep(agentName, options.sessionQualifier)}
+- ${IMPACT_STEP}
+{{KGRAPH_CAPTURE_POLICY}}
+- ${REPAIR_STEP}
+- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
+- ${HISTORY_STEP}`;
+}

package/dist/session/session-store.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { KGraphError } from '../cli/errors.js';
 import { getIntegrationAdapter } from '../integrations/integration-registry.js';
 import { pathExists } from '../storage/kgraph-paths.js';
-import { KGraphError } from '../cli/errors.js';
 import { estimateTokens } from './token-estimator.js';
 const EMPTY_STATE = {
     active: {},
@@ -32,6 +32,12 @@ export async function readSessionLedger(workspace) {
 export async function recordSessionEvent(workspace, input) {
     const now = new Date().toISOString();
     const state = await readSessionState(workspace);
+    // Auto-close any open session for this agent before starting a new one so
+    // the ledger entry is never silently lost on repeated start calls.
+    if (input.type === 'start' && state.active[input.agent]) {
+        await appendLedgerEntry(workspace, summarizeAgentSession(input.agent, state, now));
+        delete state.active[input.agent];
+    }
     const active = state.active[input.agent] ?? {
         agent: input.agent,
         sessionId: `${input.agent}-${now.replace(/[:.]/g, '-')}`,
@@ -146,7 +152,11 @@ function topRepeatedReads(events) {
     for (const event of events) {
         if (!event.path)
             continue;
-        const current = byPath.get(event.path) ?? { path: event.path, count: 0, estimatedTokens: 0 };
+        const current = byPath.get(event.path) ?? {
+            path: event.path,
+            count: 0,
+            estimatedTokens: 0,
+        };
         current.count += 1;
         current.estimatedTokens += event.tokenEstimate ?? 0;
         byPath.set(event.path, current);

package/package.json

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