@kentwynn/kgraph 0.2.10 → 0.2.12

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,14 +220,41 @@ 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.
+
+```bash
+kgraph knowledge list
+kgraph knowledge list --type finding --topic auth --json
+kgraph knowledge get <atom-id>
+kgraph knowledge archive <atom-id>
+kgraph knowledge supersede <old-id> <new-id>
+```
+
+Inspect and manage canonical knowledge atoms. Archive and supersede update lifecycle metadata; they do not delete history.
+
+```bash
+kgraph stale
+kgraph stale --json
+kgraph blame <atom-id>
+```
+
+Refresh atom lifecycle status against the current scan and inspect atom provenance. Changed file hashes move atoms to `needs-review`; deleted files or missing symbols move atoms to `stale`; `blame` shows the source command, agent/session/commit, evidence refs, and lifecycle links.
+
+```bash
+kgraph pack "auth token refresh" --budget 8000
+kgraph pack "auth token refresh" --budget 8000 --json
+```
+
+Build a budget-aware context pack from files, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents.
 
 ```bash
 kgraph compact --dry-run
 kgraph compact
 ```
 
-Merge duplicate cognition records and archive low-confidence stale entries. Compaction keeps memory inspectable under `.kgraph/cognition/` while reducing low-value noise in future context responses.
+Merge duplicate knowledge atoms and archive low-confidence stale entries. Compaction operates on `.kgraph/knowledge/atoms.jsonl` first, then regenerates indexes and compatibility domain records so future context responses use the atom lifecycle as the source of truth.
 
 ## Optional Step Commands
 
@@ -246,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`.
 
@@ -256,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
@@ -273,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
 
@@ -327,10 +354,14 @@ All runtime data lives under `.kgraph/`:
 ├── domains/
 ├── interactions/processed/
 ├── sessions/
+├── knowledge/
+│   ├── atoms.jsonl
+│   ├── schema.json
+│   └── indexes/
 └── context/
 ```
 
-The files are local, inspectable, and human-readable. Core KGraph functionality is free. There is no database, telemetry, cloud service, account, API key, embedding service, model provider, or source-code upload.
+The files are local, inspectable, and human-readable. `knowledge/atoms.jsonl` is the canonical durable-memory store; Markdown cognition remains a compatibility and input layer. Core KGraph functionality is free. There is no database, telemetry, cloud service, account, API key, embedding service, model provider, or source-code upload.
 
 ## Language Support
 
@@ -352,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
 
@@ -434,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/blame.d.ts

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

package/dist/cli/commands/blame.js

@@ -0,0 +1,52 @@
+import { readKnowledgeAtoms } from '../../knowledge/atom-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerBlameCommand(program) {
+    program
+        .command('blame <atomId>')
+        .description('Show who or what created a knowledge atom and why it exists')
+        .option('--json', 'Print JSON output')
+        .action((atomId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const atom = (await readKnowledgeAtoms(workspace)).find((candidate) => candidate.id === atomId);
+        if (!atom)
+            throw new KGraphError(`Knowledge atom not found: ${atomId}`);
+        const result = {
+            id: atom.id,
+            topic: atom.topic,
+            claim: atom.claim,
+            provenance: atom.provenance,
+            evidenceRefs: atom.evidenceRefs,
+            lifecycle: atom.lifecycle,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`# ${atom.topic}`);
+        console.log('');
+        console.log(`ID: ${atom.id}`);
+        console.log(`Claim: ${atom.claim}`);
+        console.log(`Source: ${atom.provenance.sourceCommand}`);
+        if (atom.provenance.agent)
+            console.log(`Agent: ${atom.provenance.agent}`);
+        if (atom.provenance.sessionId) {
+            console.log(`Session: ${atom.provenance.sessionId}`);
+        }
+        if (atom.provenance.commit)
+            console.log(`Commit: ${atom.provenance.commit}`);
+        console.log(`Created: ${atom.provenance.createdAt}`);
+        if (atom.provenance.updatedAt)
+            console.log(`Updated: ${atom.provenance.updatedAt}`);
+        console.log('');
+        console.log('Evidence:');
+        for (const ref of atom.evidenceRefs) {
+            console.log(`- ${JSON.stringify(ref)}`);
+        }
+        if (atom.lifecycle.supersededBy || atom.lifecycle.supersedes.length > 0) {
+            console.log('');
+            console.log('Lifecycle:');
+            console.log(JSON.stringify(atom.lifecycle, null, 2));
+        }
+    }));
+}

