@kentwynn/kgraph 0.2.2 → 0.2.4

package/README.md

@@ -219,6 +219,8 @@ kgraph scan
 
 Refresh only the structural maps in `.kgraph/map/`.
 
+If the repository is a git repo, KGraph stores the HEAD commit hash with the scan result. On the next scan it computes which files changed since that commit using `git diff --name-only` and skips unchanged files without any filesystem `stat()` calls. In large repos this is measurably faster than the mtime+size fallback, which still runs automatically in non-git directories.
+
 ```bash
 kgraph context "auth token refresh"
 kgraph context "auth token refresh" --json
@@ -227,6 +229,8 @@ kgraph context "auth token refresh" --json
 Return context from existing maps and cognition without scanning or updating first.
 Markdown output includes the reason each file, symbol, cognition note, nearby symbol, or relationship was selected. Use `--json` when an agent or script needs the same explanation data programmatically.
 
+Context output includes a **Recent Git Changes** section that surfaces files with staged edits, unstaged edits, or changes in recent commits. This lets AI agents know which files are actively in flux without running a separate `git status` or `git log`.
+
 ```bash
 kgraph update
 kgraph update --dry-run
@@ -263,24 +267,24 @@ 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 |
-| --- | --- |
-| `always` | Every chat in the repository starts with `kgraph "<topic>"`, even simple or conversational requests. |
-| `smart` | Runs KGraph automatically for repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests. Skips simple conversational requests that do not depend on repo knowledge. |
-| `manual` | Exposes KGraph commands and instructions, but the agent runs KGraph only when the user explicitly asks. |
-| `off` | Disables that integration and removes generated KGraph instruction blocks/command files. |
+| Mode     | Behavior                                                                                                                                                                                                |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `always` | Every chat in the repository starts with `kgraph "<topic>"`, even simple or conversational requests.                                                                                                    |
+| `smart`  | Runs KGraph automatically for repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests. Skips simple conversational requests that do not depend on repo knowledge. |
+| `manual` | Exposes KGraph commands and instructions, but the agent runs KGraph only when the user explicitly asks.                                                                                                 |
+| `off`    | Disables that integration and removes generated KGraph instruction blocks/command files.                                                                                                                |
 
