@kentwynn/kgraph 0.1.23 → 0.1.25

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/cli/commands/init.d.ts

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

package/dist/cli/commands/init.js

@@ -1,28 +1,43 @@
-import { writeDefaultConfig } from "../../config/config.js";
-import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
-import { addIntegrations } from "../../integrations/integration-store.js";
-import { ensureWorkspace } from "../../storage/kgraph-paths.js";
-import { KGraphError, runCommand } from "../errors.js";
+import { loadConfig, writeDefaultConfig } from '../../config/config.js';
+import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
+import { addIntegrations } from '../../integrations/integration-store.js';
+import { scanRepository } from '../../scanner/repo-scanner.js';
+import { ensureWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps, writeMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
 export function registerInitCommand(program) {
     program
-        .command("init")
-        .description("Initialize a .kgraph workspace")
-        .option("--integration <name>", "Configure an AI tool integration", collectOption, [])
-        .option("--integrations <names>", "Configure comma-separated AI tool integrations")
-        .option("--mode <mode>", "Integration mode: smart, always, manual, or off", "always")
+        .command('init')
+        .description('Initialize a .kgraph workspace')
+        .option('--integration <name>', 'Configure an AI tool integration', collectOption, [])
+        .option('--integrations <names>', 'Configure comma-separated AI tool integrations')
+        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         const wroteConfig = await writeDefaultConfig(workspace);
-        console.log(wroteConfig ? "Initialized .kgraph workspace." : ".kgraph workspace already initialized.");
+        console.log(wroteConfig
+            ? 'Initialized .kgraph workspace.'
+            : '.kgraph workspace already initialized.');
         const names = normalizeIntegrationNames([
             ...(options.integration ?? []),
-            ...(options.integrations ? [options.integrations] : [])
+            ...(options.integrations ? [options.integrations] : []),
         ]);
         if (names.length > 0) {
             const mode = normalizeIntegrationMode(options.mode);
             const changed = await addIntegrations(workspace, names, mode);
-            console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+            console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
         }
+        const config = await loadConfig(workspace);
+        const previousMaps = await readMaps(workspace);
+        const result = await scanRepository(workspace.rootPath, config, {
+            files: previousMaps.fileMap.files,
+            symbols: previousMaps.symbolMap.symbols,
+            dependencies: previousMaps.dependencyMap.dependencies,
+            relationships: previousMaps.relationshipMap.relationships,
+            warnings: [],
+        });
+        await writeMaps(workspace, result);
+        console.log(`Scanned ${result.files.length} files and ${result.symbols.length} symbols.`);
     }));
 }
 function collectOption(value, previous) {
@@ -30,8 +45,11 @@ function collectOption(value, previous) {
     return previous;
 }
 function normalizeIntegrationMode(value) {
-    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+    if (value === 'smart' ||
+        value === 'always' ||
+        value === 'manual' ||
+        value === 'off') {
         return value;
     }
-    throw new KGraphError("--mode must be smart, always, manual, or off.");
+    throw new KGraphError('--mode must be smart, always, manual, or off.');
 }

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

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

package/dist/cli/commands/integrate.js

@@ -1,63 +1,75 @@
-import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode } from "../../integrations/integration-store.js";
-import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
-import { assertWorkspace } from "../../storage/kgraph-paths.js";
-import { KGraphError, runCommand } from "../errors.js";
+import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
+import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode, } from '../../integrations/integration-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
 export function registerIntegrateCommand(program) {
-    const integrate = program.command("integrate").description("Manage AI tool integrations");
-    integrate.command("list").description("List configured integrations").action(() => runCommand(async () => {
+    const integrate = program
+        .command('integrate')
+        .description('Manage AI tool integrations');
+    integrate
+        .command('list')
+        .description('List configured integrations')
+        .action(() => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const integrations = await listIntegrations(workspace);
         if (integrations.length === 0) {
-            console.log("No integrations configured.");
+            console.log('No integrations configured.');
             return;
         }
         for (const integration of integrations) {
-            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.mode} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
+            console.log(`${integration.name} ${integration.enabled ? 'enabled' : 'disabled'} ${integration.mode} ${integration.targetPath} ${integration.targetExists ? 'present' : 'missing'}`);
         }
     }));
     integrate
-        .command("add")
-        .description("Add AI tool integrations")
-        .argument("<names...>")
-        .option("--mode <mode>", "smart, always, manual, or off", "always")
+        .command('add')
+        .description('Add AI tool integrations')
+        .argument('<names...>')
+        .option('--mode <mode>', 'always, smart, manual, or off', 'always')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
-            throw new KGraphError("Provide at least one integration name.");
+            throw new KGraphError('Provide at least one integration name.');
         }
         const mode = normalizeIntegrationMode(options.mode);
         const changed = await addIntegrations(workspace, normalized, mode);
