@kentwynn/kgraph 0.2.1 → 0.2.3

package/README.md

@@ -74,6 +74,8 @@ That shows matched files/symbols, files importing the target, known callers/call
 
 ## Install
 
+The official npm package is `@kentwynn/kgraph`; the official repository is `github.com/kentwynn/KGraph`.
+
 Use the published CLI:
 
 ```bash
@@ -90,6 +92,8 @@ npx @kentwynn/kgraph@latest "auth token refresh"
 
 KGraph requires Node.js 20 or newer.
 
+KGraph's core functionality is free and local-first. It does not require accounts, telemetry, cloud services, API keys, or source-code upload.
+
 ## Quick Start
 
 From the root of a repository:
@@ -215,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
@@ -223,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
@@ -261,22 +269,22 @@ 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.
 
-| 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.
 
@@ -302,7 +310,7 @@ All runtime data lives under `.kgraph/`:
 └── context/
 ```
 
-The files are local, inspectable, and human-readable. There is no database, telemetry, cloud service, account, API key, embedding service, or model provider.
+The files are local, inspectable, and human-readable. Core KGraph functionality is free. There is no database, telemetry, cloud service, account, API key, embedding service, model provider, or source-code upload.
 
 ## Language Support
 
@@ -371,14 +379,25 @@ npm run release:pack
 
 ## Release
 
-Releases are tag-driven:
+Releases are PR-first because `main` is protected. Use the Makefile helper to bump the version on a release branch, push it, and open a pull request when the GitHub CLI is available:
+
+```bash
+make release
+```
+
+Use `RELEASE=minor` or `RELEASE=major` when needed:
+
+```bash
+make release RELEASE=minor
+```
+
+After the PR is merged, tag the merged commit from an up-to-date `main`:
 
 ```bash
-npm version patch
-git push origin main --follow-tags
+make release-tag VERSION=v0.2.2
 ```
 
-The release workflow builds, tests, packs, publishes the npm package on version tags, creates a GitHub Release, and uploads the tarball artifact.
+The release workflow builds, tests, packs, publishes the npm package on version tags, creates a GitHub Release, and uploads the tarball artifact. Do not push directly to `main` for releases.
 
 ## Design Principles
 
@@ -394,5 +413,5 @@ The release workflow builds, tests, packs, publishes the npm package on version
 - Smarter cross-file symbol and call relationship inference.
 - Stronger TypeScript path alias and package export resolution.
 - Richer graph filtering for large repositories.
-- Optional MCP server for editor tool-call access.
-- Team workflows for shared committed cognition.
+- Optional MCP and editor integration.
+- Team-friendly shared cognition workflows that stay local-first.

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

@@ -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.`);

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