@kentwynn/kgraph 0.1.15 → 0.1.17

package/README.md

@@ -1,112 +1,71 @@
 # KGraph
 
-> **Persistent repository intelligence for AI coding tools.**
-> Stop paying the context tax on every session. KGraph gives your AI assistant a memory.
+Persistent repository intelligence for AI coding tools.
 
----
+KGraph gives Codex, GitHub Copilot, Cursor, and Claude Code a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable notes from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
 
-## The Problem
+## The Workflow
 
-Every AI coding session starts with the same expensive ritual:
+Use KGraph in two steps:
 
-```
-"Let me read your package.json..."
-"Let me trace the imports in auth.ts..."
-"Let me find where sessions are created..."
-"Let me understand the database layer..."
-```
-
-On a medium-sized codebase, this exploration burns **3,000–8,000 tokens** before the AI writes a single line of code. Multiply that across 10 sessions per day and you're spending the majority of your context budget re-learning things you already know.
-
-Worse: AI tools forget. The debugging insight from Tuesday, the architecture decision from last sprint, the "don't touch this or it breaks payments" gotcha — gone after every session.
-
----
-
-## The Solution
-
-KGraph builds a local knowledge layer that grows with your project. It maps your codebase once, captures reasoning from your AI sessions, and serves compact, targeted context on demand.
+```bash
+# Required once per repository
+kgraph init --integrations codex,copilot,cursor,claude-code
 
+# Normal daily command
+kgraph "auth token refresh"
 ```
-Without KGraph                     With KGraph
-─────────────────────────────────  ──────────────────────────────────
-Session start: ~5,000 tokens       Session start: ~300 tokens
-exploring files and structure      kgraph context "auth token refresh"
 
-Re-learns same architecture        Recalls prior decisions instantly
-every single session               from cognition store
+That second command runs the full practical workflow:
 
-Context limit hit mid-task         Full context budget for actual work
-
-Debugging insight lost forever     Captured in .kgraph/inbox/
-                                   available in every future session
-```
+1. Refreshes the repository scan.
+2. Updates file, symbol, import, and relationship maps.
+3. Processes any Markdown notes waiting in `.kgraph/inbox/`.
+4. Returns compact context for the topic you asked about.
 
----
+You can also run just:
 
-## Token Savings — What This Looks Like in Practice
+```bash
+kgraph
+```
 
-A typical `kgraph context` response for a focused topic:
+That refreshes maps and cognition without printing topic-specific context.
 
-```
-topic: auth token refresh
+The smaller commands, such as `kgraph scan`, `kgraph update`, and `kgraph context`, still exist. They are useful when you want one specific step, but they are not the main workflow.
 
-files:
-  src/lib/auth.ts           (createSession, validateToken, refreshToken)
-  app/api/auth/route.ts     (POST handler → createSession)
-  middleware.ts             (reads session cookie, calls validateToken)
+## Why It Exists
 
-key relationships:
-  POST /api/auth → createSession → writes JWT to cookie
-  middleware → validateToken → redirects on expiry
+Most AI coding sessions start like this:
 
-cognition:
-  refreshToken has a race condition under concurrent requests — see issue #47
-  JWT secret must come from env, never hardcoded — broke staging in March
-  token TTL is 15 min by design, not a bug
+```text
+Let me inspect package.json.
+Let me search for auth routes.
+Let me trace imports.
+Let me understand where sessions are stored.
 ```
 
-**~280 tokens.** The equivalent file-by-file exploration: **4,200+ tokens.**  
-That's a **15x reduction** in context cost for navigation alone.
+That exploration is useful once. It is wasteful the tenth time.
 
-The gap widens every week as cognition accumulates — past decisions, debugging discoveries, and architectural gotchas that would otherwise cost the AI thousands of tokens to re-derive.
+KGraph stores the reusable parts locally:
 
----
+- What files exist and what language they use.
+- What symbols each source file defines.
+- Which files import each other.
+- Which notes, decisions, debugging findings, and gotchas were captured from prior sessions.
+- Which cognition references are current, mixed, stale, or unresolved after code moves.
 
-## How It Works
+Then an AI assistant can ask for focused context before broad exploration:
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Your Codebase                        │
-└──────────────────────────────┬──────────────────────────────┘
-                               │  kgraph scan
-                               ▼
-┌─────────────────────────────────────────────────────────────┐
-│  .kgraph/                                                   │
-│  ├── maps/          file graph, symbol index, imports       │
-│  ├── cognition.md   decisions, gotchas, debugging history   │
-│  └── config.yaml    include/exclude rules                   │
-└──────────────────────────────┬──────────────────────────────┘
-                               │  kgraph context "topic"
-                               ▼
-┌─────────────────────────────────────────────────────────────┐
-│  AI Tool  (Copilot / Codex / Cursor / Claude Code)          │
-│  Reads compact context → navigates directly → works faster  │
-└─────────────────────────────────────────────────────────────┘
-                               │  session ends
-                               ▼
-┌─────────────────────────────────────────────────────────────┐
-│  .kgraph/inbox/     AI drops a note: what it learned        │
-│                     kgraph update → distilled into          │
-│                     cognition.md for the next session       │
-└─────────────────────────────────────────────────────────────┘
+```bash
+kgraph "blog admin token usage"
 ```
 
