@kentwynn/kgraph 0.1.23 → 0.1.24

package/README.md

@@ -107,14 +107,14 @@ kgraph "auth token refresh"
 kgraph doctor
 ```
 
-After useful AI work, assistants can save durable notes into `.kgraph/inbox/`. The next `kgraph` run processes those notes automatically. You can also process them directly with `kgraph update`.
+After useful AI work, assistants save durable runtime-capture notes into `.kgraph/inbox/`. These notes are not project documentation; they are KGraph input files that the next `kgraph` run processes automatically. You can also process them directly with `kgraph update`.
 
 Normal agent flow is intentionally small:
 
 ```bash
 kgraph "topic"
 # work normally
-# if repo files changed, write an inbox note when the change has future value
+# if repo files changed, write an inbox note before the final refresh
 kgraph
 ```
 

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

@@ -17,30 +17,12 @@ export const claudeCodeAdapter = {
 4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 5. Track meaningful session activity with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code\` when native hooks are unavailable.
 6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-7. At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-8. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-9. 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.
-10. After the final \`kgraph\` run, mention whether the inbox note was processed.
-11. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-13. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 
-The inbox note must use this structure:
-\`\`\`markdown
-# <Short Title>
+{{KGRAPH_CAPTURE_POLICY}}
 
-## Summary
-One or two sentences describing the durable change or finding.
-
-## Key Files
-- \`path/to/file.ts\` — what changed or why it matters
-
-## Key Symbols
-- \`FunctionName\` — what changed or why it matters
-
-## Decisions
-Any implementation or product decision future sessions should know.
-\`\`\`
+7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
         },
         {

package/dist/integrations/adapters/cline.js

@@ -8,10 +8,7 @@ export const clineAdapter = {
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 - Track meaningful session activity with \`kgraph session start --agent cline\`, \`kgraph session read <path> --agent cline\`, \`kgraph session write <path> --agent cline\`, and \`kgraph session end --agent cline\`.
 - Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-- 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.
-- After the final \`kgraph\` run, mention whether the inbox note was processed.
+{{KGRAPH_CAPTURE_POLICY}}
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

package/dist/integrations/adapters/codex.js

@@ -24,30 +24,12 @@ Workflow:
 4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 5. Track meaningful session activity with \`kgraph session start --agent codex\`, \`kgraph session read <path> --agent codex\`, \`kgraph session write <path> --agent codex\`, and \`kgraph session end --agent codex\`.
 6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-7. At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-8. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-9. 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.
-10. After the final \`kgraph\` run, mention whether the inbox note was processed.
-11. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-13. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 
-The inbox note must use this structure:
-\`\`\`markdown
-# <Short Title>
+{{KGRAPH_CAPTURE_POLICY}}
 
-## Summary
-One or two sentences describing the durable change or finding.
-
-## Key Files
-- \`path/to/file.ts\` — what changed or why it matters
-
-## Key Symbols
-- \`FunctionName\` — what changed or why it matters
-
-## Decisions
-Any implementation or product decision future sessions should know.
-\`\`\`
+7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
         },
     ],

package/dist/integrations/adapters/copilot.js

@@ -8,28 +8,10 @@ export const copilotAdapter = {
 2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 3. Track meaningful session activity with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot\`.
 4. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-5. At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-6. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-7. 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.
-8. After the final \`kgraph\` run, mention whether the inbox note was processed.
-9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 
-The inbox note must use this structure:
-\`\`\`markdown
-# <Short Title>
+{{KGRAPH_CAPTURE_POLICY}}
 
-## Summary
-One or two sentences describing what was done.
-
-## Key Files
-- \`path/to/file.ts\` — what it does
-
-## Key Symbols
-- \`FunctionName\` — what it does
-
-## Decisions
-Any architectural or implementation decisions made.
-\`\`\`
+5. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 `,
     commandFiles: [
         {
@@ -93,27 +75,7 @@ argument-hint: "Brief description of what was done"
 
 Capture this session into KGraph cognition.
 
-1. For any completed code or repo-file change, write one Markdown note to \`.kgraph/inbox/<slug>.md\` using the structure below.
-2. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-3. Use the user's message as context, but keep the note factual and concise.
-4. Run \`kgraph\` once to process the note and refresh maps. Use \`kgraph update\` only when you intentionally want inbox processing without a scan.
-
-Note structure:
-\`\`\`markdown
-# <Short Title>
-
-## Summary
-One or two sentences describing what was done.
-
-## Key Files
-- \`path/to/file.ts\` — what it does
-
-## Key Symbols
-- \`FunctionName\` — what it does
-
-## Decisions
-Any architectural or implementation decisions made.
-\`\`\`
+{{KGRAPH_CAPTURE_POLICY}}
 `,
         },
         {

package/dist/integrations/adapters/cursor.js

@@ -13,10 +13,7 @@ alwaysApply: true
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 - Track meaningful session activity with \`kgraph session start --agent cursor\`, \`kgraph session read <path> --agent cursor\`, \`kgraph session write <path> --agent cursor\`, and \`kgraph session end --agent cursor\`.
 - Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-- 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.
-- After the final \`kgraph\` run, mention whether the inbox note was processed.
+{{KGRAPH_CAPTURE_POLICY}}
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

package/dist/integrations/adapters/gemini.js

@@ -8,10 +8,7 @@ export const geminiAdapter = {
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 - Track meaningful session activity with \`kgraph session start --agent gemini\`, \`kgraph session read <path> --agent gemini\`, \`kgraph session write <path> --agent gemini\`, and \`kgraph session end --agent gemini\`.
 - Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-- 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.
-- After the final \`kgraph\` run, mention whether the inbox note was processed.
+{{KGRAPH_CAPTURE_POLICY}}
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

package/dist/integrations/adapters/windsurf.js

@@ -8,10 +8,7 @@ export const windsurfAdapter = {
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
 - Track meaningful session activity with \`kgraph session start --agent windsurf\`, \`kgraph session read <path> --agent windsurf\`, \`kgraph session write <path> --agent windsurf\`, and \`kgraph session end --agent windsurf\`.
 - Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
-- 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.
-- After the final \`kgraph\` run, mention whether the inbox note was processed.
+{{KGRAPH_CAPTURE_POLICY}}
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

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

@@ -1,6 +1,8 @@
 import type { IntegrationMode } from "../types/config.js";
 export declare const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLICY}}";
+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;

package/dist/integrations/instruction-blocks.js

@@ -1,6 +1,7 @@
 const MARKER_PREFIX = "<!--";
 const MARKER_SUFFIX = "-->";
 export const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLICY}}";
+export const KGRAPH_CAPTURE_POLICY_PLACEHOLDER = "{{KGRAPH_CAPTURE_POLICY}}";
 export function upsertManagedBlock(content, integrationName, instructions) {
     const normalized = content.trimEnd();
     const block = renderManagedBlock(integrationName, instructions);
@@ -27,7 +28,9 @@ function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 export function applyContextPolicy(content, mode) {
-    return content.replaceAll(KGRAPH_CONTEXT_POLICY_PLACEHOLDER, renderContextPolicy(mode));
+    return content
+        .replaceAll(KGRAPH_CONTEXT_POLICY_PLACEHOLDER, renderContextPolicy(mode))
+        .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy());
 }
 export function renderContextPolicy(mode) {
     switch (mode) {
@@ -42,3 +45,28 @@ export function renderContextPolicy(mode) {
             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.';
     }
 }
+export function renderCapturePolicy() {
+    return `Capture policy:
+- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+- A \`.kgraph/inbox/*.md\` note is KGraph runtime capture, not project documentation. It is allowed and required by this workflow unless the user explicitly says not to capture to KGraph.
+- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+- 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.
+- After the final \`kgraph\` run, mention whether the inbox note was processed.
+
+The inbox note must use this structure:
+\`\`\`markdown
+# <Short Title>
+
+## Summary
+One or two sentences describing what was done.
+
+## Key Files
+- \`path/to/file.ts\` - what changed or why it matters
+
+## Key Symbols
+- \`FunctionName\` - what changed or why it matters
+
+## Decisions
+Any implementation or product decision future sessions should know.
+\`\`\``;
+}

package/package.json

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