package/dist/cli/commands/doctor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { analyzeCognitionQuality, } from '../../cognition/cognition-quality.js';
 import { loadConfig } from '../../config/config.js';
 import { listIntegrations } from '../../integrations/integration-store.js';
+import { validateKnowledgeStore } from '../../knowledge/atom-store.js';
 import { getCurrentCommit, isGitRepo } from '../../scanner/git-utils.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { mapPaths, mapsExist, readMaps } from '../../storage/map-store.js';
@@ -76,6 +77,22 @@ export function registerDoctorCommand(program) {
                 detail: missing.join(', '),
             });
         }
+        const knowledgeIssues = await validateKnowledgeStore(workspace, maps
+            ? { fileMap: maps.fileMap, symbolMap: maps.symbolMap }
+            : undefined);
+        checks.push({
+            label: 'knowledge',
+            ok: knowledgeIssues.length === 0,
+            detail: knowledgeIssues.length === 0
+                ? 'knowledge atoms, schema, and refs are valid'
+                : knowledgeIssues
+                    .slice(0, 3)
+                    .map((issue) => issue.message)
+                    .join('; ') +
+                    (knowledgeIssues.length > 3
+                        ? `; and ${knowledgeIssues.length - 3} more`
+                        : ''),
+        });
         const inboxCount = await countMarkdownFiles(workspace.inboxPath);
         checks.push({
             label: 'inbox',
@@ -97,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);
@@ -112,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('');
@@ -139,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}`);
@@ -170,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

@@ -1,6 +1,7 @@
 import { loadConfig, writeDefaultConfig } from '../../config/config.js';
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations } from '../../integrations/integration-store.js';
+import { ensureKnowledgeStore } from '../../knowledge/atom-store.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
 import { ensureWorkspace } from '../../storage/kgraph-paths.js';
 import { readMaps, writeMaps } from '../../storage/map-store.js';
@@ -17,6 +18,7 @@ export function registerInitCommand(program) {
         .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'smart')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
+        await ensureKnowledgeStore(workspace);
         const wroteConfig = await writeDefaultConfig(workspace);
         console.log(wroteConfig
             ? 'Initialized .kgraph workspace.'

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

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

package/dist/cli/commands/knowledge.js

@@ -0,0 +1,137 @@
+import { readKnowledgeAtoms, updateKnowledgeAtom, } from '../../knowledge/atom-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerKnowledgeCommand(program) {
+    const knowledge = program
+        .command('knowledge')
+        .description('Manage canonical KGraph knowledge atoms');
+    knowledge
+        .command('list')
+        .option('--type <type>', 'Filter by atom type')
+        .option('--topic <topic>', 'Filter by topic substring')
+        .option('--status <status>', 'Filter by active, stale, needs-review, or archived')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const atoms = filterAtoms(await readKnowledgeAtoms(workspace), options);
+        if (options.json) {
+            console.log(JSON.stringify(atoms, null, 2));
+            return;
+        }
+        console.log('KGraph Knowledge');
+        console.log('');
+        for (const atom of atoms) {
+            console.log(`- ${atom.id} [${atom.type}, ${atom.confidence}, ${atom.status}] ${atom.topic}`);
+            console.log(`  ${atom.claim}`);
+        }
+        if (atoms.length === 0)
+            console.log('- None');
+    }));
+    knowledge
+        .command('get <atomId>')
+        .option('--json', 'Print JSON output')
+        .action((atomId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const atom = await requireAtom(workspace, atomId);
+        if (options.json) {
+            console.log(JSON.stringify(atom, null, 2));
+            return;
+        }
+        console.log(`# ${atom.topic}`);
+        console.log('');
+        console.log(`ID: ${atom.id}`);
+        console.log(`Type: ${atom.type}`);
+        console.log(`Confidence: ${atom.confidence}`);
+        console.log(`Status: ${atom.status}`);
+        console.log(`Claim: ${atom.claim}`);
+        if (atom.summary)
+            console.log(`Summary: ${atom.summary}`);
+        console.log('');
+        console.log('Evidence:');
+        for (const ref of atom.evidenceRefs) {
+            console.log(`- ${JSON.stringify(ref)}`);
+        }
+        console.log('');
+        console.log('Provenance:');
+        console.log(JSON.stringify(atom.provenance, null, 2));
+        console.log('');
+        console.log('Lifecycle:');
+        console.log(JSON.stringify(atom.lifecycle, null, 2));
+    }));
+    knowledge
+        .command('archive <atomId>')
+        .option('--json', 'Print JSON output')
+        .action((atomId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const now = new Date().toISOString();
+        const atom = await updateKnowledgeAtom(workspace, atomId, (current) => ({
+            ...current,
+            status: 'archived',
+            provenance: { ...current.provenance, updatedAt: now },
+            lifecycle: { ...current.lifecycle, archivedAt: now },
+        }));
+        console.log(options.json
+            ? JSON.stringify(atom, null, 2)
+            : `Archived knowledge atom: ${atom.id}`);
+    }));
+    knowledge
+        .command('supersede <oldId> <newId>')
+        .option('--json', 'Print JSON output')
+        .action((oldId, newId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        await requireAtom(workspace, newId);
+        const now = new Date().toISOString();
+        const oldAtom = await updateKnowledgeAtom(workspace, oldId, (current) => ({
+            ...current,
+            status: 'archived',
+            provenance: { ...current.provenance, updatedAt: now },
+            lifecycle: {
+                ...current.lifecycle,
+                supersededBy: newId,
+                archivedAt: now,
+            },
+        }));
+        const newAtom = await updateKnowledgeAtom(workspace, newId, (current) => ({
+            ...current,
+            provenance: { ...current.provenance, updatedAt: now },
+            lifecycle: {
+                ...current.lifecycle,
+                supersedes: [...new Set([...current.lifecycle.supersedes, oldId])],
+            },
+        }));
+        const result = { old: oldAtom, new: newAtom };
+        console.log(options.json
+            ? JSON.stringify(result, null, 2)
+            : `Superseded ${oldId} with ${newId}`);
+    }));
+}
+async function requireAtom(workspace, atomId) {
+    const atom = (await readKnowledgeAtoms(workspace)).find((candidate) => candidate.id === atomId);
+    if (!atom)
+        throw new KGraphError(`Knowledge atom not found: ${atomId}`);
+    return atom;
+}
+function filterAtoms(atoms, options) {
+    return atoms.filter((atom) => {
+        if (options.type && atom.type !== options.type)
+            return false;
+        if (options.status &&
+            atom.status !== normalizeStatus(options.status)) {
+            return false;
+        }
+        if (options.topic &&
+            !atom.topic.toLowerCase().includes(options.topic.toLowerCase())) {
+            return false;
+        }
+        return true;
+    });
+}
+function normalizeStatus(value) {
+    if (value === 'active' ||
+        value === 'stale' ||
+        value === 'needs-review' ||
+        value === 'archived') {
+        return value;
+    }
+    throw new KGraphError('--status must be active, stale, needs-review, or archived.');
+}

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

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

