@kentwynn/kgraph 0.2.16 → 0.2.18

package/README.md

@@ -121,12 +121,14 @@ After useful AI work, assistants save durable runtime-capture notes into `.kgrap
 Normal agent flow is intentionally small:
 
 ```bash
-kgraph "topic"
+kgraph pack "topic" --budget 8000 --json
 # work normally
 # if repo files changed, write an inbox note before the final refresh
 kgraph
 ```
 
+`kgraph "<topic>"` remains the human-readable briefing. Agents should prefer `kgraph pack "<topic>" --budget 8000 --json` because it returns the stable `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.
 
 Agents can also report session activity so KGraph can estimate token waste:
@@ -249,7 +251,7 @@ 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.
+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.
 
 ```bash
 kgraph compact --dry-run

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

@@ -1,2 +1,4 @@
 import type { Command } from 'commander';
+import type { ContextPack } from '../../types/knowledge.js';
 export declare function registerPackCommand(program: Command): void;
+export declare function renderPackText(pack: ContextPack): string;

package/dist/cli/commands/pack.js

@@ -31,19 +31,66 @@ export function registerPackCommand(program) {
             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('; ')}`);
+        console.log(renderPackText(pack));
+    }));
+}
+export function renderPackText(pack) {
+    const lines = [
+        `KGraph Pack · ${pack.task}`,
+        `local-first · budget-aware · machine contract: --json`,
+        ``,
+        `● Budget`,
+        `  used        ${pack.usedTokens} / ${pack.budget}`,
+        `  included    ${pack.items.length}`,
+        `  omitted     ${pack.omitted.length}`,
+        ``,
+    ];
+    appendGroup(lines, 'Atoms', pack.items.filter((item) => item.kind === 'atom'));
+    appendGroup(lines, 'Git Changes', pack.items.filter((item) => item.kind === 'git-change'));
+    appendGroup(lines, 'Source Ranges', pack.items.filter((item) => item.kind === 'file-range'));
+    appendGroup(lines, 'Symbols', pack.items.filter((item) => item.kind === 'symbol'));
+    appendGroup(lines, 'Files', pack.items.filter((item) => item.kind === 'file'));
+    appendGroup(lines, 'Graph', pack.items.filter((item) => item.kind === 'relationship'));
+    lines.push(`● Omitted`);
+    const omitted = pack.omitted.slice(0, 8);
+    if (omitted.length === 0) {
+        lines.push('- None');
+    }
+    else {
+        for (const item of omitted) {
+            lines.push(`  ◌ ${item.kind} ${item.title} (~${item.tokenEstimate} tokens)`);
         }
-        if (pack.omitted.length > 0) {
-            console.log('');
-            console.log(`Omitted: ${pack.omitted.length} item(s) over budget`);
+        if (pack.omitted.length > omitted.length) {
+            lines.push(`  ◌ ${pack.omitted.length - omitted.length} more omitted items`);
         }
-    }));
+    }
+    lines.push('', '● Next', '  agents should consume this command with --json for the full ContextPack contract');
+    return lines.join('\n');
+}
+function appendGroup(lines, title, items) {
+    lines.push(`● ${title}`);
+    if (items.length === 0) {
+        lines.push('- None', '');
+        return;
+    }
+    for (const item of items.slice(0, 6)) {
+        lines.push(`  ● ${item.title} (~${item.tokenEstimate} tokens)`);
+        lines.push(`    because ${formatReasons(item.reasons)}`);
+        if (item.kind === 'file-range') {
+            const data = item.data;
+            if (data.path && data.startLine != null && data.endLine != null) {
+                lines.push(`    range ${data.path}:${data.startLine}-${data.endLine}`);
+            }
+        }
+    }
+    if (items.length > 6)
+        lines.push(`  ◌ ${items.length - 6} more ${title.toLowerCase()} omitted from display`);
+    lines.push('');
+}
+function formatReasons(reasons) {
+    if (reasons.length === 0)
+        return 'included by pack ranking';
+    const shown = reasons.slice(0, 3);
+    const remaining = reasons.length - shown.length;
+    return remaining > 0 ? `${shown.join('; ')}; and ${remaining} more` : shown.join('; ');
 }

package/dist/context/context-pack.js

@@ -53,10 +53,15 @@ export function buildContextPack(response, budget, rootPath) {
         })),
     ];
     const orderedCandidates = candidates.sort(comparePackCandidates);
