@kentwynn/kgraph 0.2.11 → 0.2.13

package/README.md

@@ -2,7 +2,7 @@
 
 Persistent repository intelligence for AI coding tools.
 
-KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable notes from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
+KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable knowledge atoms from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
 
 ## The Workflow
 
@@ -20,7 +20,7 @@ That second command runs the full practical workflow:
 
 1. Refreshes the repository scan.
 2. Updates file, symbol, import, and relationship maps.
-3. Processes any Markdown notes waiting in `.kgraph/inbox/`.
+3. Processes any Markdown capture notes waiting in `.kgraph/inbox/` into knowledge atoms.
 4. Returns compact context for the topic you asked about.
 
 You can also run just:
@@ -29,7 +29,7 @@ You can also run just:
 kgraph
 ```
 
-That refreshes maps and cognition without printing topic-specific context.
+That refreshes maps and durable memory without printing topic-specific context.
 
 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.
 
@@ -52,8 +52,8 @@ KGraph stores the reusable parts locally:
 - What symbols each source file defines.
 - Which files import each other.
 - Which TypeScript/JavaScript functions and methods directly call each other when KGraph can infer it cheaply.
-- Which notes, decisions, debugging findings, and gotchas were captured from prior sessions.
-- Which cognition references are current, mixed, stale, or unresolved after code moves.
+- Which decisions, debugging findings, gotchas, summaries, and relationships were captured as knowledge atoms.
+- Which atoms are active, need review, stale, archived, or superseded after code moves.
 
 Then an AI assistant can ask for focused context before broad exploration:
 
@@ -61,8 +61,8 @@ Then an AI assistant can ask for focused context before broad exploration:
 kgraph "blog admin token usage"
 ```
 
-Instead of reading the whole repo, it gets a compact starting point: relevant files, symbols, relationships, domains, prior notes, and stale references to watch.
-Each context item explains why it was returned, such as a path/name match, a matched cognition reference, a domain match, or a nearby import relationship.
+Instead of reading the whole repo, it gets a compact starting point: relevant files, symbols, relationships, domains, knowledge atoms, and stale references to watch.
+Each context item explains why it was returned, such as a path/name match, a matched atom reference, a domain match, or a nearby import relationship.
 
 When you need change impact instead of broad context:
 
@@ -70,7 +70,7 @@ When you need change impact instead of broad context:
 kgraph impact Button
 ```
 
-That shows matched files/symbols, files importing the target, known callers/callees, related cognition, and simple risk signals.
+That shows matched files/symbols, files importing the target, known callers/callees, related knowledge atoms, and simple risk signals.
 
 ## Install
 
@@ -125,7 +125,7 @@ kgraph "topic"
 kgraph
 ```
 
-Use `kgraph doctor` after setup and before trusting a repo's saved intelligence. It checks initialization, maps, pending inbox notes, integration targets, and actionable quality problems. Use `kgraph doctor --quality` and `kgraph repair --dry-run` when stale or noisy cognition references start making context harder to trust.
+Use `kgraph doctor` after setup and before trusting a repo's saved intelligence. It checks initialization, maps, pending inbox notes, integration targets, and actionable quality problems. Use `kgraph doctor --quality` and `kgraph repair --dry-run` when stale or noisy atom references start making context harder to trust.
 
 Agents can also report session activity so KGraph can estimate token waste:
 
@@ -157,29 +157,29 @@ Initializes KGraph and writes local instruction files for supported AI tools.
 kgraph "some topic"
 ```
 
-The normal command. Scans the repo, updates cognition, and returns focused context for the topic.
+The normal command. Scans the repo, updates durable memory, and returns focused context for the topic.
 
 ```bash
 kgraph
 ```
 
-Refreshes maps and cognition without returning topic-specific context.
+Refreshes maps and durable memory without returning topic-specific context.
 
 ```bash
 kgraph doctor
 kgraph doctor --quality
 ```
 
-Checks whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use `--quality` when context shows stale/noisy cognition references, unresolved local imports, unresolved call edges, duplicate cognition titles, or generated files in the scan.
+Checks whether the workspace is initialized, maps exist, inbox notes are pending, knowledge storage is valid, and configured integrations point to real files. Use `--quality` when context shows stale/noisy atom references, unresolved local imports, unresolved call edges, duplicate atom topics, or generated files in the scan.
 
-The default doctor result is the main quality gate. It fails on actionable hygiene issues such as stale/noisy cognition, duplicate cognition titles, generated integration files leaking into scans, missing maps, or broken integration targets. Scanner coverage counts such as unresolved local imports or unresolved call edges remain visible in `--quality`, but they do not fail the gate by themselves because they often reflect current parser limits.
+The default doctor result is the main quality gate. It fails on actionable hygiene issues such as stale/noisy atoms, duplicate atom topics, generated integration files leaking into scans, missing maps, invalid knowledge storage, or broken integration targets. Scanner coverage counts such as unresolved local imports or unresolved call edges remain visible in `--quality`, but they do not fail the gate by themselves because they often reflect current parser limits.
 
 ```bash
 kgraph repair --dry-run
 kgraph repair
 ```
 
-`repair --dry-run` previews cleanup for noisy cognition references, such as framework names recorded as files or local variables recorded as symbols. `repair` applies only the safe noisy-reference cleanup; broader quality findings stay report-only. Run repair intentionally when stale references make context noisy; it is not part of every normal workflow.
+`repair --dry-run` previews cleanup for noisy atom references, such as framework names recorded as files or local variables recorded as symbols. `repair` applies only the safe noisy-reference cleanup; broader quality findings stay report-only. Run repair intentionally when stale references make context noisy; it is not part of every normal workflow.
 
 ```bash
 kgraph uninstall
@@ -194,7 +194,7 @@ kgraph impact "Button"
 kgraph impact "createSession" --json
 ```
 
-Show practical impact for a file, symbol, or topic: matched files/symbols, import users, callers, callees, ownership edges, related cognition, and risk hints.
+Show practical impact for a file, symbol, or topic: matched files/symbols, import users, callers, callees, ownership edges, related knowledge atoms, and risk hints.
 
 ```bash
 kgraph session
@@ -208,7 +208,7 @@ kgraph session end --agent codex --conclude --topic "auth token refresh"
 ```
 
 Track agent-reported read/write activity, repeated reads, and estimated token cost. Supported agents are `codex`, `claude-code`, `copilot`, `cursor`, `gemini`, `windsurf`, and `cline`.
-The text report now includes next actions, such as using `kgraph context "<topic>"` before repeated broad file inspection. Add `--conclude` to store a durable session summary with touched files attached as related cognition.
+The text report includes next actions, such as using `kgraph context "<topic>"` before repeated broad file inspection. Add `--conclude` to store a durable session summary with touched files attached as atom evidence.
 
 ```bash
 kgraph conclude "auth refresh requires rotating the session cookie" \