-This creates a **compounding feedback loop**: the more you use KGraph, the richer the cognition store, the less exploration the AI needs to do.
-
----
+Instead of reading the whole repo, it gets a compact starting point: relevant files, symbols, relationships, domains, prior notes, and stale references to watch.
 
 ## Install
 
+Use the published CLI:
+
 ```bash
 npm install -g @kentwynn/kgraph@latest
 kgraph --version
@@ -116,107 +75,171 @@ Or run without installing:
 
 ```bash
 npx @kentwynn/kgraph@latest init
+npx @kentwynn/kgraph@latest "auth token refresh"
 ```
 
----
+KGraph requires Node.js 20 or newer.
 
 ## Quick Start
 
+From the root of a repository:
+
+```bash
+# 1. Create the local KGraph workspace
+kgraph init
+
+# 2. Optional: connect AI tools so they know the KGraph workflow
+kgraph integrate add codex copilot cursor claude-code
+
+# 3. Run the normal workflow for a topic
+kgraph "auth token refresh"
+
+# 4. Check health if something feels off
+kgraph doctor
+```
+
+After useful AI work, assistants can save durable notes into `.kgraph/inbox/`. The next `kgraph` run processes those notes automatically. You can also process them directly with `kgraph update`.
+
+## Main Commands
+
+```bash
+kgraph init
+```
+
+Required once per repo. Creates `.kgraph/` and the local config.
+
 ```bash
-# 1. Initialize and connect your AI tools
 kgraph init --integrations codex,copilot,cursor,claude-code
+```
 
-# 2. Scan the codebase
-kgraph scan
+Initializes KGraph and writes local instruction files for supported AI tools.
 
-# 3. Ask for context before exploring (your AI does this automatically)
-kgraph context "auth token refresh"
+```bash
+kgraph "some topic"
+```
 
-# 4. After an AI session, save what was learned
-kgraph update
+The normal command. Scans the repo, updates cognition, and returns focused context for the topic.
+
+```bash
+kgraph
 ```
 
-That's the entire loop. From session 2 onward, your AI tool loads existing intelligence before touching a single file.
+Refreshes maps and cognition without returning topic-specific context.
 
----
+```bash
+kgraph doctor
+```
 
-## AI Tool Integrations
+Checks whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files.
+
+## Optional Step Commands
 
-`kgraph integrate` writes instruction files and command/skill packs directly into your repo so each tool knows how to use the knowledge layer — no manual setup.
+These are useful for scripting, debugging, or when you want a single operation.
 
 ```bash
-kgraph integrate add codex copilot cursor claude-code
-kgraph integrate list
+kgraph scan
+```
+
+Refresh only the structural maps in `.kgraph/map/`.
+
+```bash
+kgraph context "auth token refresh"
+kgraph context "auth token refresh" --json
 ```
 
-| Tool           | Always-on instruction             | Skills / commands                                                                               |
-| -------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- |
-| GitHub Copilot | `.github/copilot-instructions.md` | `/kgraph-scan` · `/kgraph-update` · `/kgraph-visualize` · `/kgraph-history` · `/kgraph-capture` |
-| Codex          | `AGENTS.md`                       | `.agents/skills/kgraph/SKILL.md` (VS Code Agent Skills standard)                                |
-| Cursor         | `.cursor/rules/kgraph.mdc`        | Built into the rule                                                                             |
-| Claude Code    | `CLAUDE.md`                       | `/kgraph` · `/kgraph-scan` · `/kgraph-update` · `/kgraph-visualize` · `/kgraph-history`         |
+Return context from existing maps and cognition without scanning or updating first.
 
-Each integration installs a `/kgraph` skill or command that handles the full workflow automatically: load context → work → capture findings → update cognition. `/kgraph-scan`, `/kgraph-update`, and `/kgraph-visualize` are available for manual maintenance.
+```bash
+kgraph update
+kgraph update --dry-run
+```
 
-Existing user content in `AGENTS.md`, `CLAUDE.md`, etc. is preserved — KGraph manages only its own clearly-marked blocks.
+Process Markdown notes from `.kgraph/inbox/` into durable cognition records.
 
----
+```bash
+kgraph visualize
+kgraph visualize --port 3000
+kgraph visualize --no-open
+```
 
-## CLI Reference
+Open the local interactive dependency graph at `http://localhost:4242`.
 
 ```bash
-kgraph init                                     # initialize .kgraph/ workspace
-kgraph init --integrations codex,copilot        # init + configure integrations
+kgraph history
+kgraph history --last 10
+kgraph history --json
+```
 
-kgraph scan                                     # scan codebase, update maps
-kgraph context "auth token refresh"             # get compact context for a topic
-kgraph context "auth token refresh" --json      # machine-readable output
-kgraph update                                   # process inbox notes into cognition
+Show processed cognition sessions.
 
-kgraph integrate list                           # show integration status
-kgraph integrate add codex copilot cursor       # add integrations
-kgraph integrate remove cursor                  # remove an integration
+## AI Tool Integrations
 