-        console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+        console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
     }));
     integrate
-        .command("set")
-        .description("Set AI tool integration mode")
-        .argument("<names...>")
-        .requiredOption("--mode <mode>", "smart, always, manual, or off")
+        .command('set')
+        .description('Set AI tool integration mode')
+        .argument('<names...>')
+        .requiredOption('--mode <mode>', 'smart, always, manual, or off')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
-            throw new KGraphError("Provide at least one integration name.");
+            throw new KGraphError('Provide at least one integration name.');
         }
         const mode = normalizeIntegrationMode(options.mode);
         const changed = await setIntegrationMode(workspace, normalized, mode);
-        console.log(`Updated integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+        console.log(`Updated integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
     }));
-    integrate.command("remove").description("Remove AI tool integrations").argument("<names...>").action((names) => runCommand(async () => {
+    integrate
+        .command('remove')
+        .description('Remove AI tool integrations')
+        .argument('<names...>')
+        .action((names) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
-            throw new KGraphError("Provide at least one integration name.");
+            throw new KGraphError('Provide at least one integration name.');
         }
         const removed = await removeIntegrations(workspace, normalized);
-        console.log(`Removed integrations: ${removed.join(", ")}`);
+        console.log(`Removed integrations: ${removed.join(', ')}`);
     }));
 }
 function normalizeIntegrationMode(value) {
-    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+    if (value === 'smart' ||
+        value === 'always' ||
+        value === 'manual' ||
+        value === 'off') {
         return value;
     }
-    throw new KGraphError("--mode must be smart, always, manual, or off.");
+    throw new KGraphError('--mode must be smart, always, manual, or off.');
 }

package/dist/cognition/markdown-note-parser.js