+    const strongPaths = strongPackPaths(candidates);
     const items = [];
     const omitted = [];
     let usedTokens = 0;
     for (const candidate of orderedCandidates) {
+        if (isLowSignalCandidate(candidate, strongPaths)) {
+            omitted.push(candidate);
+            continue;
+        }
         if (usedTokens + candidate.tokenEstimate <= budget) {
             items.push(candidate);
             usedTokens += candidate.tokenEstimate;
@@ -102,6 +107,60 @@ function packPriority(item) {
     score -= Math.floor(item.tokenEstimate / 2000);
     return score;
 }
+function strongPackPaths(candidates) {
+    const paths = new Set();
+    for (const candidate of candidates) {
+        if (candidate.kind === 'file-range' || candidate.kind === 'git-change') {
+            const pathValue = candidatePath(candidate);
+            if (pathValue)
+                paths.add(pathValue);
+        }
+        if (candidate.kind === 'file' && hasStrongReason(candidate)) {
+            const pathValue = candidatePath(candidate);
+            if (pathValue)
+                paths.add(pathValue);
+        }
+        if (candidate.kind === 'atom') {
+            const atom = candidate.data;
+            for (const file of atom?.relatedFiles ?? [])
+                paths.add(file);
+        }
+    }
+    return paths;
+}
+function isLowSignalCandidate(candidate, strongPaths) {
+    if (strongPaths.size === 0)
+        return false;
+    if (candidate.kind === 'atom' || candidate.kind === 'git-change' || candidate.kind === 'file-range') {
+        return false;
+    }
+    if (hasStrongReason(candidate))
+        return false;
+    if (candidateTouchesStrongPath(candidate, strongPaths))
+        return false;
+    return candidate.kind === 'file' || candidate.kind === 'symbol' || candidate.kind === 'relationship';
+}
+function hasStrongReason(candidate) {
+    return candidate.reasons.some((reason) => reason.includes('matched atom') ||
+        reason.includes('current git change') ||
+        reason.includes('changed in recent commits') ||
+        reason.includes('unstaged change') ||
+        reason.includes('staged change'));
+}
+function candidateTouchesStrongPath(candidate, strongPaths) {
+    const pathValue = candidatePath(candidate);
+    if (pathValue && strongPaths.has(pathValue))
+        return true;
+    if (candidate.kind !== 'relationship')
+        return false;
+    const relationship = candidate.data;
+    return [...strongPaths].some((strongPath) => relationship.sourceId?.includes(strongPath) ||
+        relationship.targetId?.includes(strongPath));
+}
+function candidatePath(candidate) {
+    const data = candidate.data;
+    return data?.path ?? data?.filePath;
+}
 const GENERIC_RANGE_TOKENS = new Set([
     'app',
     'code',

package/dist/integrations/adapters/codex.js

@@ -1,4 +1,4 @@
-import { numberedWorkflow } from '../workflow-steps.js';
+import { agentSkillFiles } from '../agent-skills.js';
 export const codexAdapter = {
     name: 'codex',
     label: 'Codex',
@@ -7,24 +7,6 @@ export const codexAdapter = {
 
 {{KGRAPH_CONTEXT_POLICY}} The /kgraph skill handles 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.
 `,
-    commandFiles: [
-        {
-            path: '.agents/skills/kgraph/SKILL.md',
-            content: `---
-name: kgraph
-description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
----
-
-# KGraph Skill
-
-Workflow:
-
-${numberedWorkflow('codex')}
-`,
-        },
-    ],
-    obsoleteCommandFiles: [
-        '.agents/skills/kgraph-scan/SKILL.md',
-        '.agents/skills/kgraph-update/SKILL.md',
-    ],
+    commandFiles: agentSkillFiles('codex'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/adapters/copilot.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { numberedWorkflow } from '../workflow-steps.js';
 export const copilotAdapter = {
     name: 'copilot',
@@ -7,172 +8,6 @@ export const copilotAdapter = {
 
 ${numberedWorkflow('copilot')}
 `,
-    commandFiles: [
-        {
-            path: '.github/prompts/kgraph-doctor.prompt.md',
-            content: `---
-description: Check KGraph workspace health and next actions
-agent: agent
----
-
-Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-repair.prompt.md',
-            content: `---
-description: Preview or clean stale/noisy KGraph cognition references
-agent: agent
-argument-hint: "--dry-run or apply"
----
-
-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.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-compact.prompt.md',
-            content: `---
-description: Merge duplicate KGraph cognition and archive stale low-value entries
-agent: agent
-argument-hint: "--dry-run or apply"
----
-
-Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-pack.prompt.md',
-            content: `---
-description: Build a budget-aware KGraph context pack
-agent: agent
-argument-hint: "Task description"
----
-
-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.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-knowledge.prompt.md',
-            content: `---
-description: Inspect or manage KGraph canonical knowledge atoms
-agent: agent
-argument-hint: "list, get <atom-id>, archive <atom-id>, or supersede <old-id> <new-id>"
----
-
-Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-stale.prompt.md',
-            content: `---
-description: Show KGraph knowledge invalidated by changed or missing refs
-agent: agent
----
-
-Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-blame.prompt.md',
-            content: `---
-description: Show KGraph atom provenance and evidence
-agent: agent
-argument-hint: "Atom id"
----
-
-Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-scan.prompt.md',
-            content: `---
-description: Refresh KGraph file, symbol, import, and relationship maps
-agent: agent
----
-
-Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-update.prompt.md',
-            content: `---
-description: Process KGraph inbox notes into durable cognition
-agent: agent
----
-
-Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-visualize.prompt.md',
-            content: `---
-description: Open interactive KGraph dependency graph in browser
-agent: agent
----
-
-Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-capture.prompt.md',
-            content: `---
-description: Save what was just built or changed into KGraph cognition
-agent: agent
-argument-hint: "Brief description of what was done"
----
-
-Capture this session into KGraph cognition.
-
-{{KGRAPH_CAPTURE_POLICY}}
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-conclude.prompt.md',
-            content: `---
-description: Store a typed durable KGraph engineering conclusion
-agent: agent
-argument-hint: "Topic plus optional type, confidence, files, and symbols"
----
-
-Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-impact.prompt.md',
-            content: `---
-description: Show KGraph change impact for a file, symbol, or topic
-agent: agent
-argument-hint: "File, symbol, or topic"
----
-
-Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-session.prompt.md',
-            content: `---
-description: Track KGraph session read/write activity and token estimates
-agent: agent
-argument-hint: "start, read <path>, write <path>, end, or status"
----
-
-Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot --conclude --topic "<topic>"\` when durable session memory is useful.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-history.prompt.md',
-            content: `---
-description: Show timeline of KGraph cognition sessions with git attribution
-agent: agent
-argument-hint: "Optional topic"
----
-
-Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
-`,
-        },
-    ],
-    obsoleteCommandFiles: [
-        '.github/prompts/kgraph.prompt.md',
-        '.github/kgraph.agent.md',
-    ],
+    commandFiles: agentSkillFiles('copilot'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/agent-skills.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared agent skill definitions used by any integration that writes
+ * `.agents/skills/` SKILL.md files (copilot, codex, etc.).
+ *
+ * Per-command skills are agent-name-agnostic.
+ * The main kgraph workflow skill is parameterised by agent name.
+ */
+import type { IntegrationCommandFile } from './integration-registry.js';
+/** Per-command skills shared across all agent-skill integrations. */
+export declare const SHARED_AGENT_SKILLS: IntegrationCommandFile[];
+/**
+ * Build the full agent skill list for an adapter: the main workflow skill
+ * (parameterised by agent name) plus all shared per-command skills.
+ */
+export declare function agentSkillFiles(agentName: string): IntegrationCommandFile[];

package/dist/integrations/agent-skills.js

@@ -0,0 +1,186 @@
+/**
+ * Shared agent skill definitions used by any integration that writes
+ * `.agents/skills/` SKILL.md files (copilot, codex, etc.).
+ *
+ * Per-command skills are agent-name-agnostic.
+ * The main kgraph workflow skill is parameterised by agent name.
+ */
+import { numberedWorkflow } from './workflow-steps.js';
+/** Per-command skills shared across all agent-skill integrations. */
+export const SHARED_AGENT_SKILLS = [
+    {
+        path: '.agents/skills/kgraph-doctor/SKILL.md',
+        content: `---
+name: kgraph-doctor
+description: Check KGraph workspace health and next actions
+---
+
+Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-repair/SKILL.md',
+        content: `---
+name: kgraph-repair
+description: Preview or clean stale/noisy KGraph cognition references
+---
+
+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.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-compact/SKILL.md',
+        content: `---
+name: kgraph-compact
+description: Merge duplicate KGraph cognition and archive stale low-value entries
+---
+
+Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-pack/SKILL.md',
+        content: `---
+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.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-knowledge/SKILL.md',
+        content: `---
+name: kgraph-knowledge
+description: Inspect or manage KGraph canonical knowledge atoms
+---
+
+Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-stale/SKILL.md',
+        content: `---
+name: kgraph-stale
+description: Show KGraph knowledge invalidated by changed or missing refs
+---
+
+Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-blame/SKILL.md',
+        content: `---
+name: kgraph-blame
+description: Show KGraph atom provenance and evidence
+---
+
+Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-scan/SKILL.md',
+        content: `---
+name: kgraph-scan
+description: Refresh KGraph file, symbol, import, and relationship maps
+---
+
+Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-update/SKILL.md',
+        content: `---
+name: kgraph-update
+description: Process KGraph inbox notes into durable cognition
+---
+
+Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-visualize/SKILL.md',
+        content: `---
+name: kgraph-visualize
+description: Open interactive KGraph dependency graph in browser
+---
+
+Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-capture/SKILL.md',
+        content: `---
+name: kgraph-capture
+description: Save what was just built or changed into KGraph cognition
+---
+
+Capture this session into KGraph cognition.
+
+{{KGRAPH_CAPTURE_POLICY}}
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-conclude/SKILL.md',
+        content: `---
+name: kgraph-conclude
+description: Store a typed durable KGraph engineering conclusion
+---
+
+Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-impact/SKILL.md',
+        content: `---
+name: kgraph-impact
+description: Show KGraph change impact for a file, symbol, or topic
+---
+
+Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-session/SKILL.md',
+        content: `---
+name: kgraph-session
+description: Track KGraph session read/write activity and token estimates
+---
+
+Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent $AGENT\`, \`kgraph session read <path> --agent $AGENT\`, \`kgraph session write <path> --agent $AGENT\`, and \`kgraph session end --agent $AGENT --conclude --topic "<topic>"\` when durable session memory is useful.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-history/SKILL.md',
+        content: `---
+name: kgraph-history
+description: Show timeline of KGraph cognition sessions with git attribution
+---
+
+Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
+`,
+    },
+];
+/**
+ * Build the full agent skill list for an adapter: the main workflow skill
+ * (parameterised by agent name) plus all shared per-command skills.
+ */
+export function agentSkillFiles(agentName) {
+    return [
+        {
+            path: '.agents/skills/kgraph/SKILL.md',
+            content: `---
+name: kgraph
+description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
+---
+
+# KGraph Skill
+
+Workflow:
+
+${numberedWorkflow(agentName)}
+`,
+        },
+        ...SHARED_AGENT_SKILLS,
+    ];
+}

package/dist/integrations/instruction-blocks.js

@@ -36,17 +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.';
+    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.';
     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. ${useResultBoundary}`;
+            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}`;
         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.';
+            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 "<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}`;
+            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}`;
     }
 }
 export function renderCapturePolicy() {
@@ -56,7 +56,7 @@ export function renderCapturePolicy() {
 - 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>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph pack "<topic>" --budget 8000 --json\` for agent-readable context. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
 - 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

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, rmdir, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig, saveConfig } from '../config/config.js';
 import { pathExists } from '../storage/kgraph-paths.js';
@@ -19,6 +19,7 @@ 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 = [];
+    const writtenCommandFiles = new Set();
     for (const name of names) {
         const adapter = getIntegrationAdapter(name);
         const next = {
@@ -34,10 +35,14 @@ export async function addIntegrations(workspace, names, mode = 'always') {
         }
         else {
             await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
-            await writeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).map((file) => ({
+            const deduped = (adapter.commandFiles ?? []).filter((file) => !writtenCommandFiles.has(file.path));
+            await writeIntegrationCommandFiles(workspace.rootPath, deduped.map((file) => ({
                 ...file,
                 content: applyContextPolicy(file.content, mode),
             })));
+            for (const file of adapter.commandFiles ?? []) {
+                writtenCommandFiles.add(file.path);
+            }
         }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         changed.push(next);
@@ -53,10 +58,21 @@ export async function removeIntegrations(workspace, names) {
     const config = await loadConfig(workspace);
     const removeNames = new Set(names);
     const removed = [];
+    // Collect command-file paths still owned by remaining enabled integrations
+    const retainedPaths = new Set();
+    for (const integration of config.integrations) {
+        if (removeNames.has(integration.name) || !integration.enabled) {
+            continue;
+        }
+        const adapter = getIntegrationAdapter(integration.name);
+        for (const file of adapter.commandFiles ?? []) {
+            retainedPaths.add(file.path);
+        }
+    }
     for (const name of removeNames) {
         const adapter = getIntegrationAdapter(name);
         await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
-        await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+        await removeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).filter((file) => !retainedPaths.has(file.path)));
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         removed.push(adapter.name);
     }
@@ -96,6 +112,21 @@ async function writeIntegrationCommandFiles(rootPath, files) {
 async function removeIntegrationCommandFiles(rootPath, files) {
     for (const file of files) {
         const filePath = typeof file === 'string' ? file : file.path;
-        await rm(path.join(rootPath, filePath), { force: true, recursive: true });
+        const fullPath = path.join(rootPath, filePath);
+        await rm(fullPath, { force: true, recursive: true });
+        // Remove empty parent directories up to (but not including) rootPath
+        let dir = path.dirname(fullPath);
+        while (dir !== rootPath && dir.startsWith(rootPath)) {
+            try {
+                const entries = await readdir(dir);
+                if (entries.length > 0)
+                    break;
+                await rmdir(dir);
+                dir = path.dirname(dir);
+            }
+            catch {
+                break;
+            }
+        }
     }
 }

package/dist/integrations/workflow-steps.js

@@ -8,7 +8,7 @@ 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 = `Run \`kgraph pack "<task>" --budget 8000 --json\` when an agent needs a machine-readable, token-budgeted context pack instead of human Markdown context.`;
+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 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.`;

package/package.json

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