-kgraph visualize                                # interactive graph at http://localhost:4242
-kgraph visualize --port 3000                    # custom port
-kgraph visualize --no-open                      # print URL, don't open browser
+KGraph integrations are local files. They do not start background agents, call AI providers, or send data anywhere.
 
-kgraph history                                  # timeline of processed cognition sessions
-kgraph history --last 10                        # show last 10 entries
-kgraph history --json                           # machine-readable output
+```bash
+kgraph integrate add codex copilot cursor claude-code
+kgraph integrate list
+kgraph integrate remove cursor
 ```
 
----
+| 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/*` |
+
+KGraph preserves existing user-authored content and updates only its marked instruction blocks or generated command files.
+
+## What Gets Stored
+
+All runtime data lives under `.kgraph/`:
+
+```text
+.kgraph/
+├── config.yaml
+├── map/
+│   ├── files.json
+│   ├── symbols.json
+│   ├── dependencies.json
+│   └── relationships.json
+├── inbox/
+├── cognition/
+├── domains/
+├── interactions/processed/
+└── context/
+```
 
-## What KGraph Tracks
+The files are local, inspectable, and human-readable. There is no database, telemetry, cloud service, account, API key, embedding service, or model provider.
 
-| Category          | Examples                                                               |
-| ----------------- | ---------------------------------------------------------------------- |
-| **File map**      | every source file, language, size                                      |
-| **Symbol index**  | functions, classes, methods, exports per file                          |
-| **Import graph**  | which files import which, dependency chains                            |
-| **Relationships** | call sites, re-exports, shared types                                   |
-| **Cognition**     | past decisions, architectural constraints, debugging insights, gotchas |
+## Language Support
 
-**Deep scan** (symbols, functions, classes, methods, imports): TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C, C++, C#
+KGraph deeply scans:
 
-**Generic scan** (file path, language, size — contributes to context): Ruby, PHP, Swift, Shell, HTML, CSS, SQL, YAML, TOML, and 20+ more — detected by file extension, no configuration needed.
+- TypeScript and JavaScript
+- Python
+- Go
+- Rust
+- Java and Kotlin
+- C and C++
+- C#
 
----
+Other common file types still appear in the file map with generic metadata, so context queries can still point to docs, config, SQL, CSS, HTML, YAML, and similar files.
 
-## Local-First, Zero Dependencies
+## Visualization
 
-KGraph requires nothing beyond Node.js ≥ 20:
+```bash
+kgraph visualize
+```
 
-- No accounts or API keys
-- No embeddings or vector databases
-- No cloud services or telemetry
-- No background daemons
-- No model provider
+The graph shows files, symbols, imports, cognition notes, and relationship edges. Cognition notes are colored by reference health:
 
-All data lives in `.kgraph/` as human-readable JSON, YAML, and Markdown. Commit it, diff it, inspect it anytime.
+- current
+- mixed
+- stale
+- unresolved
 
----
+Use it when you want to inspect what KGraph currently knows, find stale notes after refactors, or export a graph image for a report.
 
 ## Development
 
@@ -226,60 +249,54 @@ npm run build
 npm test
 ```
 
-Test a command without installing:
+Run the local TypeScript CLI without installing globally:
 
 ```bash
-npm run kgraph -- init --integrations codex,cursor
-npm run kgraph -- context "auth token refresh"
+npm run kgraph -- init
+npm run kgraph -- "auth token refresh"
+npm run kgraph -- doctor
 ```
 
-Install the local build globally to test the `kgraph` binary end-to-end:
+Test the built package as a global local install:
 
 ```bash
+npm run build
 npm install -g .
 kgraph --version
-kgraph init --integrations codex,copilot
+kgraph doctor
+kgraph "auth token refresh"
 ```
 
----
-
-## Release
-
-Releases are tag-driven. Bump the version, push the commit and tag:
+Package checks:
 
 ```bash
-npm version patch
-git push origin main --follow-tags
+npm run pack:dry
+npm run release:pack
 ```
 
-CI verifies the tag matches `package.json`, checks the version is unpublished, publishes to npm, creates a GitHub Release, and attaches the tarball.
-
----
+## Release
 
-## Visualization
+Releases are tag-driven:
 
 ```bash
-kgraph visualize
+npm version patch
+git push origin main --follow-tags
 ```
 
-Starts a local server at `http://localhost:4242` and opens an interactive dependency graph in your browser. No install required — two CDN scripts (Cytoscape.js + dagre layout) are loaded at view time.
-
-**What you see:**
+The release workflow builds, tests, packs, publishes the npm package on version tags, creates a GitHub Release, and uploads the tarball artifact.
 
-- File nodes colored by language (TypeScript, JavaScript, Markdown, YAML, …)
-- Cognition notes as diamonds, colored by health (green = current, amber = mixed, red = stale)
-- Import edges showing real dependency flow
-- Dashed blue edges linking cognition notes to the files they describe
-- Click any node for a metadata panel (path, size, domain, related symbols)
-- Toggle cognition overlay on/off
-- Switch layout: Hierarchical (default), Force-directed, Grid, Concentric
-- **Export PNG** — 2× resolution, dark background, ready for reports or slides
+## Design Principles
 
----
+- Local-first: the repo intelligence stays in your repo.
+- Explicit: no daemon and no hidden background process.
+- Inspectable: generated knowledge is JSON, YAML, and Markdown.
+- Deterministic first: useful ranking without requiring embeddings or a model.
+- Assistant-friendly: one normal command, with lower-level commands available when needed.
 
 ## Roadmap
 
-- Git-aware history and rename tracking
-- richer language scanners (deeper AST, cross-file type resolution)
-- MCP server for editor tool-call access
-- team-shared cognition via committed `.kgraph/`
+- 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.

package/dist/cli/commands/context.d.ts

@@ -1,2 +1,4 @@
 import type { Command } from "commander";
+import type { ContextResponse } from "../../types/cognition.js";
 export declare function registerContextCommand(program: Command): void;
+export declare function renderContextMarkdown(response: ContextResponse): string;

package/dist/cli/commands/context.js

@@ -19,10 +19,10 @@ export function registerContextCommand(program) {
         const config = await loadConfig(workspace);
         const maps = await readMaps(workspace);
         const response = await queryContext(workspace, config, maps, query);
-        console.log(options.json ? JSON.stringify(response, null, 2) : renderMarkdown(response));
+        console.log(options.json ? JSON.stringify(response, null, 2) : renderContextMarkdown(response));
     }));
 }
-function renderMarkdown(response) {
+export function renderContextMarkdown(response) {
     const lines = [`# KGraph Context`, ``, `Query: ${response.query}`, ``];
     lines.push("## Matched Domains", "");
     lines.push(...formatList(response.matchedDomains.map((item) => `- ${item.item.name} (${item.reasons.join(", ")})`)));

package/dist/cli/commands/doctor.d.ts

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

package/dist/cli/commands/doctor.js

@@ -0,0 +1,100 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig } from '../../config/config.js';
+import { listIntegrations } from '../../integrations/integration-store.js';
+import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
+import { mapPaths, mapsExist, readMaps } from '../../storage/map-store.js';
+import { runCommand } from '../errors.js';
+export function registerDoctorCommand(program) {
+    program
+        .command('doctor')
+        .description('Check KGraph workspace health and next actions')
+        .action(() => runCommand(async () => {
+        const rootPath = process.cwd();
+        const workspace = resolveWorkspace(rootPath);
+        const checks = [];
+        const initialized = await pathExists(workspace.kgraphPath);
+        checks.push({
+            label: 'workspace',
+            ok: initialized,
+            detail: initialized ? '.kgraph exists' : 'run `kgraph init` first',
+        });
+        if (!initialized) {
+            printChecks(checks);
+            process.exitCode = 1;
+            return;
+        }
+        await assertWorkspace(rootPath);
+        const config = await loadConfig(workspace);
+        checks.push({
+            label: 'config',
+            ok: true,
+            detail: `${config.include.length} include pattern(s), ${config.exclude.length} exclude pattern(s)`,
+        });
+        const mapStatus = await mapsExist(workspace);
+        checks.push({
+            label: 'maps',
+            ok: mapStatus,
+            detail: mapStatus ? 'structural maps are present' : 'run `kgraph scan` or just `kgraph`',
+        });
+        if (mapStatus) {
+            const maps = await readMaps(workspace);
+            checks.push({
+                label: 'scan result',
+                ok: true,
+                detail: `${maps.fileMap.files.length} files, ${maps.symbolMap.symbols.length} symbols, ${maps.dependencyMap.dependencies.length} dependencies`,
+            });
+        }
+        else {
+            const paths = mapPaths(workspace);
+            const missing = [];
+            for (const [name, filePath] of Object.entries(paths)) {
+                if (!(await pathExists(filePath)))
+                    missing.push(name);
+            }
+            checks.push({
+                label: 'missing maps',
+                ok: false,
+                detail: missing.join(', '),
+            });
+        }
+        const inboxCount = await countMarkdownFiles(workspace.inboxPath);
+        checks.push({
+            label: 'inbox',
+            ok: true,
+            detail: inboxCount === 0
+                ? 'no pending cognition notes'
+                : `${inboxCount} note(s) waiting for \`kgraph update\``,
+        });
+        const integrations = await listIntegrations(workspace);
+        checks.push({
+            label: 'integrations',
+            ok: integrations.every((integration) => integration.targetExists),
+            detail: integrations.length === 0
+                ? 'none configured'
+                : integrations
+                    .map((integration) => integration.targetExists
+                    ? `${integration.name}: ${integration.targetPath}`
+                    : `${integration.name}: missing ${integration.targetPath}`)
+                    .join('; '),
+        });
+        printChecks(checks);
+        if (checks.some((check) => !check.ok)) {
+            process.exitCode = 1;
+        }
+    }));
+}
+async function countMarkdownFiles(dirPath) {
+    if (!(await pathExists(dirPath))) {
+        return 0;
+    }
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile() && path.extname(entry.name) === '.md').length;
+}
+function printChecks(checks) {
+    console.log('KGraph Doctor');
+    console.log('');
+    for (const check of checks) {
+        console.log(`${check.ok ? 'OK' : 'FAIL'}  ${check.label}: ${check.detail}`);
+    }
+}

package/dist/cli/commands/workflow.d.ts

@@ -0,0 +1 @@
+export declare function runDefaultWorkflow(query?: string): Promise<void>;

package/dist/cli/commands/workflow.js

@@ -0,0 +1,42 @@
+import { updateCognition } from '../../cognition/cognition-updater.js';
+import { refreshCognitionReferenceStatuses } from '../../cognition/cognition-updater.js';
+import { loadConfig } from '../../config/config.js';
+import { queryContext } from '../../context/context-query.js';
+import { scanRepository } from '../../scanner/repo-scanner.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps, writeMaps } from '../../storage/map-store.js';
+import { runCommand } from '../errors.js';
+import { renderContextMarkdown } from './context.js';
+export async function runDefaultWorkflow(query) {
+    await runCommand(async () => {
+        const topic = query?.trim();
+        const workspace = await assertWorkspace(process.cwd());
+        const config = await loadConfig(workspace);
+        const previousMaps = await readMaps(workspace);
+        const scan = await scanRepository(workspace.rootPath, config, {
+            files: previousMaps.fileMap.files,
+            symbols: previousMaps.symbolMap.symbols,
+            dependencies: previousMaps.dependencyMap.dependencies,
+            relationships: previousMaps.relationshipMap.relationships,
+            warnings: [],
+        });
+        await writeMaps(workspace, scan);
+        await refreshCognitionReferenceStatuses(workspace, {
+            files: scan.files,
+            symbols: scan.symbols,
+        });
+        const update = await updateCognition(workspace, { files: scan.files, symbols: scan.symbols }, false);
+        console.log(`KGraph refreshed ${scan.files.length} files, ${scan.symbols.length} symbols, and ${update.processed.length} cognition notes.`);
+        for (const warning of [...scan.warnings, ...update.warnings]) {
+            console.warn(`Warning: ${warning}`);
+        }
+        if (!topic) {
+            console.log('Add a topic to return compact context, for example: kgraph "auth token refresh"');
+            return;
+        }
+        const maps = await readMaps(workspace);
+        const response = await queryContext(workspace, config, maps, topic);
+        console.log('');
+        console.log(renderContextMarkdown(response));
+    });
+}

package/dist/cli/help.js

@@ -14,16 +14,22 @@ export function renderRootHelp(useColor = supportsColor()) {
         `  ${theme.hex('#c084fc')('and Claude Code reuse repo structure, decisions, and debugging history.')}`,
         '',
         theme.bold('Usage'),
+        '  kgraph [topic]',
         '  kgraph <command> [options]',
         '',
         theme.bold('Start'),
-        command('init', 'Create .kgraph/ workspace'),
+        command('init', 'Required once: create .kgraph/ workspace'),
         command('init --integrations codex,cursor', 'Initialize and connect AI tools'),
         '',
+        theme.bold('Daily workflow'),
+        command('kgraph', 'Refresh scan maps and process pending cognition notes'),
+        command('kgraph "auth token refresh"', 'Refresh everything and return compact context for a topic'),
+        '',
         theme.bold('Workflows'),
-        command('scan', 'Refresh file, symbol, import, and relationship maps'),
-        command('context "auth token refresh"', 'Return compact context for an AI chat'),
-        command('update', 'Process .kgraph/inbox Markdown cognition notes'),
+        command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
+        command('context "auth token refresh"', 'Optional: return context without scanning or updating'),
+        command('update', 'Optional: process only .kgraph/inbox Markdown cognition notes'),
+        command('doctor', 'Check workspace health and next actions'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history', 'Timeline of processed cognition sessions'),
         '',
@@ -38,8 +44,8 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         `${theme.yellow('Examples')}`,
         '  kgraph init --integrations codex,copilot,cursor',
-        '  kgraph scan',
-        '  kgraph context "blog admin token usage" --json',
+        '  kgraph "blog admin token usage"',
+        '  kgraph doctor',
         '',
         theme.dim('Docs: https://github.com/kentwynn/KGraph#readme'),
         '',

package/dist/cli/index.js

@@ -4,12 +4,14 @@ import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { registerContextCommand } from './commands/context.js';
+import { registerDoctorCommand } from './commands/doctor.js';
 import { registerHistoryCommand } from './commands/history.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
 import { registerScanCommand } from './commands/scan.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerVisualizeCommand } from './commands/visualize.js';
+import { runDefaultWorkflow } from './commands/workflow.js';
 import { renderRootHelp } from './help.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
@@ -18,9 +20,13 @@ export function createProgram() {
     program
         .name('kgraph')
         .description('Persistent repo intelligence for AI coding assistants')
+        .argument('[topic...]', 'Run the default refresh workflow and optionally return context for a topic')
         .version(version)
         .addHelpText('beforeAll', renderRootHelp())
-        .helpOption(false);
+        .helpOption(false)
+        .action(async (topicParts = []) => {
+        await runDefaultWorkflow(topicParts.join(' '));
+    });
     program.option('-h, --help', 'Show this help');
     program.hook('preAction', (thisCommand) => {
         if (thisCommand.opts().help) {
@@ -35,13 +41,12 @@ export function createProgram() {
     registerIntegrateCommand(program);
     registerVisualizeCommand(program);
     registerHistoryCommand(program);
+    registerDoctorCommand(program);
     return program;
 }
 if (isCliEntrypoint()) {
     const program = createProgram();
-    if (process.argv.length <= 2 ||
-        process.argv.includes('-h') ||
-        process.argv.includes('--help')) {
+    if (process.argv.includes('-h') || process.argv.includes('--help')) {
         console.log(renderRootHelp());
     }
     else {

package/dist/context/context-query.js

@@ -26,6 +26,31 @@ export async function queryContext(workspace, config, maps, query) {
         { name: 'tags', value: (domain) => domain.tags },
         { name: 'path', value: (domain) => domain.pathHints },
     ]).slice(0, max);
+    const relatedIds = new Set([
+        ...relevantFiles.map((file) => file.item.path),
+        ...relevantSymbols.map((symbol) => symbol.item.id),
+        ...relevantSymbols.map((symbol) => symbol.item.filePath),
+        ...relevantCognition.flatMap((note) => [
+            ...note.item.relatedFiles,
+            ...note.item.relatedSymbols,
+        ]),
+        ...matchedDomains.flatMap((domain) => [
+            ...domain.item.files,
+            ...domain.item.symbols,
+        ]),
+    ]);
+    const rankedRelationships = rankByFields(query, maps.relationshipMap.relationships, [
+        { name: 'source', value: (relationship) => relationship.sourceId },
+        { name: 'target', value: (relationship) => relationship.targetId },
+        { name: 'type', value: (relationship) => relationship.relationshipType },
+    ]);
+    const relationships = [
+        ...maps.relationshipMap.relationships.filter((relationship) => relatedIds.has(relationship.sourceId) ||
+            relatedIds.has(relationship.targetId)),
+        ...rankedRelationships.map((relationship) => relationship.item),
+    ].filter((relationship, index, all) => all.findIndex((candidate) => candidate.sourceId === relationship.sourceId &&
+        candidate.targetId === relationship.targetId &&
+        candidate.relationshipType === relationship.relationshipType) === index);
     const filePaths = new Set(maps.fileMap.files.map((f) => f.path));
     const symbolNames = new Set(maps.symbolMap.symbols.map((s) => s.name));
     const staleReferences = cognition
@@ -46,7 +71,7 @@ export async function queryContext(workspace, config, maps, query) {
         relevantFiles,
         relevantSymbols,
         relevantCognition,
-        relationships: maps.relationshipMap.relationships.slice(0, max),
+        relationships: relationships.slice(0, max),
         staleReferences,
         warnings: [],
     };

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

@@ -4,7 +4,7 @@ export const claudeCodeAdapter = {
     targetPath: 'CLAUDE.md',
     instructions: `## KGraph Workflow
 
-Before exploring the repository, run \`kgraph context "<topic>"\` to load existing repo intelligence. Use /kgraph for the full automated workflow. Run \`kgraph scan\` and \`kgraph update\` manually when needed.
+Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intelligence and load focused context. Use /kgraph for the full automated workflow. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
     commandFiles: [
         {
@@ -12,12 +12,13 @@ Before exploring the repository, run \`kgraph context "<topic>"\` to load existi
             content: `Use KGraph persistent repo intelligence for the current request.
 
 1. Infer the topic from the user's request.
-2. Run \`kgraph context "<topic>"\`.
+2. Run \`kgraph "<topic>"\`. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
-4. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\`.
-5. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph scan\` and report the summary. Skip it otherwise.
-6. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-7. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
+5. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
+6. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph\` or \`kgraph scan\` and report the summary. Skip it otherwise.
+7. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+8. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -35,6 +36,11 @@ One or two sentences describing what was done.
 ## Decisions
 Any architectural or implementation decisions made.
 \`\`\`
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-doctor.md',
+            content: `Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Summarize any failed checks and the next command to run.
 `,
         },
         {

package/dist/integrations/adapters/codex.js

@@ -4,7 +4,7 @@ export const codexAdapter = {
     targetPath: 'AGENTS.md',
     instructions: `## KGraph Workflow
 
-Before exploring the repository, run \`kgraph context "<topic>"\` to load existing repo intelligence. The /kgraph skill handles the full automated workflow. Run \`kgraph scan\` and \`kgraph update\` manually when needed.
+Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intelligence and load focused context. The /kgraph skill handles the full automated workflow. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
     commandFiles: [
         {
@@ -19,12 +19,13 @@ description: Use KGraph persistent repo intelligence before broad repository exp
 Workflow:
 
 1. Infer the current topic from the user request.
-2. Run \`kgraph context "<topic>"\` before broad repo exploration.
+2. Run \`kgraph "<topic>"\` before broad repo exploration. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
 3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
-4. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\`.
-5. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph scan\`. Skip it otherwise.
-6. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-7. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
+5. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
+6. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph\` or \`kgraph scan\`. Skip it otherwise.
+7. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+8. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown

package/dist/integrations/adapters/copilot.js

@@ -4,9 +4,10 @@ export const copilotAdapter = {
     targetPath: '.github/copilot-instructions.md',
     instructions: `## KGraph Workflow
 
-1. **Before exploring the repository**, run \`kgraph context "<topic>"\` to load existing repo intelligence. Use the returned files, symbols, and cognition before any broad exploration.
-2. **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, architectural constraint, non-obvious decision, or bug. For routine or read-only sessions where nothing new was found, skip capture entirely. When you do capture, immediately run \`kgraph update\`.
-3. If you created, moved, deleted, or renamed files or symbols, run \`kgraph scan\`.
+1. **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
+3. **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, architectural constraint, non-obvious decision, or bug. For routine or read-only sessions where nothing new was found, skip capture entirely. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
+4. If you created, moved, deleted, or renamed files or symbols, run \`kgraph\` or \`kgraph scan\`.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -26,6 +27,16 @@ Any architectural or implementation decisions made.
 \`\`\`
 `,
     commandFiles: [
+        {
+            path: '.github/prompts/kgraph-doctor.prompt.md',
+            content: `---
+description: Check KGraph workspace health and next actions
+agent: agent
+---
+
+Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Summarize any failed checks and the next command to run.
+`,
+        },
         {
             path: '.github/prompts/kgraph-scan.prompt.md',
             content: `---

package/dist/integrations/adapters/cursor.js

@@ -9,9 +9,10 @@ alwaysApply: true
 
 ## KGraph Workflow
 
-- **Before exploring the repository**, run \`kgraph context "<topic>"\` to load existing repo intelligence. Use the returned files, symbols, and cognition before any broad exploration.
-- **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` (title, Key Files, Key Symbols, Decisions sections) **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\`.
-- If you created, moved, deleted, or renamed files or symbols, run \`kgraph scan\`.
+- **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong.
+- **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` (title, Key Files, Key Symbols, Decisions sections) **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\` or simply run \`kgraph\`.
+- If you created, moved, deleted, or renamed files or symbols, run \`kgraph\` or \`kgraph scan\`.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
 `,

package/dist/scanner/repo-scanner.js

@@ -80,7 +80,7 @@ export async function scanRepository(rootPath, config, previous) {
                 const extracted = extractSymbols(text, repoPath);
                 symbols.push(...extracted.symbols);
                 dependencies.push(...extracted.dependencies);
-                relationships.push(...extracted.relationships);
+                relationships.push(...extracted.relationships.filter((relationship) => relationship.relationshipType !== 'import'));
                 file.warnings.push(...extracted.warnings);
             }
             files.push(file);
@@ -100,9 +100,71 @@ export async function scanRepository(rootPath, config, previous) {
             });
         }
     }
+    resolveLocalDependencies(dependencies, files);
+    relationships.push(...buildImportRelationships(dependencies));
     relationships.push(...detectMovedFiles(previous?.files ?? [], files));
     return { files, symbols, dependencies, relationships, warnings };
 }
+const SOURCE_EXTENSIONS = [
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.mts',
+    '.cts',
+    '.py',
+    '.go',
+    '.rs',
+    '.java',
+    '.kt',
+    '.kts',
+    '.c',
+    '.h',
+    '.cpp',
+    '.cc',
+    '.cxx',
+    '.hpp',
+    '.hxx',
+    '.cs',
+];
+function resolveLocalDependencies(dependencies, files) {
+    const filePaths = new Set(files.map((file) => file.path));
+    for (const dependency of dependencies) {
+        if (dependency.kind !== 'local') {
+            continue;
+        }
+        dependency.resolvedFile = resolveLocalDependencyPath(dependency.fromFile, dependency.specifier, filePaths);
+    }
+}
+function resolveLocalDependencyPath(fromFile, specifier, filePaths) {
+    if (!specifier.startsWith('.')) {
+        return undefined;
+    }
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+    const candidates = path.posix.extname(base)
+        ? [base]
+        : [
+            ...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`),
+            ...SOURCE_EXTENSIONS.map((extension) => path.posix.join(base, `index${extension}`)),
+        ];
+    return candidates.find((candidate) => filePaths.has(candidate));
+}
+function buildImportRelationships(dependencies) {
+    return dependencies.map((dependency) => ({
+        sourceType: 'file',
+        sourceId: dependency.fromFile,
+        targetType: dependency.kind === 'local' ? 'file' : 'package',
+        targetId: dependency.resolvedFile ?? dependency.specifier,
+        relationshipType: 'import',
+        confidence: dependency.resolvedFile
+            ? 'high'
+            : dependency.kind === 'local'
+                ? 'low'
+                : 'medium',
+    }));
+}
 function detectMovedFiles(previousFiles, currentFiles) {
     const currentPaths = new Set(currentFiles.map((file) => file.path));
     const previousByHash = new Map(previousFiles

package/dist/storage/cognition-store.js

@@ -26,7 +26,11 @@ export async function writeCognitionNote(workspace, note) {
 export async function writeDomainRecord(workspace, domain) {
     await mkdir(workspace.domainsPath, { recursive: true });
     const filePath = path.join(workspace.domainsPath, `${slugify(domain.name)}.md`);
-    await writeFile(filePath, renderDomainRecord(domain), "utf8");
+    const existing = (await pathExists(filePath))
+        ? parseEmbeddedJson(await readFile(filePath, "utf8"))
+        : undefined;
+    const merged = existing ? mergeDomainRecords(existing, domain) : domain;
+    await writeFile(filePath, renderDomainRecord(merged), "utf8");
     return filePath;
 }
 export async function readCognitionNotes(workspace) {
@@ -41,9 +45,9 @@ export async function readCognitionNotes(workspace) {
         }
         const filePath = path.join(workspace.cognitionPath, entry.name);
         const raw = await readFile(filePath, "utf8");
-        const encoded = raw.match(/```json\n([\s\S]*?)\n```/);
+        const encoded = parseEmbeddedJson(raw);
         if (encoded) {
-            notes.push(JSON.parse(encoded[1]));
+            notes.push(encoded);
         }
     }
     return notes;
@@ -59,13 +63,35 @@ export async function readDomainRecords(workspace) {
             continue;
         }
         const raw = await readFile(path.join(workspace.domainsPath, entry.name), "utf8");
-        const encoded = raw.match(/```json\n([\s\S]*?)\n```/);
+        const encoded = parseEmbeddedJson(raw);
         if (encoded) {
-            domains.push(JSON.parse(encoded[1]));
+            domains.push(encoded);
         }
     }
     return domains;
 }
+function parseEmbeddedJson(raw) {
+    const encoded = raw.match(/```json\n([\s\S]*?)\n```/);
+    return encoded ? JSON.parse(encoded[1]) : undefined;
+}
+function mergeDomainRecords(existing, next) {
+    return {
+        ...existing,
+        ...next,
+        description: next.description ?? existing.description,
+        pathHints: unique([...existing.pathHints, ...next.pathHints]),
+        tags: unique([...existing.tags, ...next.tags]),
+        files: unique([...existing.files, ...next.files]),
+        symbols: unique([...existing.symbols, ...next.symbols]),
+        cognitionNotes: unique([
+            ...existing.cognitionNotes,
+            ...next.cognitionNotes,
+        ]),
+    };
+}
+function unique(items) {
+    return [...new Set(items)];
+}
 export function slugify(value) {
     return value
         .trim()

package/dist/visualization/graph-builder.d.ts

@@ -13,4 +13,4 @@ export interface GraphData {
         generatedAt: string;
     };
 }
-export declare function buildGraph(fileMap: FileMap, symbolMap: SymbolMap, dependencyMap: DependencyMap, _relationshipMap: RelationshipMap, cognitionNotes: CognitionNote[]): GraphData;
+export declare function buildGraph(fileMap: FileMap, symbolMap: SymbolMap, dependencyMap: DependencyMap, relationshipMap: RelationshipMap, cognitionNotes: CognitionNote[]): GraphData;

package/dist/visualization/graph-builder.js

@@ -13,10 +13,19 @@ const STATUS_COLORS = {
     stale: '#ef4444',
     unresolved: '#6b7280',
 };
-export function buildGraph(fileMap, symbolMap, dependencyMap, _relationshipMap, cognitionNotes) {
+const SYMBOL_COLORS = {
+    function: '#22c55e',
+    class: '#a855f7',
+    method: '#14b8a6',
+    export: '#f97316',
+    import: '#64748b',
+};
+export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, cognitionNotes) {
     const elements = [];
     const edgeIds = new Set();
+    const nodeIds = new Set();
     for (const file of fileMap.files) {
+        nodeIds.add(file.id);
         elements.push({
             data: {
                 id: file.id,
@@ -31,6 +40,21 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, _relationshipMap,
             classes: `file ${file.language}`,
         });
     }
+    for (const symbol of symbolMap.symbols) {
+        nodeIds.add(symbol.id);
+        elements.push({
+            data: {
+                id: symbol.id,
+                label: symbol.name,
+                path: symbol.filePath,
+                kind: symbol.kind,
+                parentName: symbol.parentName ?? '',
+                type: 'symbol',
+                color: SYMBOL_COLORS[symbol.kind] ?? '#94a3b8',
+            },
+            classes: `symbol ${symbol.kind}`,
+        });
+    }
     for (const note of cognitionNotes) {
         const id = `cognition-${note.id}`;
         elements.push({
@@ -88,6 +112,27 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, _relationshipMap,
             }
         }
     }
+    for (const relationship of relationshipMap.relationships) {
+        if (!nodeIds.has(relationship.sourceId) || !nodeIds.has(relationship.targetId)) {
+            continue;
+        }
+        const edgeId = `rel-${relationship.relationshipType}-${relationship.sourceId}-${relationship.targetId}`;
+        if (edgeIds.has(edgeId)) {
+            continue;
+        }
+        edgeIds.add(edgeId);
+        elements.push({
+            data: {
+                id: edgeId,
+                source: relationship.sourceId,
+                target: relationship.targetId,
+                type: relationship.relationshipType,
+                confidence: relationship.confidence,
+                label: relationship.relationshipType,
+            },
+            classes: `relationship ${relationship.relationshipType}`,
+        });
+    }
     return {
         elements,
         meta: {

package/package.json

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