@@ -1,8 +1,9 @@
 import YAML from 'yaml';
 const PATH_REF = /(?:^|\s|`?)([\w./-]+\.(?:ts|tsx|js|jsx|json|md|yaml|yml))(?:\s|$|[),.;`])/g;
 export function parseMarkdownNote(markdown) {
+    const normalized = markdown.replace(/\r\n/g, '\n');
     const warnings = [];
-    const { frontmatter, body } = splitFrontmatter(markdown, warnings);
+    const { frontmatter, body } = splitFrontmatter(normalized, warnings);
     const sections = parseSections(body);
     const frontmatterTitle = typeof frontmatter.title === 'string' ? frontmatter.title : undefined;
     const title = extractTitle(body) ?? frontmatterTitle ?? 'Untitled Cognition Note';

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";
+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}}";
+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);
@@ -8,37 +9,67 @@ export function upsertManagedBlock(content, integrationName, instructions) {
     if (pattern.test(content)) {
         return content.replace(pattern, block);
     }
-    return `${normalized}${normalized ? "\n\n" : ""}${block}\n`;
+    return normalized ? `${block}\n\n${normalized}\n` : `${block}\n`;
 }
 export function removeManagedBlock(content, integrationName) {
-    return content.replace(managedBlockPattern(integrationName), "").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+    return (content
+        .replace(managedBlockPattern(integrationName), '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim() + '\n');
 }
 function renderManagedBlock(integrationName, instructions) {
     return [
         `${MARKER_PREFIX} BEGIN KGRAPH ${integrationName} ${MARKER_SUFFIX}`,
         instructions.trim(),
-        `${MARKER_PREFIX} END KGRAPH ${integrationName} ${MARKER_SUFFIX}`
-    ].join("\n");
+        `${MARKER_PREFIX} END KGRAPH ${integrationName} ${MARKER_SUFFIX}`,
+    ].join('\n');
 }
 function managedBlockPattern(integrationName) {
-    return new RegExp(`${escapeRegExp(MARKER_PREFIX)} BEGIN KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}[\\s\\S]*?${escapeRegExp(MARKER_PREFIX)} END KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}\\n?`, "m");
+    return new RegExp(`${escapeRegExp(MARKER_PREFIX)} BEGIN KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}[\\s\\S]*?${escapeRegExp(MARKER_PREFIX)} END KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}\\n?`, 'm');
 }
 function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    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) {
-        case "always":
+        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.';
-        case "manual":
+        case 'manual':
             return 'Do not run KGraph automatically. Run `kgraph "<topic>"` only when the user explicitly asks for KGraph context or invokes the KGraph command.';
-        case "off":
-            return "KGraph is disabled for this integration.";
-        case "smart":
+        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.';
     }
 }
+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/dist/integrations/integration-registry.d.ts

