@kentwynn/kgraph 0.2.24 → 0.2.27

package/README.md

@@ -168,12 +168,12 @@ Normal agent flow is intentionally small:
 ```bash
 kgraph "topic"
 # work normally
-kgraph "topic" --final
+kgraph "topic" --final --agent codex
 # if final check requires capture:
-kgraph "topic" --capture "durable conclusion" --capture-file path/to/file.ts --capture-symbol SymbolName
+kgraph "topic" --capture "durable conclusion" --capture-file path/to/file.ts --capture-symbol SymbolName --agent codex
 ```
 
-`kgraph "<topic>"` is the smart root workflow: it refreshes maps, processes capture notes, reports memory health, and returns focused context. Agents can still use `kgraph pack "<topic>" --budget 8000 --json` when they need the stable machine-readable `ContextPack` contract with atoms, source ranges, git changes, omitted items, token estimates, and inclusion reasons.
+`kgraph "<topic>"` is the smart root workflow: it refreshes maps, processes capture notes, reports memory health, and returns focused context. Agents can pass `--agent <name>` to record a lightweight session context event. Agents can still use `kgraph pack "<topic>" --budget 8000 --json --agent <name>` when they need the stable machine-readable `ContextPack` contract with atoms, source ranges, git changes, omitted items, token estimates, and inclusion reasons.
 
 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.
 
@@ -187,7 +187,7 @@ kgraph session end --agent codex --conclude --topic "auth session work"
 kgraph session
 ```
 
-This is optional. Claude Code can use generated hook scripts for automatic capture; other agents use the same commands through their managed instructions, rules, or prompts.
+This is optional for manual read/write tracking. Generated `always` and `smart` workflows use `--agent <name>` on `kgraph pack` and root/final commands to record lightweight session context automatically; Claude Code can also use generated hook scripts for file read/write capture.
 
 ## Main Commands
 
@@ -307,9 +307,10 @@ Refresh atom lifecycle status against the current scan and inspect atom provenan
 ```bash
 kgraph pack "auth token refresh" --budget 8000
 kgraph pack "auth token refresh" --budget 8000 --json
+kgraph pack "auth token refresh" --budget 8000 --json --agent codex
 ```
 
-Build a budget-aware context pack from files, source ranges, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents; text output is an Atom Core briefing for humans.
+Build a budget-aware context pack from files, source ranges, symbols, relationships, git changes, session history, and knowledge atoms. Add `--agent <name>` to record a lightweight automatic session context event. JSON output is the stable machine-readable contract for agents; text output is an Atom Core briefing for humans.
 
 ```bash
 kgraph compact --dry-run

package/dist/cli/commands/pack.js

@@ -1,6 +1,7 @@
 import { buildContextPack } from '../../context/context-pack.js';
 import { queryContext } from '../../context/context-query.js';
 import { loadConfig } from '../../config/config.js';