package/dist/cli/commands/pack.js

@@ -0,0 +1,49 @@
+import { buildContextPack } from '../../context/context-pack.js';
+import { queryContext } from '../../context/context-query.js';
+import { loadConfig } from '../../config/config.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerPackCommand(program) {
+    program
+        .command('pack <task>')
+        .description('Build a budget-aware KGraph context pack for a task')
+        .option('--budget <tokens>', 'Maximum estimated tokens to include', '8000')
+        .option('--json', 'Print JSON output')
+        .action((task, options) => runCommand(async () => {
+        if (!task.trim())
+            throw new KGraphError('Task cannot be empty.');
+        const budget = Number.parseInt(options.budget ?? '8000', 10);
+        if (!Number.isFinite(budget) || budget < 1) {
+            throw new KGraphError('--budget must be a positive integer.');
+        }
+        const workspace = await assertWorkspace(process.cwd());
+        if (!(await mapsExist(workspace))) {
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+        }
+        const [config, maps] = await Promise.all([
+            loadConfig(workspace),
+            readMaps(workspace),
+        ]);
+        const response = await queryContext(workspace, config, maps, task);
+        const pack = buildContextPack(response, budget);
+        if (options.json) {
+            console.log(JSON.stringify(pack, null, 2));
+            return;
+        }
+        console.log(`# KGraph Context Pack`);
+        console.log('');
+        console.log(`Task: ${pack.task}`);
+        console.log(`Budget: ${pack.budget}`);
+        console.log(`Used: ${pack.usedTokens}`);
+        console.log('');
+        for (const item of pack.items) {
+            console.log(`- [${item.kind}] ${item.title} (~${item.tokenEstimate} tokens)`);
+            console.log(`  because ${item.reasons.slice(0, 3).join('; ')}`);
+        }
+        if (pack.omitted.length > 0) {
+            console.log('');
+            console.log(`Omitted: ${pack.omitted.length} item(s) over budget`);
+        }
+    }));
+}