@@ -220,7 +220,7 @@ kgraph conclude "auth refresh requires rotating the session cookie" \
   --note "The refresh path must update both the access token and cookie expiry."
 ```
 
-Store durable engineering memory directly. Cognition is typed as `finding`, `decision`, `gotcha`, `summary`, or `relationship`, and confidence is `high`, `medium`, or `low`. Keep conclusions concise: preserve expensive-to-rediscover knowledge, not raw chain-of-thought, speculative exploration, or temporary reasoning.
+Store durable engineering memory directly. Knowledge atoms are typed as `finding`, `decision`, `gotcha`, `summary`, or `relationship`, and confidence is `high`, `medium`, or `low`. Keep conclusions concise: preserve expensive-to-rediscover knowledge, not raw chain-of-thought, speculative exploration, or temporary reasoning.
 
 KGraph stores these conclusions as canonical knowledge atoms under `.kgraph/knowledge/` while keeping existing Markdown cognition files readable for compatibility.
 
@@ -273,8 +273,8 @@ kgraph context "auth token refresh"
 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.
+Return context from existing maps and knowledge atoms without scanning or updating first.
+Markdown output includes the reason each file, symbol, knowledge atom, 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`.
 
@@ -283,7 +283,7 @@ kgraph update
 kgraph update --dry-run
 ```
 
-Process Markdown notes from `.kgraph/inbox/` into durable cognition records.
+Process Markdown capture notes from `.kgraph/inbox/` into durable knowledge atoms and compatibility Markdown.
 
 ```bash
 kgraph visualize
@@ -300,7 +300,7 @@ kgraph history "blog button"
 kgraph history --json
 ```
 
-Show processed cognition sessions. Add a query to find historical work by title, summary, file, symbol, or note body.
+Show processed capture history. Add a query to find historical work by title, summary, file, symbol, or note body.
 
 ## AI Tool Integrations
 
@@ -308,13 +308,13 @@ KGraph integrations are local files. They do not start background agents, call A
 
 ```bash
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
-kgraph integrate add copilot --mode always
+kgraph integrate add copilot --mode smart
 kgraph integrate set copilot --mode manual
 kgraph integrate list
 kgraph integrate remove cursor
 ```
 
-New integrations default to `smart` mode. Use `--mode always` to force KGraph on every chat, or `--mode manual` to run only when explicitly asked.
+New integrations default to `always` mode, so every chat in the repository starts with `kgraph "<topic>"`. Use `--mode smart` to run KGraph only for repo-specific work, or `--mode manual` to run only when explicitly asked.
 
 | Mode     | Behavior                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -383,14 +383,13 @@ Other languages keep practical file, import, and symbol depth without full call
 kgraph visualize
 ```
 
-The graph shows files, symbols, imports, TypeScript/JavaScript call edges, ownership edges, cognition notes, and relationship edges. Cognition notes are colored by reference health:
+The graph shows files, imports, TypeScript/JavaScript call edges, ownership edges, relationship edges, and canonical knowledge atoms. Symbols are kept out of the main rendered graph for performance and shown in the file detail panel instead. Atom nodes are capped in large memory sets and colored by lifecycle status:
 
-- current
-- mixed
+- active
+- needs-review
 - 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.
+Use it when you want to inspect what KGraph currently knows, find stale atoms after refactors, or export a graph image for a report.
 
 ## Development
 
@@ -465,4 +464,4 @@ The release workflow builds, tests, packs, publishes the npm package on version
 - Stronger TypeScript path alias and package export resolution.
 - Richer graph filtering for large repositories.
 - Optional MCP and editor integration.
-- Team-friendly shared cognition workflows that stay local-first.
+- Team-friendly shared knowledge workflows that stay local-first.

package/dist/cli/commands/doctor.js

@@ -114,7 +114,8 @@ export function registerDoctorCommand(program) {
                     .join('; '),
         });
         let qualityReport;
-        if (maps) {
+        const knowledgeReadable = !knowledgeIssues.some((issue) => issue.code === 'invalid-jsonl' || issue.code === 'missing-schema');
+        if (maps && knowledgeReadable) {
             qualityReport = await analyzeCognitionQuality(workspace, maps);
             const qualityFindings = summarizeQualityFindings(qualityReport);
             const coverageNotes = summarizeCoverageNotes(qualityReport);
@@ -129,8 +130,15 @@ export function registerDoctorCommand(program) {
                     : qualityFindings.join('; '),
             });
         }
+        else if (maps) {
+            checks.push({
+                label: 'quality gate',
+                ok: false,
+                detail: 'knowledge storage is invalid; fix knowledge check first',
+            });
+        }
         printChecks(checks);