@@ -1,4 +1,4 @@
-import type { IntegrationName } from "../types/config.js";
+import type { IntegrationName } from '../types/config.js';
 export interface IntegrationAdapter {
     name: IntegrationName;
     label: string;

package/dist/integrations/integration-registry.js

@@ -1,10 +1,10 @@
-import { claudeCodeAdapter } from "./adapters/claude-code.js";
-import { clineAdapter } from "./adapters/cline.js";
-import { codexAdapter } from "./adapters/codex.js";
-import { copilotAdapter } from "./adapters/copilot.js";
-import { cursorAdapter } from "./adapters/cursor.js";
-import { geminiAdapter } from "./adapters/gemini.js";
-import { windsurfAdapter } from "./adapters/windsurf.js";
+import { claudeCodeAdapter } from './adapters/claude-code.js';
+import { clineAdapter } from './adapters/cline.js';
+import { codexAdapter } from './adapters/codex.js';
+import { copilotAdapter } from './adapters/copilot.js';
+import { cursorAdapter } from './adapters/cursor.js';
+import { geminiAdapter } from './adapters/gemini.js';
+import { windsurfAdapter } from './adapters/windsurf.js';
 const ADAPTERS = [
     claudeCodeAdapter,
     clineAdapter,
@@ -12,7 +12,7 @@ const ADAPTERS = [
     copilotAdapter,
     cursorAdapter,
     geminiAdapter,
-    windsurfAdapter
+    windsurfAdapter,
 ].sort((left, right) => left.name.localeCompare(right.name));
 export function listIntegrationAdapters() {
     return ADAPTERS;
@@ -20,7 +20,7 @@ export function listIntegrationAdapters() {
 export function getIntegrationAdapter(name) {
     const adapter = ADAPTERS.find((item) => item.name === name);
     if (!adapter) {
-        throw new Error(`Unsupported integration "${name}". Supported integrations: ${ADAPTERS.map((item) => item.name).join(", ")}`);
+        throw new Error(`Unsupported integration "${name}". Supported integrations: ${ADAPTERS.map((item) => item.name).join(', ')}`);
     }
     return adapter;
 }
@@ -31,7 +31,7 @@ export function normalizeIntegrationNames(values) {
     const names = [];
     const seen = new Set();
     for (const value of values) {
-        for (const raw of value.split(",")) {
+        for (const raw of value.split(/[\s,]+/)) {
             const name = raw.trim();
             if (!name || seen.has(name)) {
                 continue;

package/dist/integrations/integration-store.d.ts

@@ -1,4 +1,4 @@
-import type { IntegrationConfig, IntegrationMode, IntegrationName, KGraphWorkspace } from "../types/config.js";
+import type { IntegrationConfig, IntegrationMode, IntegrationName, KGraphWorkspace } from '../types/config.js';
 export interface IntegrationStatus {
     name: IntegrationName;
     enabled: boolean;

package/dist/integrations/integration-store.js

@@ -1,9 +1,9 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { loadConfig, saveConfig } from "../config/config.js";
-import { pathExists } from "../storage/kgraph-paths.js";
-import { getIntegrationAdapter } from "./integration-registry.js";
-import { applyContextPolicy, removeManagedBlock, upsertManagedBlock } from "./instruction-blocks.js";
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig, saveConfig } from '../config/config.js';
+import { pathExists } from '../storage/kgraph-paths.js';
+import { applyContextPolicy, removeManagedBlock, upsertManagedBlock, } from './instruction-blocks.js';
+import { getIntegrationAdapter } from './integration-registry.js';
 export async function listIntegrations(workspace) {
     const config = await loadConfig(workspace);
     const statuses = await Promise.all(config.integrations.map(async (integration) => ({
@@ -11,11 +11,11 @@ export async function listIntegrations(workspace) {
         enabled: integration.enabled,
         mode: integration.mode,
         targetPath: integration.targetPath,
-        targetExists: await pathExists(path.join(workspace.rootPath, integration.targetPath))
+        targetExists: await pathExists(path.join(workspace.rootPath, integration.targetPath)),
     })));
     return statuses.sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function addIntegrations(workspace, names, mode = "always") {
+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 = [];
@@ -23,12 +23,12 @@ export async function addIntegrations(workspace, names, mode = "always") {
         const adapter = getIntegrationAdapter(name);
         const next = {
             name: adapter.name,
-            enabled: mode !== "off",
+            enabled: mode !== 'off',
             mode,
-            targetPath: adapter.targetPath
+            targetPath: adapter.targetPath,
         };
         byName.set(adapter.name, next);
-        if (mode === "off") {
+        if (mode === 'off') {
             await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
             await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
         }
@@ -36,7 +36,7 @@ export async function addIntegrations(workspace, names, mode = "always") {
             await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
             await writeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).map((file) => ({
                 ...file,
-                content: applyContextPolicy(file.content, mode)
+                content: applyContextPolicy(file.content, mode),
             })));
         }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
@@ -66,34 +66,36 @@ export async function removeIntegrations(workspace, names) {
 }
 async function writeIntegrationInstructions(rootPath, targetPath, integrationName, instructions) {
     const fullPath = path.join(rootPath, targetPath);
-    const existing = (await pathExists(fullPath)) ? await readFile(fullPath, "utf8") : "";
+    const existing = (await pathExists(fullPath))
+        ? await readFile(fullPath, 'utf8')
+        : '';
     const next = upsertManagedBlock(existing, integrationName, instructions);
     await mkdir(path.dirname(fullPath), { recursive: true });
-    await writeFile(fullPath, next, "utf8");
+    await writeFile(fullPath, next, 'utf8');
 }
 async function removeIntegrationInstructions(rootPath, targetPath, integrationName) {
     const fullPath = path.join(rootPath, targetPath);
     if (!(await pathExists(fullPath))) {
         return;
     }
-    const existing = await readFile(fullPath, "utf8");
+    const existing = await readFile(fullPath, 'utf8');
     const next = removeManagedBlock(existing, integrationName);
     if (next.trim().length === 0) {
         await rm(fullPath, { force: true });
         return;
     }
-    await writeFile(fullPath, next, "utf8");
+    await writeFile(fullPath, next, 'utf8');
 }
 async function writeIntegrationCommandFiles(rootPath, files) {
     for (const file of files) {
         const fullPath = path.join(rootPath, file.path);
         await mkdir(path.dirname(fullPath), { recursive: true });
-        await writeFile(fullPath, file.content.trimEnd() + "\n", "utf8");
+        await writeFile(fullPath, file.content.trimEnd() + '\n', 'utf8');
     }
 }
 async function removeIntegrationCommandFiles(rootPath, files) {
     for (const file of files) {
-        const filePath = typeof file === "string" ? file : file.path;
+        const filePath = typeof file === 'string' ? file : file.path;
         await rm(path.join(rootPath, filePath), { force: true, recursive: true });
     }
 }

package/dist/visualization/html-template.js

@@ -53,6 +53,7 @@ select:hover,button:hover{background:#475569}
   <span id="t-title">\u29e1 KGraph \u00b7 ${repoName}</span>
   <span id="t-stats">${meta.fileCount} files &middot; ${meta.symbolCount} symbols &middot; ${meta.cognitionCount} notes &middot; ~${meta.tokenEstimate} tokens</span>
   <div id="t-controls">
+    <label class="clabel"><input type="checkbox" id="tog-lbl" checked> Labels</label>
     <label class="clabel"><input type="checkbox" id="tog-cog" checked> Cognition</label>
     <select id="sel-layout" title="Graph layout algorithm">
       <option value="dagre">Hierarchical</option>
@@ -108,6 +109,27 @@ select:hover,button:hover{background:#475569}
     cytoscape.use(cytoscapeDagre);
   }
 
+  // Separate symbol data from graph elements — symbols are shown in sidebar only.
+  var SYMBOL_TYPES = { symbol: 1, contains: 1, 'symbol-contains': 1, calls: 1 };
+  var coreElements = [];
+  var symbolsByFile = {};
+  GRAPH_DATA.elements.forEach(function (el) {
+    if (el.data.type === 'symbol') {
+      var fp = el.data.path;
+      if (!symbolsByFile[fp]) symbolsByFile[fp] = [];
+      symbolsByFile[fp].push(el.data);
+    } else if (!SYMBOL_TYPES[el.data.type]) {
+      coreElements.push(el);
+    }
+  });
+
+  var LARGE_THRESHOLD = 200;
+  var isLarge = coreElements.length > LARGE_THRESHOLD;
+
+  if (isLarge) {
+    document.getElementById('tog-lbl').checked = false;
+  }
+
   function esc(v) {
     return String(v == null ? '' : v)
       .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -122,13 +144,13 @@ select:hover,button:hover{background:#475569}
 
   var cy = cytoscape({
     container: document.getElementById('cy'),
-    elements: GRAPH_DATA.elements,
+    elements: coreElements,
     style: [
       {
         selector: 'node',
         style: {
           'background-color': 'data(color)',
-          label: 'data(label)',
+          label: isLarge ? '' : 'data(label)',
           color: '#94a3b8',
           'font-size': '10px',
           'text-valign': 'bottom',
@@ -136,8 +158,8 @@ select:hover,button:hover{background:#475569}
           'text-margin-y': '5px',
           'border-width': 1,
           'border-color': '#1e293b',
-          width: 30,
-          height: 30,
+          width: isLarge ? 20 : 30,
+          height: isLarge ? 20 : 30,
           'text-wrap': 'ellipsis',
           'text-max-width': '80px',
           'overlay-opacity': 0
@@ -204,37 +226,45 @@ select:hover,button:hover{background:#475569}
       },
       { selector: '.hidden', style: { display: 'none' } }
     ],
-    layout: {
-      name: 'dagre',
-      rankDir: 'LR',
-      nodeSep: 60,
-      rankSep: 120,
-      padding: 40,
-      animate: true,
-      animationDuration: 400
-    }
+    layout: isLarge
+      ? { name: 'cose', animate: false, padding: 40, nodeOverlap: 20, idealEdgeLength: 80, numIter: 100 }
+      : { name: 'dagre', rankDir: 'LR', nodeSep: 60, rankSep: 120, padding: 40, animate: true, animationDuration: 400 }
   });
 
+  var anim = !isLarge;
   var LAYOUTS = {
-    dagre: { name: 'dagre', rankDir: 'LR', nodeSep: 60, rankSep: 120, animate: true, animationDuration: 400, padding: 40 },
-    cose: { name: 'cose', animate: true, animationDuration: 600, padding: 40 },
-    grid: { name: 'grid', animate: true, animationDuration: 400, padding: 40 },
+    dagre: { name: 'dagre', rankDir: 'LR', nodeSep: 60, rankSep: 120, animate: anim, animationDuration: 400, padding: 40 },
+    cose: { name: 'cose', animate: anim, animationDuration: 600, padding: 40 },
+    grid: { name: 'grid', animate: anim, animationDuration: 400, padding: 40 },
     concentric: {
       name: 'concentric',
       concentric: function (n) { return n.degree(); },
       levelWidth: function () { return 2; },
-      animate: true,
+      animate: anim,
       animationDuration: 400,
       padding: 40
     }
   };
 
+  var SYMBOL_KIND_COLORS = { 'function': '#22c55e', 'class': '#a855f7', method: '#14b8a6', 'export': '#f97316', 'import': '#64748b' };
+
   function renderFilePanel(d) {
+    var syms = symbolsByFile[d.path] || [];
+    var symHtml = '';
+    if (syms.length) {
+      symHtml = '<div class="sb-sect"><div class="sb-lbl">Symbols (' + syms.length + ')</div><ul class="sb-list">' +
+        syms.map(function (s) {
+          var c = SYMBOL_KIND_COLORS[s.kind] || '#94a3b8';
+          return '<li><span style="color:' + c + ';font-weight:600">' + esc(s.kind) + '</span> <span class="sb-code">' + esc(s.label) + '</span>' +
+            (s.parentName ? ' <span style="color:#475569">in ' + esc(s.parentName) + '</span>' : '') + '</li>';
+        }).join('') + '</ul></div>';
+    }
     return '<div class="sb-badge" style="background:' + esc(d.color) + '22;color:' + esc(d.color) + ';border:1px solid ' + esc(d.color) + '44">' + esc(d.language) + '</div>' +
       '<div class="sb-title">' + esc(d.path) + '</div>' +
       '<div class="sb-sect"><div class="sb-lbl">Scan Status</div><div class="sb-val">' + esc(d.scanStatus) + '</div></div>' +
       '<div class="sb-sect"><div class="sb-lbl">File Size</div><div class="sb-val">' + bytes(d.size) + '</div></div>' +
-      '<div class="sb-sect"><div class="sb-lbl">Estimated Tokens</div><div class="sb-val">~' + esc(d.tokenEstimate || 0) + ' tokens</div></div>';
+      '<div class="sb-sect"><div class="sb-lbl">Estimated Tokens</div><div class="sb-val">~' + esc(d.tokenEstimate || 0) + ' tokens</div></div>' +
+      symHtml;
   }
 
   function renderCognitionPanel(d) {
@@ -269,6 +299,10 @@ select:hover,button:hover{background:#475569}
     document.getElementById('sidebar').classList.remove('open');
   });
 
+  document.getElementById('tog-lbl').addEventListener('change', function (e) {
+    cy.style().selector('node').style('label', e.target.checked ? 'data(label)' : '').update();
+  });
+
   document.getElementById('tog-cog').addEventListener('change', function (e) {
     if (e.target.checked) {
       cy.nodes('.cognition').removeClass('hidden');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",
-    "postbuild": "chmod +x dist/cli/index.js",
+    "postbuild": "node -e \"try{require('child_process').execSync('chmod +x dist/cli/index.js')}catch{}\"",
     "test": "vitest run",
     "kgraph": "tsx src/cli/index.ts",
     "check:artifacts": "node scripts/check-clean-artifacts.mjs",