+import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
@@ -10,7 +11,8 @@ export function registerPackCommand(program) {
         .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 () => {
+        .option('--agent <name>', 'Record an automatic KGraph session context event for this integration agent')
+        .action((task, options, command) => runCommand(async () => {
         if (!task.trim())
             throw new KGraphError('Task cannot be empty.');
         const budget = Number.parseInt(options.budget ?? '8000', 10);
@@ -21,6 +23,16 @@ export function registerPackCommand(program) {
         if (!(await mapsExist(workspace))) {
             throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
+        const agent = options.agent ??
+            command.getOptionValue('agent') ??
+            findCommandOption(command, 'agent');
+        if (agent) {
+            await recordSessionEvent(workspace, {
+                agent: assertSessionAgent(agent),
+                type: 'context',
+                captureSource: 'automatic',
+            });
+        }
         const [config, maps] = await Promise.all([
             loadConfig(workspace),
             readMaps(workspace),
@@ -34,6 +46,18 @@ export function registerPackCommand(program) {
         console.log(renderPackText(pack));
     }));
 }
+function findCommandOption(command, name) {
+    let current = command?.parent;
+    while (current) {
+        const value = current.getOptionValue(name) ??
+            current.opts()[name];
+        if (value) {
+            return value;
+        }
+        current = current.parent;
+    }
+    return undefined;
+}
 export function renderPackText(pack) {
     const lines = [
         `KGraph Pack · ${pack.task}`,

package/dist/cli/commands/session.js

@@ -17,12 +17,12 @@ export function registerSessionCommand(program) {
     }));
     session
         .command('start')
-        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--agent <name>', 'KGraph integration agent name')
         .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
-        .action((options) => runCommand(async () => {
+        .action((options, command) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const event = await recordSessionEvent(workspace, {
-            agent: requireAgent(options.agent),
+            agent: requireAgent(options, command),
             type: 'start',
             captureSource: normalizeSource(options.source),
         });
@@ -30,13 +30,13 @@ export function registerSessionCommand(program) {
     }));
     session
         .command('read <path>')
-        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--agent <name>', 'KGraph integration agent name')
         .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
-        .action((filePath, options) => runCommand(async () => {
+        .action((filePath, options, command) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const maps = await readMaps(workspace);
         const event = await recordSessionEvent(workspace, {
-            agent: requireAgent(options.agent),
+            agent: requireAgent(options, command),
             type: 'read',
             path: filePath,
             captureSource: normalizeSource(options.source),
@@ -46,13 +46,13 @@ export function registerSessionCommand(program) {
     }));
     session
         .command('write <path>')
-        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--agent <name>', 'KGraph integration agent name')
         .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
-        .action((filePath, options) => runCommand(async () => {
+        .action((filePath, options, command) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const maps = await readMaps(workspace);
         const event = await recordSessionEvent(workspace, {
-            agent: requireAgent(options.agent),
+            agent: requireAgent(options, command),
             type: 'write',
             path: filePath,
             captureSource: normalizeSource(options.source),
@@ -62,26 +62,27 @@ export function registerSessionCommand(program) {
     }));
     session
         .command('end')
-        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--agent <name>', 'KGraph integration agent name')
         .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
         .option('--conclude', 'Store a durable typed summary for this session')
         .option('--topic <topic>', 'Conclusion topic when using --conclude')
         .option('--type <type>', 'finding, decision, gotcha, summary, or relationship', 'summary')
         .option('--confidence <level>', 'high, medium, or low', 'medium')
         .option('--note <text>', 'Concise durable conclusion text')
-        .action((options) => runCommand(async () => {
+        .action((options, command) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
+        const agent = requireAgent(options, command);
         let pendingConclusion;
         if (options.conclude) {
-            pendingConclusion = await buildActiveSessionConclusion(workspace, requireAgent(options.agent), {
-                topic: options.topic ?? `${options.agent} session summary`,
+            pendingConclusion = await buildActiveSessionConclusion(workspace, agent, {
+                topic: options.topic ?? `${agent} session summary`,
                 body: options.note,
                 kind: normalizeKind(options.type),
                 confidence: normalizeConfidence(options.confidence),
             });
         }
         const event = await recordSessionEvent(workspace, {
-            agent: requireAgent(options.agent),
+            agent,
             type: 'end',
             captureSource: normalizeSource(options.source),
         });
@@ -121,12 +122,27 @@ export function renderSessionReport(report) {
     lines.push(...sessionNextActions(report));
     return lines.join('\n');
 }
-function requireAgent(value) {
+function requireAgent(options, command) {
+    const value = options.agent ??
+        command?.getOptionValue('agent') ??
+        findCommandOption(command, 'agent');
     if (!value) {
         throw new KGraphError('--agent is required.');
     }
     return assertSessionAgent(value);
 }
+function findCommandOption(command, name) {
+    let current = command?.parent;
+    while (current) {
+        const value = current.getOptionValue(name) ??
+            current.opts()[name];
+        if (value) {
+            return value;
+        }
+        current = current.parent;
+    }
+    return undefined;
+}
 function normalizeSource(value) {
     if (value === 'automatic' || value === 'agent-reported' || value === 'manual') {
         return value;

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

@@ -7,5 +7,6 @@ export interface DefaultWorkflowOptions {
     tags?: string[];
     files?: string[];
     symbols?: string[];
+    agent?: string;
 }
 export declare function runDefaultWorkflow(query?: string, options?: DefaultWorkflowOptions): Promise<void>;

package/dist/cli/commands/workflow.js

@@ -6,6 +6,7 @@ import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
 import { getWorkingTreeChanges } from '../../scanner/git-utils.js';
 import { shouldExclude } from '../../scanner/file-classifier.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
+import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
 import { listInboxNotes } from '../../storage/cognition-store.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { readMaps, writeMaps } from '../../storage/map-store.js';
@@ -23,6 +24,16 @@ export async function runDefaultWorkflow(query, options = {}) {
         }
         const workspace = await assertWorkspace(process.cwd());
         const config = await loadConfig(workspace);
+        const sessionAgent = options.agent
+            ? assertSessionAgent(options.agent)
+            : undefined;
+        if (sessionAgent) {
+            await recordSessionEvent(workspace, {
+                agent: sessionAgent,
+                type: 'context',
+                captureSource: 'automatic',
+            });
+        }
         const previousMaps = await readMaps(workspace);
         const scan = await scanRepository(workspace.rootPath, config, {
             files: previousMaps.fileMap.files,

package/dist/cli/help.js

@@ -37,6 +37,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         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('pack "auth task" --agent codex', 'Record lightweight agent session context while building a 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'),
@@ -66,6 +67,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('--capture <text>', 'Store a durable conclusion in the root workflow'),
         command('--capture-file <path>', 'Attach file evidence to root capture'),
         command('--capture-symbol <name>', 'Attach symbol evidence to root capture'),
+        command('--agent <name>', 'Record lightweight agent session context'),
         '',
         sectionTitle(theme, `${accent} Examples`),
         '  kgraph init',

package/dist/cli/index.js

@@ -39,6 +39,7 @@ export function createProgram() {
         .option('--capture-tag <tag>', 'Capture tag; repeatable', collect, [])
         .option('--capture-file <path>', 'Capture related repo file; repeatable', collect, [])
         .option('--capture-symbol <name>', 'Capture related symbol; repeatable', collect, [])
+        .option('--agent <name>', 'Record an automatic KGraph session context event for this integration agent')
         .version(version)
         .helpOption(false)
         .action(async (topicParts = [], options) => {
@@ -51,6 +52,7 @@ export function createProgram() {
             tags: options.captureTag,
             files: options.captureFile,
             symbols: options.captureSymbol,
+            agent: options.agent,
         });
     });
     program.option('-h, --help', 'Show this help');

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

@@ -12,16 +12,16 @@ ${numberedWorkflow('claude-code', {
     commandFiles: [
         {
             path: '.claude/commands/kgraph.md',
-            content: `Use KGraph persistent repo intelligence through the single normal \`kgraph "<topic>"\` entry point.
+            content: `Use KGraph persistent repo intelligence through the single normal \`kgraph "<topic>" --agent claude-code\` entry point.
 
 1. Infer a concise topic from the user's request.
-2. Run exactly one command from the repository root: \`kgraph "<topic>"\`.
+2. Run exactly one command from the repository root: \`kgraph "<topic>" --agent claude-code\`.
 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, run \`kgraph "<topic>" --final\`. If KGraph reports capture-required, run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\`, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
+8. At the end of repository-file changes, run \`kgraph "<topic>" --final --agent claude-code\`. If KGraph reports capture-required, run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent claude-code\`, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
 `,
         },
         {
@@ -41,7 +41,7 @@ ${numberedWorkflow('claude-code', {
         },
         {
             path: '.claude/commands/kgraph-pack.md',
-            content: `Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+            content: `Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json --agent claude-code\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
 `,
         },
         {

package/dist/integrations/agent-skills.js

@@ -45,7 +45,7 @@ name: kgraph-pack
 description: Build a budget-aware KGraph context pack
 ---
 
-Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
 `,
     },
     {
@@ -181,6 +181,9 @@ Workflow:
 ${numberedWorkflow(agentName)}
 `,
         },
-        ...SHARED_AGENT_SKILLS,
+        ...SHARED_AGENT_SKILLS.map((file) => ({
+            ...file,
+            content: file.content.replaceAll('$AGENT', agentName),
+        })),
     ];
 }

package/dist/integrations/instruction-blocks.d.ts

@@ -3,6 +3,6 @@ export declare const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLIC
 export declare const KGRAPH_CAPTURE_POLICY_PLACEHOLDER = "{{KGRAPH_CAPTURE_POLICY}}";
 export declare function upsertManagedBlock(content: string, integrationName: string, instructions: string): string;
 export declare function removeManagedBlock(content: string, integrationName: string): string;
-export declare function applyContextPolicy(content: string, mode: IntegrationMode): string;
-export declare function renderContextPolicy(mode: IntegrationMode): string;
-export declare function renderCapturePolicy(): string;
+export declare function applyContextPolicy(content: string, mode: IntegrationMode, agentName?: string): string;
+export declare function renderContextPolicy(mode: IntegrationMode, agentName?: string): string;
+export declare function renderCapturePolicy(agentName?: string): string;

package/dist/integrations/instruction-blocks.js

@@ -30,36 +30,45 @@ function managedBlockPattern(integrationName) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-export function applyContextPolicy(content, mode) {
+export function applyContextPolicy(content, mode, agentName) {
     return content
-        .replaceAll(KGRAPH_CONTEXT_POLICY_PLACEHOLDER, renderContextPolicy(mode))
-        .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy());
+        .replaceAll(KGRAPH_CONTEXT_POLICY_PLACEHOLDER, renderContextPolicy(mode, agentName))
+        .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy(agentName));
 }
-export function renderContextPolicy(mode) {
+export function renderContextPolicy(mode, agentName) {
     const useResultBoundary = 'Use the returned KGraph ContextPack items as the first-pass source of truth. Prefer source ranges, atoms, git changes, and inclusion reasons from the pack before broad repository search. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file or range 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.';
+    const packCommand = agentName
+        ? `kgraph pack "<topic>" --budget 8000 --json --agent ${agentName}`
+        : 'kgraph pack "<topic>" --budget 8000 --json';
     switch (mode) {
         case 'always':
-            return `Every chat in this repository must start by running \`kgraph pack "<topic>" --budget 8000 --json\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
+            return `Every chat in this repository must start by running \`${packCommand}\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. This records a lightweight KGraph session context event for the agent. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
         case 'manual':
             return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack.';
         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 pack "<topic>" --budget 8000 --json\` 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. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
+            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`${packCommand}\` before broad repository exploration. Infer the topic from the user's message. This records a lightweight KGraph session context event only when KGraph is actually used. Skip KGraph for simple conversational requests that do not depend on repo knowledge. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
     }
 }
-export function renderCapturePolicy() {
+export function renderCapturePolicy(agentName) {
+    const finalCommand = agentName
+        ? `kgraph "<topic>" --final --agent ${agentName}`
+        : 'kgraph "<topic>" --final';
+    const captureCommand = agentName
+        ? `kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent ${agentName}`
+        : 'kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>';
     return `Capture policy:
-- At the end of any session that changed repository files, run \`kgraph "<topic>" --final\` before the final response so KGraph can enforce whether capture is required.
-- If final check reports capture-required, run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\` to store durable engineering memory, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
+- At the end of any session that changed repository files, run \`${finalCommand}\` before the final response so KGraph can enforce whether capture is required.
+- If final check reports capture-required, run \`${captureCommand}\` to store durable engineering memory, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
 - Low-level alternatives remain available: \`kgraph conclude "<topic>" --type <finding|decision|gotcha|summary|relationship> --confidence <high|medium|low>\` or \`kgraph session end --agent <agent> --conclude --topic "<topic>"\`.
 - Add evidence when storing cognition. High-confidence conclusions must include at least one \`--file <path>\` or \`--symbol <name>\`; medium-confidence conclusions should include evidence when possible.
 - Preserve only expensive-to-rediscover findings, decisions, gotchas, summaries, and relationships. Do not store raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
 - Use \`.kgraph/inbox/<slug>.md\` only when a longer structured note is clearer than a single \`kgraph conclude\` command.
 - A \`.kgraph/inbox/*.md\` note is KGraph runtime capture, not project documentation. It is allowed by this workflow unless the user explicitly says not to capture to KGraph.
 - Do not skip capture for meaningful UI text, button, link, route, styling, or small file edits. Skip capture only when no reusable repository knowledge was created.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\` or \`kgraph pack "<topic>" --budget 8000 --json\` for agent-readable context. If repo files changed, run \`kgraph "<topic>" --final\` once before the final answer.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph pack "<topic>" --budget 8000 --json${agentName ? ` --agent ${agentName}` : ''}\` for agent-readable context. If repo files changed, run \`${finalCommand}\` once before the final answer.
 - After the final \`kgraph\` run, mention whether durable cognition was stored or processed.
 
 When using an inbox note, use this structure:

package/dist/integrations/integration-store.js

@@ -34,11 +34,11 @@ export async function addIntegrations(workspace, names, mode = 'always') {
             await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
         }
         else {
-            await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
+            await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode, adapter.name));
             const deduped = (adapter.commandFiles ?? []).filter((file) => !writtenCommandFiles.has(file.path));
             await writeIntegrationCommandFiles(workspace.rootPath, deduped.map((file) => ({
                 ...file,
-                content: applyContextPolicy(file.content, mode),
+                content: applyContextPolicy(file.content, mode, adapter.name),
             })));
             for (const file of adapter.commandFiles ?? []) {
                 writtenCommandFiles.add(file.path);

package/dist/integrations/workflow-steps.js

@@ -8,8 +8,12 @@ const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/n
 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 = `Treat \`kgraph pack "<task>" --budget 8000 --json\` as the primary agent contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. Use human \`kgraph "<topic>"\` output only when the user explicitly wants a briefing.`;
-const SMART_ROOT_STEP = `Prefer the root workflow for normal agent work: run \`kgraph "<topic>"\` to refresh maps, process cognition, report memory health, and return context; run \`kgraph "<topic>" --final\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\` when the final check requires durable knowledge.`;
+function packStep(agentName) {
+    return `Treat \`kgraph pack "<task>" --budget 8000 --json --agent ${agentName}\` as the primary agent contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. Use human \`kgraph "<topic>" --agent ${agentName}\` output only when the user explicitly wants a briefing.`;
+}
+function smartRootStep(agentName) {
+    return `Prefer the root workflow for normal agent work: run \`kgraph "<topic>" --agent ${agentName}\` when a human-readable refresh/context briefing is needed; run \`kgraph "<topic>" --final --agent ${agentName}\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent ${agentName}\` when the final check requires durable knowledge.`;
+}
 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.`;
@@ -27,8 +31,8 @@ export function numberedWorkflow(agentName, options = {}) {
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
 4. ${EXPLORATION_BOUNDARY_STEP}
 5. ${VERIFY_EDIT_STEP}
-6. ${SMART_ROOT_STEP}
-7. ${PACK_STEP}
+6. ${smartRootStep(agentName)}
+7. ${packStep(agentName)}
 8. ${KNOWLEDGE_STEP}
 9. ${DOCTOR_STEP}
 10. ${STALE_STEP}
@@ -50,8 +54,8 @@ export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}
-- ${SMART_ROOT_STEP}
-- ${PACK_STEP}
+- ${smartRootStep(agentName)}
+- ${packStep(agentName)}
 - ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}
 - ${STALE_STEP}

package/dist/scanner/tree-sitter-parser.js

@@ -1,6 +1,9 @@
+import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Language, Parser } from 'web-tree-sitter';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 let initPromise = null;
 const languageCache = new Map();
@@ -42,8 +45,31 @@ async function ensureInit() {
 }
 function resolveWasmPath(grammarKey) {
     const { pkg, wasm } = GRAMMAR_PACKAGES[grammarKey];
-    const pkgDir = path.dirname(require.resolve(`${pkg}/package.json`));
-    return path.join(pkgDir, wasm);
+    // Production: bundled in dist/grammars/
+    const bundled = path.join(__dirname, '..', 'grammars', wasm);
+    if (fs.existsSync(bundled))
+        return bundled;
+    // Development: resolve from node_modules
+    try {
+        const pkgDir = path.dirname(require.resolve(`${pkg}/package.json`));
+        const fromPkg = path.join(pkgDir, wasm);
+        if (fs.existsSync(fromPkg))
+            return fromPkg;
+    }
+    catch {
+        // package not installed
+    }
+    // Fallback: tree-sitter-wasms package
+    try {
+        const wasmsDir = path.join(path.dirname(require.resolve('tree-sitter-wasms/package.json')), 'out');
+        const fromWasms = path.join(wasmsDir, wasm);
+        if (fs.existsSync(fromWasms))
+            return fromWasms;
+    }
+    catch {
+        // tree-sitter-wasms not installed
+    }
+    throw new Error(`Cannot find ${wasm} for grammar "${grammarKey}". Run "npm run build" or install dev dependencies.`);
 }
 export async function loadLanguage(grammarKey) {
     const cached = languageCache.get(grammarKey);

package/dist/types/session.d.ts

@@ -1,6 +1,6 @@
 import type { IntegrationName } from './config.js';
 export type SessionAgent = IntegrationName;
-export type SessionEventType = 'start' | 'read' | 'write' | 'end';
+export type SessionEventType = 'start' | 'context' | 'read' | 'write' | 'end';
 export type SessionCaptureSource = 'automatic' | 'agent-reported' | 'manual';
 export interface SessionEvent {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.24",
+  "version": "0.2.27",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   ],
   "scripts": {
     "clean": "node scripts/clean-dist.mjs",
-    "build": "npm run clean && tsc -p tsconfig.json",
+    "build": "npm run clean && tsc -p tsconfig.json && node scripts/bundle-grammars.mjs",
     "postbuild": "node -e \"try{require('child_process').execSync('chmod +x dist/cli/index.js')}catch{}\"",
     "test": "vitest run",
     "kgraph": "tsx src/cli/index.ts",
@@ -44,11 +44,19 @@
   "homepage": "https://github.com/kentwynn/KGraph#readme",
   "dependencies": {
     "@clack/prompts": "^1.3.0",
-    "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",
-    "@tree-sitter-grammars/tree-sitter-yaml": "^0.7.1",
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
+    "typescript": "^5.9.3",
+    "web-tree-sitter": "^0.26.8",
+    "yaml": "^2.5.1"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^11.0.0",
+    "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",
+    "@tree-sitter-grammars/tree-sitter-yaml": "^0.7.1",
+    "@types/node": "^20.17.10",
+    "release-it": "^20.0.1",
     "tree-sitter-bash": "^0.25.1",
     "tree-sitter-c": "^0.24.1",
     "tree-sitter-c-sharp": "^0.23.5",
@@ -66,14 +74,7 @@
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "^0.24.0",
     "tree-sitter-scala": "^0.24.0",
-    "typescript": "^5.9.3",
-    "web-tree-sitter": "^0.26.8",
-    "yaml": "^2.5.1"
-  },
-  "devDependencies": {
-    "@release-it/conventional-changelog": "^11.0.0",
-    "@types/node": "^20.17.10",
-    "release-it": "^20.0.1",
+    "tree-sitter-wasms": "^0.1.13",
     "tsx": "^4.19.2",
     "vitest": "^3.2.4"
   },