-        if (options.quality && maps) {
+        if (options.quality && maps && knowledgeReadable) {
             console.log('');
             console.log('KGraph Cognition Quality');
             console.log('');
@@ -156,14 +164,19 @@ function printChecks(checks) {
     }
 }
 export function printQualityReport(report) {
-    console.log(`Notes: ${report.noteCount}`);
-    console.log(`Mixed/stale/unresolved notes: ${report.mixedOrStaleCount}`);
-    console.log(`Orphaned notes (all refs dead): ${report.orphanedNoteCount}`);
+    console.log(`Atoms: ${report.atomCount}`);
+    console.log(`Needs-review atoms: ${report.needsReviewAtomCount}`);
+    console.log(`Stale atoms: ${report.staleAtomCount}`);
+    console.log(`Archived atoms: ${report.archivedAtomCount}`);
+    console.log(`Duplicate atom topics: ${report.duplicateAtomTopicCount}`);
+    console.log(`Compatibility notes: ${report.noteCount}`);
+    console.log(`Mixed/stale/unresolved compatibility notes: ${report.mixedOrStaleCount}`);
+    console.log(`Orphaned atoms (all refs dead): ${report.orphanedNoteCount}`);
     console.log(`Noisy file refs: ${report.noisyFileRefCount}`);
     console.log(`Noisy symbol refs: ${report.noisySymbolRefCount}`);
     console.log(`Unresolved local imports: ${report.unresolvedLocalImportCount}`);
     console.log(`Unresolved call edges: ${report.unresolvedCallCount}`);
-    console.log(`Duplicate cognition titles: ${report.duplicateTitleCount}`);
+    console.log(`Duplicate compatibility note titles: ${report.duplicateTitleCount}`);
     console.log(`Generated files scanned: ${report.generatedFileScanCount}`);
     console.log(`Expensive files: ${report.expensiveFileCount}`);
     console.log(`Session repeated reads: ${report.sessionRepeatedReadCount}`);
@@ -187,16 +200,16 @@ export function printQualityReport(report) {
 function summarizeQualityFindings(report) {
     const findings = [];
     if (report.orphanedNoteCount > 0) {
-        findings.push(`${report.orphanedNoteCount} orphaned cognition note(s) (all refs dead); run \`kgraph repair\` to archive`);
+        findings.push(`${report.orphanedNoteCount} orphaned atom(s) (all refs dead); run \`kgraph repair\` to archive`);
     }
-    if (report.mixedOrStaleCount > 0) {
-        findings.push(`${report.mixedOrStaleCount} stale/mixed/unresolved note(s)`);
+    if (report.staleAtomCount > 0 || report.needsReviewAtomCount > 0) {
+        findings.push(`${report.staleAtomCount} stale atom(s), ${report.needsReviewAtomCount} needs-review atom(s)`);
     }
     if (report.noisyFileRefCount > 0 || report.noisySymbolRefCount > 0) {
-        findings.push(`${report.noisyFileRefCount + report.noisySymbolRefCount} noisy cognition ref(s); run \`kgraph repair --dry-run\``);
+        findings.push(`${report.noisyFileRefCount + report.noisySymbolRefCount} noisy atom ref(s); run \`kgraph repair --dry-run\``);
     }
-    if (report.duplicateTitleCount > 0) {
-        findings.push(`${report.duplicateTitleCount} duplicate cognition title(s)`);
+    if (report.duplicateAtomTopicCount > 0) {
+        findings.push(`${report.duplicateAtomTopicCount} duplicate atom topic(s)`);
     }
     if (report.generatedFileScanCount > 0) {
         findings.push(`${report.generatedFileScanCount} generated/integration file(s) scanned; update excludes`);

package/dist/cli/commands/impact.js

@@ -1,6 +1,6 @@
 import { loadConfig } from '../../config/config.js';
 import { analyzeImpact } from '../../context/impact.js';
-import { readCognitionNotes } from '../../storage/cognition-store.js';
+import { atomToCognitionNote, refreshKnowledgeAtomStatuses, } from '../../knowledge/atom-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
@@ -17,11 +17,17 @@ export function registerImpactCommand(program) {
         if (!(await mapsExist(workspace))) {
             throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
-        const [config, maps, cognition] = await Promise.all([
+        const [config, maps] = await Promise.all([
             loadConfig(workspace),
             readMaps(workspace),
-            readCognitionNotes(workspace),
         ]);
+        const { atoms } = await refreshKnowledgeAtomStatuses(workspace, {
+            fileMap: maps.fileMap,
+            symbolMap: maps.symbolMap,
+        });
+        const cognition = atoms
+            .filter((atom) => atom.status !== 'archived')
+            .map(atomToCognitionNote);
         const response = analyzeImpact(query, maps, cognition, config.maxContextItems);
         console.log(options.json ? JSON.stringify(response, null, 2) : renderImpactMarkdown(response));
     }));
@@ -40,8 +46,8 @@ export function renderImpactMarkdown(response) {
     lines.push(...formatList(response.calls.map((rel) => `- ${rel.sourceId} calls ${rel.targetId} (${rel.confidence})`)));
     lines.push('', '## Ownership', '');
     lines.push(...formatList(response.ownership.map((rel) => `- ${rel.sourceId} owns ${rel.targetId} (${rel.confidence})`)));
-    lines.push('', '## Related Cognition', '');
-    lines.push(...formatList(response.relatedCognition.map((note) => `- ${note.title} [${note.referencesStatus}]`)));
+    lines.push('', '## Related Knowledge', '');
+    lines.push(...formatList(response.relatedCognition.map((note) => `- ${note.title} [${note.referencesStatus}, ${note.confidence}]`)));
     lines.push('', '## Risk', '');
     lines.push(...formatList(response.risk.map((item) => `- ${item}`)));
     return lines.join('\n');

package/dist/cli/commands/init.js

@@ -15,7 +15,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', 'smart')
+        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         await ensureKnowledgeStore(workspace);
@@ -55,7 +55,7 @@ export function registerInitCommand(program) {
         })) {
             const selected = await promptForInitIntegrations(recommendedIntegrations);
             if (selected.length > 0) {
-                const changed = await addIntegrations(workspace, selected, 'smart');
+                const changed = await addIntegrations(workspace, selected, 'always');
                 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', 'smart')
+        .option('--mode <mode>', 'always, smart, manual, or off', 'always')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);

package/dist/cli/commands/repair.js

@@ -6,8 +6,8 @@ import { printQualityReport } from './doctor.js';
 export function registerRepairCommand(program) {
     program
         .command('repair')
-        .description('Clean noisy stale references from KGraph cognition')
-        .option('--dry-run', 'Show proposed cognition cleanup without writing files')
+        .description('Clean noisy stale references from KGraph knowledge atoms')
+        .option('--dry-run', 'Show proposed atom cleanup without writing files')
         .action((options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         if (!(await mapsExist(workspace))) {
@@ -21,7 +21,7 @@ export function registerRepairCommand(program) {
         console.log('');
         printQualityReport(report);
         if (report.changes.length === 0) {
-            console.log('No noisy cognition references found.');
+            console.log('No noisy atom references found.');
         }
         else if (options.dryRun) {
             console.log('');

package/dist/cli/commands/uninstall.js

@@ -1,8 +1,13 @@
 import { rm } from 'node:fs/promises';
+import path from 'node:path';
 import { loadConfig } from '../../config/config.js';
 import { removeIntegrations } from '../../integrations/integration-store.js';
 import { pathExists, resolveWorkspace } from '../../storage/kgraph-paths.js';
 import { runCommand } from '../errors.js';
+const LEGACY_GENERATED_FILES = [
+    '.github/agents/kgraph.agent.md',
+    '.github/kgraph.agent.md',
+];
 export function registerUninstallCommand(program) {
     program
         .command('uninstall')
@@ -28,6 +33,7 @@ export function registerUninstallCommand(program) {
             !options.keepIntegrations &&
             configuredIntegrations.length > 0) {
             await removeIntegrations(workspace, configuredIntegrations);
+            await removeLegacyGeneratedFiles(workspace.rootPath);
         }
         if (initialized) {
             await rm(workspace.kgraphPath, { recursive: true, force: true });
@@ -37,6 +43,9 @@ export function registerUninstallCommand(program) {
         console.log('Run `kgraph init` to set up this repository again.');
     }));
 }
+async function removeLegacyGeneratedFiles(rootPath) {
+    await Promise.all(LEGACY_GENERATED_FILES.map((filePath) => rm(path.join(rootPath, filePath), { force: true })));
+}
 function printUninstallPreview(input) {
     console.log('KGraph Uninstall Preview');
     console.log('');

package/dist/cli/commands/visualize.js

@@ -1,7 +1,7 @@
 import { exec } from 'node:child_process';
 import { createServer } from 'node:http';
 import { loadConfig } from '../../config/config.js';
-import { readCognitionNotes } from '../../storage/cognition-store.js';
+import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { buildGraph } from '../../visualization/graph-builder.js';
@@ -22,12 +22,13 @@ export function registerVisualizeCommand(program) {
         if (!(await mapsExist(workspace))) {
             throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
-        const [maps, cognition] = await Promise.all([
-            readMaps(workspace),
-            readCognitionNotes(workspace),
-        ]);
+        const maps = await readMaps(workspace);
+        const { atoms } = await refreshKnowledgeAtomStatuses(workspace, {
+            fileMap: maps.fileMap,
+            symbolMap: maps.symbolMap,
+        });
         await loadConfig(workspace); // ensure workspace is valid
-        const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, cognition);
+        const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, atoms);
         const html = renderHtml(graphData, workspace.rootPath);
         await serveGraph(html, port, options.open);
     }));

package/dist/cli/help.js

@@ -22,7 +22,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
         '',
         theme.bold('Daily workflow'),
-        command('kgraph', 'Refresh scan maps and process pending cognition notes'),
+        command('kgraph', 'Refresh scan maps and process pending capture notes'),
         command('kgraph "auth token refresh"', 'Refresh everything and return compact context for a topic'),
         '',
         theme.bold('Workflows'),
@@ -30,19 +30,19 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('session', 'Show agent read/write activity and token estimates'),
         command('session read src/auth.ts --agent codex', 'Record an agent file read'),
         command('session end --agent codex --conclude', 'End tracking and store a durable session summary'),
-        command('conclude "auth refresh gotcha"', 'Store typed engineering cognition'),
-        command('compact', 'Merge duplicate cognition and archive stale noise'),
+        command('conclude "auth refresh gotcha"', 'Store typed engineering knowledge'),
+        command('compact', 'Merge duplicate atoms and archive stale noise'),
         command('knowledge list', 'Inspect canonical knowledge atoms'),
         command('pack "auth task" --budget 8000', 'Build a budget-aware context pack'),
         command('stale', 'Show atoms invalidated by changed or missing refs'),
         command('blame <atom-id>', 'Show atom provenance and evidence'),
         command('context "auth token refresh"', 'Optional: return context without scanning or updating'),
-        command('impact "Button"', 'Show imports, callers, calls, cognition, and risk'),
-        command('update', 'Optional: process only .kgraph/inbox Markdown cognition notes'),
+        command('impact "Button"', 'Show imports, callers, calls, knowledge, and risk'),
+        command('update', 'Optional: process only .kgraph/inbox capture notes'),
         command('doctor', 'Check workspace health and next actions'),
-        command('doctor --quality', 'Report stale/noisy cognition references'),
-        command('repair --dry-run', 'Preview cognition reference cleanup'),
-        command('repair', 'Clean noisy stale cognition references'),
+        command('doctor --quality', 'Report stale/noisy atom references'),
+        command('repair --dry-run', 'Preview atom reference cleanup'),
+        command('repair', 'Clean noisy stale atom references'),
         command('uninstall', 'Preview repo-local KGraph removal'),
         command('uninstall --yes', 'Remove .kgraph/ and managed integrations'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
@@ -51,7 +51,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         theme.bold('Integrations'),
         command('integrate list', 'Show configured AI tool integrations'),
         command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
-        command('integrate add copilot --mode always', 'Every Copilot chat starts with kgraph "<topic>"'),
+        command('integrate add copilot --mode smart', 'Run KGraph for repo-specific Copilot work only'),
         command('integrate set copilot --mode manual', 'Only run KGraph when explicitly requested'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
@@ -91,13 +91,13 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
                 ? ` (${stats.skippedFiles} unchanged, skipped)`
                 : '')),
         command('symbols', String(stats.symbols)),
-        command('cognition notes processed', String(stats.cognitionNotes)),
+        command('capture notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),
         '',
         theme.bold('Next'),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
-        command('kgraph doctor --quality', 'Check cognition quality'),
+        command('kgraph doctor --quality', 'Check atom quality'),
         command('kgraph knowledge list', 'Inspect knowledge atoms'),
         command('kgraph pack "auth task"', 'Build budget-aware context'),
         command('kgraph session', 'Check session token waste'),

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

@@ -9,6 +9,11 @@ export interface CognitionRepairChange {
     nextStatus: ReferenceStatus;
 }
 export interface CognitionQualityReport {
+    atomCount: number;
+    staleAtomCount: number;
+    needsReviewAtomCount: number;
+    archivedAtomCount: number;
+    duplicateAtomTopicCount: number;
     noteCount: number;
     mixedOrStaleCount: number;
     noisyFileRefCount: number;

package/dist/cognition/cognition-quality.js

@@ -1,9 +1,13 @@
 import { mkdir, rename } from 'node:fs/promises';
 import path from 'node:path';
+import { atomToCognitionNote, refreshKnowledgeAtomStatuses, writeKnowledgeAtoms, } from '../knowledge/atom-store.js';
 import { buildSessionReport } from '../session/session-store.js';
-import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
+import { overwriteDomainRecord, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
 export async function analyzeCognitionQuality(workspace, maps) {
-    const notes = await readCognitionNotes(workspace);
+    const refreshed = await refreshKnowledgeAtomStatuses(workspace, { fileMap: maps.fileMap, symbolMap: maps.symbolMap }, true);
+    const atoms = refreshed.atoms;
+    const activeAtoms = atoms.filter((atom) => atom.status !== 'archived');
+    const notes = activeAtoms.map(atomToCognitionNote);
     const session = await buildSessionReport(workspace);
     const changes = notes
         .map((note) => analyzeNote(note, maps))
@@ -11,13 +15,18 @@ export async function analyzeCognitionQuality(workspace, maps) {
         change.removedSymbolRefs.length > 0);
     const orphanedNoteCount = notes.filter((note) => note.referencesStatus === 'stale').length;
     return {
+        atomCount: activeAtoms.length,
+        staleAtomCount: activeAtoms.filter((atom) => atom.status === 'stale').length,
+        needsReviewAtomCount: activeAtoms.filter((atom) => atom.status === 'needs-review').length,
+        archivedAtomCount: atoms.filter((atom) => atom.status === 'archived').length,
+        duplicateAtomTopicCount: countDuplicateAtomTopics(activeAtoms),
         noteCount: notes.length,
         mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
         unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
         unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
-        duplicateTitleCount: countDuplicateTitles(notes),
+        duplicateTitleCount: countDuplicateAtomTopics(activeAtoms),
         generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         expensiveFileCount: countExpensiveFiles(maps.fileMap),
         sessionRepeatedReadCount: session.repeatedReadCount,
@@ -28,10 +37,14 @@ export async function analyzeCognitionQuality(workspace, maps) {
     };
 }
 export async function repairCognition(workspace, maps, dryRun = false) {
-    const notes = await readCognitionNotes(workspace);
+    const refreshed = await refreshKnowledgeAtomStatuses(workspace, { fileMap: maps.fileMap, symbolMap: maps.symbolMap }, dryRun);
+    const atoms = refreshed.atoms;
+    const activeAtoms = atoms.filter((atom) => atom.status !== 'archived');
+    const notes = activeAtoms.map(atomToCognitionNote);
     const session = await buildSessionReport(workspace);
     const nextNotes = [];
     const changes = [];
+    const changesById = new Map();
     for (const note of notes) {
         const change = analyzeNote(note, maps);
         const nextNote = applyChange(note, change);
@@ -39,6 +52,7 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         if (change.removedFileRefs.length > 0 ||
             change.removedSymbolRefs.length > 0) {
             changes.push(change);
+            changesById.set(change.noteId, change);
             if (!dryRun) {
                 await writeCognitionNote(workspace, nextNote);
             }
@@ -47,8 +61,58 @@ export async function repairCognition(workspace, maps, dryRun = false) {
     // Archive fully-orphaned notes (all refs dead) so they no longer appear in context
     const orphanedNotes = nextNotes.filter((note) => note.referencesStatus === 'stale');
     if (!dryRun && (changes.length > 0 || orphanedNotes.length > 0)) {
+        const now = new Date().toISOString();
+        const nextAtoms = atoms.map((atom) => {
+            if (atom.status === 'archived')
+                return atom;
+            const change = changesById.get(atom.id);
+            if (!change && !orphanedNotes.some((note) => note.id === atom.id)) {
+                return atom;
+            }
+            if (orphanedNotes.some((note) => note.id === atom.id)) {
+                return {
+                    ...atom,
+                    status: 'archived',
+                    confidence: 'low',
+                    lifecycle: { ...atom.lifecycle, archivedAt: now },
+                    provenance: { ...atom.provenance, updatedAt: now },
+                };
+            }
+            const removedFiles = new Set(change?.removedFileRefs ?? []);
+            const removedSymbols = new Set(change?.removedSymbolRefs ?? []);
+            const nextStatus = atomStatusFromReferenceStatus(change?.nextStatus ?? 'current');
+            return {
+                ...atom,
+                status: nextStatus,
+                confidence: atom.confidence === 'low' && atom.status === 'stale' && nextStatus !== 'stale'
+                    ? 'medium'
+                    : atom.confidence,
+                scopeRefs: {
+                    ...atom.scopeRefs,
+                    files: atom.scopeRefs.files.filter((file) => !removedFiles.has(file)),
+                    symbols: atom.scopeRefs.symbols.filter((symbol) => !removedSymbols.has(symbol)),
+                },
+                evidenceRefs: atom.evidenceRefs.filter((ref) => {
+                    if (ref.type === 'file')
+                        return !removedFiles.has(ref.path);
+                    if (ref.type === 'symbol')
+                        return !removedSymbols.has(ref.name);
+                    return true;
+                }),
+                lifecycle: {
+                    ...atom.lifecycle,
+                    invalidatedBy: change?.nextStatus === 'current'
+                        ? undefined
+                        : atom.lifecycle.invalidatedBy,
+                },
+                provenance: { ...atom.provenance, updatedAt: now },
+            };
+        });
+        await writeKnowledgeAtoms(workspace, nextAtoms);
         // Exclude fully-orphaned notes from domain records — they are being archived
-        await repairDomainRecords(workspace, nextNotes.filter((n) => n.referencesStatus !== 'stale'), maps);
+        await repairDomainRecords(workspace, nextAtoms
+            .filter((atom) => atom.status !== 'archived')
+            .map(atomToCognitionNote), maps);
     }
     if (!dryRun) {
         for (const note of orphanedNotes) {
@@ -57,6 +121,11 @@ export async function repairCognition(workspace, maps, dryRun = false) {
     }
     const orphanedNoteCount = orphanedNotes.length;
     return {
+        atomCount: activeAtoms.length,
+        staleAtomCount: nextNotes.filter((note) => note.referencesStatus === 'stale').length,
+        needsReviewAtomCount: nextNotes.filter((note) => note.referencesStatus === 'mixed').length,
+        archivedAtomCount: atoms.filter((atom) => atom.status === 'archived').length + orphanedNoteCount,
+        duplicateAtomTopicCount: countDuplicateTitles(nextNotes),
         noteCount: notes.length,
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
@@ -98,6 +167,23 @@ function countDuplicateTitles(notes) {
     }
     return duplicates.size;
 }
+function countDuplicateAtomTopics(atoms) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const atom of atoms) {
+        const key = [
+            atom.type,
+            atom.topic.trim().toLowerCase(),
+            atom.claim.trim().toLowerCase(),
+        ].join('\0');
+        if (!atom.topic.trim())
+            continue;
+        if (seen.has(key))
+            duplicates.add(key);
+        seen.add(key);
+    }
+    return duplicates.size;
+}
 function countGeneratedScannedFiles(fileMap) {
     return fileMap.files.filter((file) => [
         '.agents/',
@@ -175,6 +261,13 @@ function evaluateReferenceStatus(relatedFiles, relatedSymbols, maps) {
         return 'stale';
     return 'mixed';
 }
+function atomStatusFromReferenceStatus(status) {
+    if (status === 'current')
+        return 'active';
+    if (status === 'mixed')
+        return 'needs-review';
+    return 'stale';
+}
 function isNoisyFileRef(ref) {
     return (!ref.includes('/') && /^[A-Z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(ref));
 }

package/dist/config/config.js

@@ -157,7 +157,7 @@ function normalizeIntegrations(value) {
     return integrations;
 }
 function normalizeIntegrationMode(value) {
-    return value === 'always' || value === 'manual' || value === 'off'
+    return value === 'smart' || value === 'manual' || value === 'off'
         ? value
-        : 'smart';
+        : 'always';
 }

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

@@ -1,4 +1,3 @@
-import { numberedWorkflow } from '../workflow-steps.js';
 export const claudeCodeAdapter = {
     name: 'claude-code',
     label: 'Claude Code',
@@ -6,13 +5,22 @@ export const claudeCodeAdapter = {
     instructions: `## KGraph Workflow
 
 {{KGRAPH_CONTEXT_POLICY}} Use /kgraph for the full automated workflow. Run \`kgraph pack "<task>" --budget 8000 --json\` for a machine-readable token-budgeted context pack, \`kgraph knowledge list\` or \`kgraph knowledge get <atom-id>\` to inspect durable atoms, \`kgraph stale\` and \`kgraph blame <atom-id>\` when lifecycle/provenance matters, \`kgraph conclude\` for durable typed engineering memory, and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. 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.
+
+{{KGRAPH_CAPTURE_POLICY}}
 `,
     commandFiles: [
         {
             path: '.claude/commands/kgraph.md',
-            content: `Use KGraph persistent repo intelligence for the current request.
+            content: `Use KGraph persistent repo intelligence through the single normal \`kgraph "<topic>"\` entry point.
 
-${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are unavailable' })}
+1. Infer a concise topic from the user's request.
+2. Run exactly one command from the repository root: \`kgraph "<topic>"\`.
+3. Treat the returned files, symbols, relationships, atoms, and warnings as the first-pass source of truth.
+4. If the user asked for an edit, inspect only the returned candidate file or the smallest necessary range, then make the edit.
+5. Verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.
+6. Do not run \`kgraph\` again, \`kgraph context\`, \`kgraph pack\`, \`kgraph knowledge\`, \`kgraph stale\`, \`kgraph blame\`, \`kgraph scan\`, \`kgraph update\`, \`kgraph compact\`, or \`kgraph repair\` unless the user explicitly asks for that lower-level command.
+7. Do not continue broad repository search after the target file is identified. If a path must be located, prefer \`rg --files\` and quote paths containing spaces or parentheses.
+8. At the end of repository-file changes, store durable engineering memory with \`kgraph conclude "<topic>" --type <finding|decision|gotcha|summary|relationship> --confidence <high|medium|low>\` only when the work created reusable engineering knowledge.
 `,
         },
         {
@@ -22,7 +30,7 @@ ${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are una
         },
         {
             path: '.claude/commands/kgraph-repair.md',
-            content: `Run \`kgraph repair --dry-run\` first and summarize the proposed cognition cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
+            content: `Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
 `,
         },
         {
@@ -67,7 +75,7 @@ ${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are una
         },
         {
             path: '.claude/commands/kgraph-impact.md',
-            content: `Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
+            content: `Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
 `,
         },
         {

package/dist/integrations/adapters/copilot.js

@@ -8,26 +8,6 @@ export const copilotAdapter = {
 ${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, pack, knowledge, stale, blame, scan, update, conclude, compact, 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 Agent
-
-You are a KGraph-powered agent. Before exploring the repository freely, always:
-
-${numberedWorkflow('copilot')}
-`,
-        },
         {
             path: '.github/prompts/kgraph-doctor.prompt.md',
             content: `---
@@ -46,7 +26,7 @@ agent: agent
 argument-hint: "--dry-run or apply"
 ---
 
-Run \`kgraph repair --dry-run\` first and summarize the proposed cognition cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
+Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
 `,
         },
         {
@@ -165,7 +145,7 @@ agent: agent
 argument-hint: "File, symbol, or topic"
 ---
 
-Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
+Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
 `,
         },
         {

package/dist/integrations/instruction-blocks.js

@@ -36,16 +36,17 @@ export function applyContextPolicy(content, mode) {
         .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy());
 }
 export function renderContextPolicy(mode) {
+    const useResultBoundary = 'Use the returned KGraph candidate files as the first-pass source of truth. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file is identified, do not retry malformed shell commands with broader variants, and do not run broad `find`, recursive `grep`, or repeated full-file dumps after KGraph has narrowed the target.';
     switch (mode) {
         case 'always':
-            return 'Every chat in this repository must start by running `kgraph "<topic>"` before answering or exploring files. Infer the topic from the user\'s message; no exceptions, including simple or conversational requests.';
+            return `Every chat in this repository must start by running \`kgraph "<topic>"\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. ${useResultBoundary}`;
         case 'manual':
             return 'Do not run KGraph automatically. Run `kgraph "<topic>"` only when the user explicitly asks for KGraph context or invokes the KGraph command.';
         case 'off':
             return 'KGraph is disabled for this integration.';
         case 'smart':
         default:
-            return 'For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run `kgraph "<topic>"` before broad repository exploration. Infer the topic from the user\'s message. Skip KGraph for simple conversational requests that do not depend on repo knowledge.';
+            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`kgraph "<topic>"\` before broad repository exploration. Infer the topic from the user's message. Skip KGraph for simple conversational requests that do not depend on repo knowledge. ${useResultBoundary}`;
     }
 }
 export function renderCapturePolicy() {

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 = 'smart') {
+export async function addIntegrations(workspace, names, mode = 'always') {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];

package/dist/integrations/workflow-steps.js

@@ -4,12 +4,14 @@
  */
 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 REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/noisy atom refs need fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.`;
 const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks duplicated, noisy, or stale. Run \`kgraph compact\` only when the user asks to merge/archive cognition.`;
 const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.`;
 const KNOWLEDGE_STEP = `Run \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\` when the user asks what KGraph remembers or atom provenance/lifecycle matters.`;
 const PACK_STEP = `Run \`kgraph pack "<task>" --budget 8000 --json\` when an agent needs a machine-readable, token-budgeted context pack instead of human Markdown context.`;
 const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
+const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files. Use \`rg --files\` and quoted paths when a path must be located.`;
+const VERIFY_EDIT_STEP = `After editing, verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.`;
 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} --conclude --topic "<topic>"\` when durable session memory is useful`;
     return qualifier ? `${base} ${qualifier}.` : `${base}.`;
@@ -22,19 +24,21 @@ 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. ${PACK_STEP}
-5. ${KNOWLEDGE_STEP}
-6. ${DOCTOR_STEP}
-7. ${STALE_STEP}
-8. ${sessionStep(agentName, options.sessionQualifier)}
-9. ${IMPACT_STEP}
+4. ${EXPLORATION_BOUNDARY_STEP}
+5. ${VERIFY_EDIT_STEP}
+6. ${PACK_STEP}
+7. ${KNOWLEDGE_STEP}
+8. ${DOCTOR_STEP}
+9. ${STALE_STEP}
+10. ${sessionStep(agentName, options.sessionQualifier)}
+11. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-10. ${REPAIR_STEP}
-11. ${COMPACT_STEP}
-12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-13. ${HISTORY_STEP}`;
+12. ${REPAIR_STEP}
+13. ${COMPACT_STEP}
+14. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+15. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -42,6 +46,8 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${EXPLORATION_BOUNDARY_STEP}
+- ${VERIFY_EDIT_STEP}
 - ${PACK_STEP}
 - ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}

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

@@ -1,4 +1,4 @@
-import type { CognitionNote } from '../types/cognition.js';
+import type { KnowledgeAtom } from '../types/knowledge.js';
 import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from '../types/maps.js';
 export interface CytoscapeElement {
     data: Record<string, unknown>;
@@ -9,9 +9,12 @@ export interface GraphData {
     meta: {
         fileCount: number;
         symbolCount: number;
+        atomCount: number;
+        hiddenAtomCount: number;
+        /** @deprecated Kept for older tests/consumers that still read cognitionCount. */
         cognitionCount: number;
         tokenEstimate: number;
         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, knowledgeAtoms: KnowledgeAtom[]): GraphData;

package/dist/visualization/graph-builder.js

@@ -8,10 +8,10 @@ const LANGUAGE_COLORS = {
     html: '#f97316',
 };
 const STATUS_COLORS = {
-    current: '#10b981',
-    mixed: '#f59e0b',
+    active: '#10b981',
+    'needs-review': '#f59e0b',
     stale: '#ef4444',
-    unresolved: '#6b7280',
+    archived: '#6b7280',
 };
 const SYMBOL_COLORS = {
     function: '#22c55e',
@@ -20,7 +20,8 @@ const SYMBOL_COLORS = {
     export: '#f97316',
     import: '#64748b',
 };
-export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, cognitionNotes) {
+const MAX_ATOM_NODES = 250;
+export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, knowledgeAtoms) {
     const elements = [];
     const edgeIds = new Set();
     const nodeIds = new Set();
@@ -59,22 +60,30 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, c
             classes: `symbol ${symbol.kind}`,
         });
     }
-    for (const note of cognitionNotes) {
-        const id = `cognition-${note.id}`;
+    const atomsForGraph = selectAtomsForGraph(knowledgeAtoms);
+    for (const atom of atomsForGraph) {
+        const id = `atom-${atom.id}`;
         elements.push({
             data: {
                 id,
-                label: note.title,
-                color: STATUS_COLORS[note.referencesStatus] ?? STATUS_COLORS.unresolved,
-                type: 'cognition',
-                referencesStatus: note.referencesStatus,
-                domain: note.domain ?? '',
-                relatedFiles: note.relatedFiles,
-                relatedSymbols: note.relatedSymbols,
+                label: atom.topic,
+                color: STATUS_COLORS[atom.status] ?? STATUS_COLORS.archived,
+                type: 'atom',
+                atomId: atom.id,
+                atomType: atom.type,
+                confidence: atom.confidence,
+                status: atom.status,
+                sourceCommand: atom.provenance.sourceCommand,
+                domain: atom.scopeRefs.domains[0] ?? '',
+                relatedFiles: atom.scopeRefs.files,
+                relatedSymbols: atom.scopeRefs.symbols,
+                supersededBy: atom.lifecycle.supersededBy ?? '',
+                supersedes: atom.lifecycle.supersedes,
+                invalidatedBy: atom.lifecycle.invalidatedBy ?? [],
             },
-            classes: `cognition ${note.referencesStatus}`,
+            classes: `atom ${atom.status}`,
         });
-        for (const filePath of note.relatedFiles) {
+        for (const filePath of atom.scopeRefs.files) {
             const target = fileMap.files.find((f) => f.path === filePath);
             if (target) {
                 const edgeId = `${id}-ref-${target.id}`;
@@ -85,10 +94,10 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, c
                             id: edgeId,
                             source: id,
                             target: target.id,
-                            type: 'cognition-ref',
+                            type: 'atom-ref',
                             label: '',
                         },
-                        classes: 'cognition-ref',
+                        classes: 'atom-ref',
                     });
                 }
             }
@@ -142,12 +151,28 @@ export function buildGraph(fileMap, symbolMap, dependencyMap, relationshipMap, c
         meta: {
             fileCount: fileMap.files.length,
             symbolCount: symbolMap.symbols.length,
-            cognitionCount: cognitionNotes.length,
+            atomCount: knowledgeAtoms.filter((atom) => atom.status !== 'archived').length,
+            hiddenAtomCount: Math.max(0, knowledgeAtoms.filter((atom) => atom.status !== 'archived').length -
+                atomsForGraph.length),
+            cognitionCount: knowledgeAtoms.filter((atom) => atom.status !== 'archived').length,
             tokenEstimate,
             generatedAt: new Date().toISOString(),
         },
     };
 }
+function selectAtomsForGraph(atoms) {
+    return atoms
+        .filter((atom) => atom.status !== 'archived')
+        .sort((left, right) => atomGraphScore(right) - atomGraphScore(left))
+        .slice(0, MAX_ATOM_NODES);
+}
+function atomGraphScore(atom) {
+    const statusScore = atom.status === 'active' ? 6 : atom.status === 'needs-review' ? 4 : 2;
+    const confidenceScore = atom.confidence === 'high' ? 3 : atom.confidence === 'medium' ? 2 : 0;
+    const evidenceScore = Math.min(4, atom.scopeRefs.files.length + atom.scopeRefs.symbols.length);
+    const typeScore = atom.type === 'decision' || atom.type === 'gotcha' ? 1 : 0;
+    return statusScore + confidenceScore + evidenceScore + typeScore;
+}
 function getTokenBucket(tokenEstimate) {
     const tokens = tokenEstimate ?? 0;
     if (tokens >= 1000)

package/dist/visualization/html-template.js

@@ -51,10 +51,10 @@ select:hover,button:hover{background:#475569}
 <body>
 <div id="toolbar">
   <span id="t-title">\u29e1 KGraph \u00b7 ${repoName}</span>
-  <span id="t-stats">${meta.fileCount} files &middot; ${meta.symbolCount} symbols &middot; ${meta.cognitionCount} notes &middot; ~${meta.tokenEstimate} tokens</span>
+  <span id="t-stats">${meta.fileCount} files &middot; ${meta.symbolCount} symbols &middot; ${meta.atomCount} atoms${meta.hiddenAtomCount ? ' (' + meta.hiddenAtomCount + ' hidden)' : ''} &middot; ~${meta.tokenEstimate} tokens</span>
   <div id="t-controls">
     <label class="clabel"><input type="checkbox" id="tog-lbl" checked> Labels</label>
-    <label class="clabel"><input type="checkbox" id="tog-cog" checked> Cognition</label>
+    <label class="clabel"><input type="checkbox" id="tog-cog" checked> Memory</label>
     <select id="sel-layout" title="Graph layout algorithm">
       <option value="dagre">Hierarchical</option>
       <option value="cose">Force-directed</option>
@@ -85,9 +85,9 @@ select:hover,button:hover{background:#475569}
   <span class="li"><span class="li-dot" style="background:#475569"></span>200+ tok</span>
   <span class="li"><span class="li-dot" style="background:#ef4444"></span>1000+ tok</span>
   <span class="li-sep"></span>
-  <span class="li-head">Cognition</span>
-  <span class="li"><span class="li-dia" style="background:#10b981"></span>Current</span>
-  <span class="li"><span class="li-dia" style="background:#f59e0b"></span>Mixed</span>
+  <span class="li-head">Atoms</span>
+  <span class="li"><span class="li-dia" style="background:#10b981"></span>Active</span>
+  <span class="li"><span class="li-dia" style="background:#f59e0b"></span>Review</span>
   <span class="li"><span class="li-dia" style="background:#ef4444"></span>Stale</span>
   <span class="li-sep"></span>
   <span class="li" style="margin-left:auto;color:#334155;font-size:10px">KGraph v${meta.generatedAt.slice(0, 10)}</span>
@@ -166,7 +166,7 @@ select:hover,button:hover{background:#475569}
         }
       },
       {
-        selector: 'node.cognition',
+        selector: 'node.atom',
         style: {
           shape: 'diamond',
           width: 40,
@@ -212,7 +212,7 @@ select:hover,button:hover{background:#475569}
         }
       },
       {
-        selector: 'edge.cognition-ref',
+        selector: 'edge.atom-ref',
         style: {
           width: 1.5,
           'line-color': '#7dd3fc',
@@ -267,25 +267,32 @@ select:hover,button:hover{background:#475569}
       symHtml;
   }
 
-  function renderCognitionPanel(d) {
-    var sc = { current: '#10b981', mixed: '#f59e0b', stale: '#ef4444', unresolved: '#6b7280' }[d.referencesStatus] || '#6b7280';
+  function renderAtomPanel(d) {
+    var sc = { active: '#10b981', 'needs-review': '#f59e0b', stale: '#ef4444', archived: '#6b7280' }[d.status] || '#6b7280';
     var files = d.relatedFiles && d.relatedFiles.length
       ? '<ul class="sb-list">' + d.relatedFiles.map(function (f) { return '<li>' + esc(f) + '</li>'; }).join('') + '</ul>'
       : '<span class="sb-val">none</span>';
     var syms = d.relatedSymbols && d.relatedSymbols.length
       ? d.relatedSymbols.slice(0, 15).map(function (s) { return '<span class="sb-code">' + esc(s) + '</span>'; }).join(' ')
       : '<span class="sb-val">none</span>';
-    return '<div class="sb-badge" style="background:' + sc + '22;color:' + sc + ';border:1px solid ' + sc + '44">' + esc(d.referencesStatus) + '</div>' +
+    var invalidated = d.invalidatedBy && d.invalidatedBy.length
+      ? '<div class="sb-sect"><div class="sb-lbl">Invalidated By</div><ul class="sb-list">' + d.invalidatedBy.map(function (r) { return '<li>' + esc(r) + '</li>'; }).join('') + '</ul></div>'
+      : '';
+    return '<div class="sb-badge" style="background:' + sc + '22;color:' + sc + ';border:1px solid ' + sc + '44">' + esc(d.status) + '</div>' +
       '<div class="sb-title">' + esc(d.label) + '</div>' +
+      '<div class="sb-sect"><div class="sb-lbl">Atom</div><div class="sb-val"><span class="sb-code">' + esc(d.atomId) + '</span></div></div>' +
+      '<div class="sb-sect"><div class="sb-lbl">Type / Confidence</div><div class="sb-val">' + esc(d.atomType) + ' / ' + esc(d.confidence) + '</div></div>' +
+      '<div class="sb-sect"><div class="sb-lbl">Source</div><div class="sb-val">' + esc(d.sourceCommand) + '</div></div>' +
       (d.domain ? '<div class="sb-sect"><div class="sb-lbl">Domain</div><div class="sb-val">' + esc(d.domain) + '</div></div>' : '') +
       '<div class="sb-sect"><div class="sb-lbl">Related Files</div>' + files + '</div>' +
-      '<div class="sb-sect"><div class="sb-lbl">Symbols</div><div class="sb-val">' + syms + '</div></div>';
+      '<div class="sb-sect"><div class="sb-lbl">Symbols</div><div class="sb-val">' + syms + '</div></div>' +
+      invalidated;
   }
 
   cy.on('tap', 'node', function (evt) {
     var d = evt.target.data();
-    document.getElementById('sb-type').textContent = d.type === 'cognition' ? 'Cognition Note' : 'File';
-    document.getElementById('sb-body').innerHTML = d.type === 'cognition' ? renderCognitionPanel(d) : renderFilePanel(d);
+    document.getElementById('sb-type').textContent = d.type === 'atom' ? 'Knowledge Atom' : 'File';
+    document.getElementById('sb-body').innerHTML = d.type === 'atom' ? renderAtomPanel(d) : renderFilePanel(d);
     document.getElementById('sidebar').classList.add('open');
   });
 
@@ -305,11 +312,11 @@ select:hover,button:hover{background:#475569}
 
   document.getElementById('tog-cog').addEventListener('change', function (e) {
     if (e.target.checked) {
-      cy.nodes('.cognition').removeClass('hidden');
-      cy.edges('.cognition-ref').removeClass('hidden');
+      cy.nodes('.atom').removeClass('hidden');
+      cy.edges('.atom-ref').removeClass('hidden');
     } else {
-      cy.nodes('.cognition').addClass('hidden');
-      cy.edges('.cognition-ref').addClass('hidden');
+      cy.nodes('.atom').addClass('hidden');
+      cy.edges('.atom-ref').addClass('hidden');
     }
   });
 

package/package.json

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