-| Tool | Files KGraph manages |
-| --- | --- |
-| Codex | `AGENTS.md`, `.agents/skills/kgraph/SKILL.md` |
+| Tool           | Files KGraph manages                                   |
+| -------------- | ------------------------------------------------------ |
+| Codex          | `AGENTS.md`, `.agents/skills/kgraph/SKILL.md`          |
 | 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` |
+| 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.
 
@@ -406,7 +410,6 @@ The release workflow builds, tests, packs, publishes the npm package on version
 
 ## Roadmap
 
-- Better Git-aware token saving and diff context.
 - Smarter cross-file symbol and call relationship inference.
 - Stronger TypeScript path alias and package export resolution.
 - Richer graph filtering for large repositories.

package/dist/cli/commands/context.js

@@ -62,6 +62,30 @@ export function renderContextMarkdown(response) {
     })));
     lines.push('', '## Stale References', '');
     lines.push(...formatList(response.staleReferences.map((ref) => `- ${ref}`)));
+    lines.push('', '## Recent Git Changes', '');
+    if (response.gitChanges && response.gitChanges.length > 0) {
+        const staged = response.gitChanges.filter((c) => c.status === 'staged');
+        const unstaged = response.gitChanges.filter((c) => c.status === 'unstaged');
+        const recent = response.gitChanges.filter((c) => c.status === 'recent-commit');
+        if (staged.length > 0) {
+            lines.push('Staged:');
+            for (const c of staged)
+                lines.push(`  ${c.path} (${c.reason})`);
+        }
+        if (unstaged.length > 0) {
+            lines.push('Unstaged:');
+            for (const c of unstaged)
+                lines.push(`  ${c.path} (${c.reason})`);
+        }
+        if (recent.length > 0) {
+            lines.push('Recent commits:');
+            for (const c of recent)
+                lines.push(`  ${c.path} (${c.reason})`);
+        }
+    }
+    else {
+        lines.push('- None');
+    }
     return lines.join('\n');
 }
 function formatGroupedRelationships(relationships, explanations) {

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);
@@ -38,6 +38,7 @@ export function registerInitCommand(program) {
             dependencies: previousMaps.dependencyMap.dependencies,
             relationships: previousMaps.relationshipMap.relationships,
             warnings: [],
+            scannedAtCommit: previousMaps.fileMap.scannedAtCommit,
         });
         await writeMaps(workspace, result);
         console.log(`Scanned ${result.files.length} files and ${result.symbols.length} symbols.`);
@@ -52,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/cli/commands/scan.d.ts

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

package/dist/cli/commands/scan.js

@@ -1,14 +1,14 @@
-import { refreshCognitionReferenceStatuses } from "../../cognition/cognition-updater.js";
-import { loadConfig } from "../../config/config.js";
-import { scanRepository } from "../../scanner/repo-scanner.js";
-import { assertWorkspace } from "../../storage/kgraph-paths.js";
-import { readMaps, writeMaps } from "../../storage/map-store.js";
-import { runCommand } from "../errors.js";
+import { refreshCognitionReferenceStatuses } from '../../cognition/cognition-updater.js';
+import { loadConfig } from '../../config/config.js';
+import { scanRepository } from '../../scanner/repo-scanner.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps, writeMaps } from '../../storage/map-store.js';
+import { runCommand } from '../errors.js';
 export function registerScanCommand(program) {
     program
-        .command("scan")
-        .description("Scan the repository into deterministic KGraph maps")
-        .option("--verbose", "Print scan warnings")
+        .command('scan')
+        .description('Scan the repository into deterministic KGraph maps')
+        .option('--verbose', 'Print scan warnings')
         .action((options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const config = await loadConfig(workspace);
@@ -18,10 +18,14 @@ export function registerScanCommand(program) {
             symbols: previousMaps.symbolMap.symbols,
             dependencies: previousMaps.dependencyMap.dependencies,
             relationships: previousMaps.relationshipMap.relationships,
-            warnings: []
+            warnings: [],
+            scannedAtCommit: previousMaps.fileMap.scannedAtCommit,
         });
         await writeMaps(workspace, result);
-        await refreshCognitionReferenceStatuses(workspace, { files: result.files, symbols: result.symbols });
+        await refreshCognitionReferenceStatuses(workspace, {
+            files: result.files,
+            symbols: result.symbols,
+        });
         console.log(`Scanned ${result.files.length} files and ${result.symbols.length} symbols.`);
         if (options.verbose && result.warnings.length > 0) {
             for (const warning of result.warnings) {

package/dist/cli/commands/workflow.js

@@ -24,6 +24,7 @@ export async function runDefaultWorkflow(query) {
             dependencies: previousMaps.dependencyMap.dependencies,
             relationships: previousMaps.relationshipMap.relationships,
             warnings: [],
+            scannedAtCommit: previousMaps.fileMap.scannedAtCommit,
         });
         await writeMaps(workspace, scan);
         await refreshCognitionReferenceStatuses(workspace, {

package/dist/context/context-query.js

@@ -1,3 +1,4 @@
+import { getRecentlyCommittedFiles, getWorkingTreeChangesDetailed, isGitRepo, } from '../scanner/git-utils.js';
 import { readCognitionNotes, readDomainRecords, } from '../storage/cognition-store.js';
 import { rankByFields } from './ranking.js';
 export async function queryContext(workspace, config, maps, query) {
@@ -109,6 +110,41 @@ export async function queryContext(workspace, config, maps, query) {
             ...dependenciesForImportedSymbol(symbol, maps.dependencyMap.dependencies),
         ],
     }));
+    // Collect git changes: working-tree and recently committed files known to KGraph
+    const knownFilePaths = new Set(maps.fileMap.files.map((f) => f.path));
+    const gitChanges = [];
+    if (await isGitRepo(workspace.rootPath)) {
+        const workingTreeChanges = await getWorkingTreeChangesDetailed(workspace.rootPath);
+        for (const change of workingTreeChanges) {
+            if (!knownFilePaths.has(change.path))
+                continue;
+            const status = change.staged && !change.unstaged
+                ? 'staged'
+                : change.unstaged && !change.staged
+                    ? 'unstaged'
+                    : 'staged'; // both staged and unstaged → report as staged
+            gitChanges.push({
+                path: change.path,
+                status,
+                reason: change.staged && change.unstaged
+                    ? 'partially staged'
+                    : status === 'staged'
+                        ? 'staged change'
+                        : 'unstaged change',
+            });
+        }
+        const committedPaths = new Set(gitChanges.map((c) => c.path));
+        const recentCommitted = await getRecentlyCommittedFiles(workspace.rootPath);
+        for (const filePath of recentCommitted) {
+            if (!knownFilePaths.has(filePath) || committedPaths.has(filePath))
+                continue;
+            gitChanges.push({
+                path: filePath,
+                status: 'recent-commit',
+                reason: 'changed in recent commits',
+            });
+        }
+    }
     return {
         query,
         matchedDomains,
@@ -119,6 +155,7 @@ export async function queryContext(workspace, config, maps, query) {
         relationshipExplanations: relationshipExplanations.slice(0, max),
         nearbySymbols,
         nearbySymbolExplanations,
+        gitChanges,
         staleReferences,
         warnings: [],
     };
@@ -130,7 +167,8 @@ function explainRelationships(relationships, context) {
     ]));
     return relationships.map((relationship) => {
         const reasons = new Set();
-        for (const reason of rankedReasons.get(relationshipKey(relationship)) ?? []) {
+        for (const reason of rankedReasons.get(relationshipKey(relationship)) ??
+            []) {
             reasons.add(reason);
         }
         for (const file of context.relevantFiles) {

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/scanner/git-utils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Returns true if the given directory is inside a git repository.
+ * Uses a fast filesystem check rather than spawning a process.
+ */
+export declare function isGitRepo(rootPath: string): Promise<boolean>;
+/**
+ * Returns the current HEAD commit hash, or null if unavailable.
+ */
+export declare function getCurrentCommit(rootPath: string): Promise<string | null>;
+/**
+ * Returns paths of files changed between the given ref and HEAD.
+ * Returns an empty array if git is unavailable or the ref is unknown.
+ */
+export declare function getChangedFilesSince(rootPath: string, ref: string): Promise<string[]>;
+/**
+ * Returns paths of files with uncommitted changes (staged or unstaged)
+ * relative to HEAD. Returns an empty array if git is unavailable.
+ */
+export declare function getWorkingTreeChanges(rootPath: string): Promise<string[]>;
+export type WorkingTreeChange = {
+    path: string;
+    staged: boolean;
+    unstaged: boolean;
+};
+/**
+ * Returns working-tree changes with staged/unstaged flags.
+ * Returns an empty array if git is unavailable.
+ */
+export declare function getWorkingTreeChangesDetailed(rootPath: string): Promise<WorkingTreeChange[]>;
+/**
+ * Returns up to `limit` files changed in the most recent commits
+ * (excluding uncommitted changes). Returns an empty array if git is unavailable.
+ */
+export declare function getRecentlyCommittedFiles(rootPath: string, limit?: number): Promise<string[]>;

package/dist/scanner/git-utils.js

@@ -0,0 +1,130 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Returns true if the given directory is inside a git repository.
+ * Uses a fast filesystem check rather than spawning a process.
+ */
+export async function isGitRepo(rootPath) {
+    try {
+        await access(path.join(rootPath, '.git'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the current HEAD commit hash, or null if unavailable.
+ */
+export async function getCurrentCommit(rootPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd: rootPath,
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns paths of files changed between the given ref and HEAD.
+ * Returns an empty array if git is unavailable or the ref is unknown.
+ */
+export async function getChangedFilesSince(rootPath, ref) {
+    try {
+        const { stdout } = await execFileAsync('git', ['diff', '--name-only', ref, 'HEAD'], { cwd: rootPath });
+        return stdout
+            .trim()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Returns paths of files with uncommitted changes (staged or unstaged)
+ * relative to HEAD. Returns an empty array if git is unavailable.
+ */
+export async function getWorkingTreeChanges(rootPath) {
+    try {
+        const [stagedResult, unstagedResult] = await Promise.all([
+            execFileAsync('git', ['diff', '--name-only', '--cached'], {
+                cwd: rootPath,
+            }),
+            execFileAsync('git', ['diff', '--name-only'], { cwd: rootPath }),
+        ]);
+        const staged = stagedResult.stdout
+            .trim()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+        const unstaged = unstagedResult.stdout
+            .trim()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean);
+        // Deduplicate: a file can appear in both if partially staged
+        return [...new Set([...staged, ...unstaged])];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Returns working-tree changes with staged/unstaged flags.
+ * Returns an empty array if git is unavailable.
+ */
+export async function getWorkingTreeChangesDetailed(rootPath) {
+    try {
+        const [stagedResult, unstagedResult] = await Promise.all([
+            execFileAsync('git', ['diff', '--name-only', '--cached'], {
+                cwd: rootPath,
+            }),
+            execFileAsync('git', ['diff', '--name-only'], { cwd: rootPath }),
+        ]);
+        const staged = new Set(stagedResult.stdout
+            .trim()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean));
+        const unstaged = new Set(unstagedResult.stdout
+            .trim()
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean));
+        const all = new Set([...staged, ...unstaged]);
+        return [...all].map((filePath) => ({
+            path: filePath,
+            staged: staged.has(filePath),
+            unstaged: unstaged.has(filePath),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Returns up to `limit` files changed in the most recent commits
+ * (excluding uncommitted changes). Returns an empty array if git is unavailable.
+ */
+export async function getRecentlyCommittedFiles(rootPath, limit = 5) {
+    try {
+        // git log --name-only gives files touched in each of the last N commits
+        const { stdout } = await execFileAsync('git', ['log', '--name-only', '--pretty=format:', `-n`, String(limit), 'HEAD'], { cwd: rootPath });
+        return [
+            ...new Set(stdout
+                .split('\n')
+                .map((line) => line.trim())
+                .filter(Boolean)),
+        ];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/scanner/repo-scanner.d.ts

@@ -1,3 +1,5 @@
 import type { KGraphConfig } from '../types/config.js';
 import type { ScanResult } from '../types/maps.js';
-export declare function scanRepository(rootPath: string, config: KGraphConfig, previous?: ScanResult): Promise<ScanResult>;
+export declare function scanRepository(rootPath: string, config: KGraphConfig, previous?: ScanResult & {
+    scannedAtCommit?: string;
+}): Promise<ScanResult>;

package/dist/scanner/repo-scanner.js

@@ -6,6 +6,7 @@ import { estimateTokens } from '../session/token-estimator.js';
 import { extractCSymbols } from './c-symbol-extractor.js';
 import { extractCSharpSymbols } from './csharp-symbol-extractor.js';
 import { buildFastGlobIgnore, detectLanguage, isPreciseLanguage, readGitignorePatterns, shouldExclude, } from './file-classifier.js';
+import { getChangedFilesSince, isGitRepo } from './git-utils.js';
 import { extractGoSymbols } from './go-symbol-extractor.js';
 import { extractJvmSymbols } from './jvm-symbol-extractor.js';
 import { extractPythonSymbols } from './python-symbol-extractor.js';
@@ -71,6 +72,16 @@ export async function scanRepository(rootPath, config, previous) {
             }
         }
     }
+    // Build git-changed-file set for fast incremental skip bypassing stat() calls.
+    // Only used when the previous scan stored a commit hash and we are in a git repo.
+    let gitChangedFiles = null;
+    if (previous?.scannedAtCommit && (await isGitRepo(rootPath))) {
+        const changed = await getChangedFilesSince(rootPath, previous.scannedAtCommit);
+        // Also include working-tree dirty files so uncommitted edits are always re-scanned.
+        // getChangedFilesSince returns committed changes; we complement with a stat check
+        // fallback below for uncommitted edits to keep correctness.
+        gitChangedFiles = new Set(changed);
+    }
     const files = [];
     const symbols = [];
     const dependencies = [];
@@ -83,9 +94,34 @@ export async function scanRepository(rootPath, config, previous) {
         }
         const absolutePath = path.join(rootPath, repoPath);
         try {
-            const info = await stat(absolutePath);
-            // Incremental skip: if mtime and size match previous, carry forward
             const prevFile = prevFileByPath.get(repoPath);
+            // Fast git-based skip: if we have a git-changed set and this file is NOT in it,
+            // carry forward directly without touching the filesystem.
+            if (prevFile &&
+                gitChangedFiles !== null &&
+                !gitChangedFiles.has(repoPath)) {
+                files.push(prevFile);
+                const prevSyms = prevSymbolsByFile.get(repoPath);
+                if (prevSyms)
+                    symbols.push(...prevSyms);
+                const prevDeps = prevDepsByFile.get(repoPath);
+                if (prevDeps)
+                    dependencies.push(...prevDeps);
+                const prevRels = prevRelsBySource.get(repoPath);
+                if (prevRels)
+                    relationships.push(...prevRels);
+                if (prevSyms) {
+                    for (const sym of prevSyms) {
+                        const symRels = prevRelsBySource.get(sym.id);
+                        if (symRels)
+                            relationships.push(...symRels);
+                    }
+                }
+                skippedFiles++;
+                continue;
+            }
+            const info = await stat(absolutePath);
+            // Fallback incremental skip: if mtime and size match previous, carry forward
             if (prevFile &&
                 prevFile.sizeBytes === info.size &&
                 prevFile.modifiedAt === info.mtime.toISOString()) {

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

@@ -1,5 +1,5 @@
-import type { KGraphWorkspace } from "../types/config.js";
-import type { DependencyMap, FileMap, RelationshipMap, ScanResult, SymbolMap } from "../types/maps.js";
+import type { KGraphWorkspace } from '../types/config.js';
+import type { DependencyMap, FileMap, RelationshipMap, ScanResult, SymbolMap } from '../types/maps.js';
 export declare function mapPaths(workspace: KGraphWorkspace): Record<string, string>;
 export declare function readMaps(workspace: KGraphWorkspace): Promise<{
     fileMap: FileMap;

package/dist/storage/map-store.js

@@ -1,13 +1,14 @@
-import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { pathExists } from "./kgraph-paths.js";
-import { KGraphError } from "../cli/errors.js";
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { KGraphError } from '../cli/errors.js';
+import { getCurrentCommit } from '../scanner/git-utils.js';
+import { pathExists } from './kgraph-paths.js';
 async function readJson(filePath, fallback) {
     if (!(await pathExists(filePath))) {
         return fallback;
     }
     try {
-        return JSON.parse(await readFile(filePath, "utf8"));
+        return JSON.parse(await readFile(filePath, 'utf8'));
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -15,40 +16,57 @@ async function readJson(filePath, fallback) {
     }
 }
 async function writeJson(filePath, value) {
-    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 export function mapPaths(workspace) {
     return {
-        files: path.join(workspace.mapPath, "files.json"),
-        symbols: path.join(workspace.mapPath, "symbols.json"),
-        dependencies: path.join(workspace.mapPath, "dependencies.json"),
-        relationships: path.join(workspace.mapPath, "relationships.json")
+        files: path.join(workspace.mapPath, 'files.json'),
+        symbols: path.join(workspace.mapPath, 'symbols.json'),
+        dependencies: path.join(workspace.mapPath, 'dependencies.json'),
+        relationships: path.join(workspace.mapPath, 'relationships.json'),
     };
 }
 export async function readMaps(workspace) {
     const paths = mapPaths(workspace);
     return {
-        fileMap: await readJson(paths.files, { generatedAt: "", files: [] }),
-        symbolMap: await readJson(paths.symbols, { generatedAt: "", symbols: [] }),
-        dependencyMap: await readJson(paths.dependencies, { generatedAt: "", dependencies: [] }),
+        fileMap: await readJson(paths.files, {
+            generatedAt: '',
+            files: [],
+        }),
+        symbolMap: await readJson(paths.symbols, {
+            generatedAt: '',
+            symbols: [],
+        }),
+        dependencyMap: await readJson(paths.dependencies, {
+            generatedAt: '',
+            dependencies: [],
+        }),
         relationshipMap: await readJson(paths.relationships, {
-            generatedAt: "",
-            relationships: []
-        })
+            generatedAt: '',
+            relationships: [],
+        }),
     };
 }
 export async function writeMaps(workspace, result) {
     const generatedAt = new Date().toISOString();
+    const scannedAtCommit = (await getCurrentCommit(workspace.rootPath)) ?? undefined;
     const paths = mapPaths(workspace);
-    await writeJson(paths.files, { generatedAt, files: result.files });
-    await writeJson(paths.symbols, { generatedAt, symbols: result.symbols });
+    await writeJson(paths.files, {
+        generatedAt,
+        scannedAtCommit,
+        files: result.files,
+    });
+    await writeJson(paths.symbols, {
+        generatedAt,
+        symbols: result.symbols,
+    });
     await writeJson(paths.dependencies, {
         generatedAt,
-        dependencies: result.dependencies
+        dependencies: result.dependencies,
     });
     await writeJson(paths.relationships, {
         generatedAt,
-        relationships: result.relationships
+        relationships: result.relationships,
     });
 }
 export async function mapsExist(workspace) {

package/dist/types/cognition.d.ts

@@ -31,6 +31,12 @@ export interface RankedItem<T> {
     score: number;
     reasons: string[];
 }
+export type GitChangeStatus = 'staged' | 'unstaged' | 'recent-commit';
+export interface GitContextChange {
+    path: string;
+    status: GitChangeStatus;
+    reason: string;
+}
 export interface ContextResponse {
     query: string;
     matchedDomains: RankedItem<DomainRecord>[];
@@ -47,6 +53,7 @@ export interface ContextResponse {
         symbol: CodeSymbol;
         reasons: string[];
     }>;
+    gitChanges?: GitContextChange[];
     staleReferences: string[];
     warnings: string[];
 }

package/dist/types/maps.d.ts

@@ -40,6 +40,7 @@ export interface Relationship {
 }
 export interface FileMap {
     generatedAt: string;
+    scannedAtCommit?: string;
     files: RepositoryFile[];
 }
 export interface SymbolMap {
@@ -61,4 +62,5 @@ export interface ScanResult {
     relationships: Relationship[];
     warnings: string[];
     skippedFiles?: number;
+    scannedAtCommit?: string;
 }

package/package.json

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