@kentwynn/kgraph 0.2.31 → 0.2.33

package/dist/cli/commands/init.js

@@ -1,4 +1,4 @@
-import { loadConfig, writeDefaultConfig } from '../../config/config.js';
+import { loadConfig, saveConfig, writeDefaultConfig, } from '../../config/config.js';
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations } from '../../integrations/integration-store.js';
 import { ensureKnowledgeStore } from '../../knowledge/atom-store.js';
@@ -6,9 +6,10 @@ 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';
-import { promptForInitIntegrations, shouldPromptForInitIntegrations, } from '../init-prompt.js';
+import { promptForInitIntegrations, promptScopeConfirmation, promptWorkspaceSetup, shouldPromptForInitIntegrations, } from '../init-prompt.js';
 import { detectMachineIntegrationRecommendations, recommendedIntegrationsForInit, } from '../init-recommendations.js';
 import { renderInitSummary } from '../init-summary.js';
+import { countScopeFiles, detectWorkspaces } from '../workspace-detection.js';
 export function registerInitCommand(program) {
     program
         .command('init')
@@ -33,6 +34,26 @@ export function registerInitCommand(program) {
             console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
         }
         let config = await loadConfig(workspace);
+        // Workspace detection — only for fresh init, non-destructive
+        const workspaceInfo = await detectWorkspaces(workspace.rootPath);
+        if (workspaceInfo && Object.keys(config.domainHints).length === 0) {
+            const result = await promptWorkspaceSetup(workspaceInfo);
+            if (result.applyDomains && result.domainHints) {
+                config = { ...config, domainHints: result.domainHints };
+                await saveConfig(workspace, config);
+            }
+        }
+        // Pre-scan scope check — fast file count before heavy scan
+        const fileCount = await countScopeFiles(workspace.rootPath, config);
+        const scopeResult = await promptScopeConfirmation(fileCount);
+        if (!scopeResult.proceed) {
+            console.log('Init cancelled. Edit .kgraph/config.yaml to adjust scope, then run `kgraph init` again.');
+            return;
+        }
+        if (scopeResult.narrowedInclude) {
+            config = { ...config, include: scopeResult.narrowedInclude };
+            await saveConfig(workspace, config);
+        }
         const previousMaps = await readMaps(workspace);
         const result = await scanRepository(workspace.rootPath, config, {
             files: previousMaps.fileMap.files,

package/dist/cli/commands/workflow.js

@@ -3,8 +3,8 @@ import { concludeTopic } from '../../cognition/conclusion.js';
 import { loadConfig } from '../../config/config.js';
 import { queryContext } from '../../context/context-query.js';
 import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
-import { getWorkingTreeChanges } from '../../scanner/git-utils.js';
 import { shouldExclude } from '../../scanner/file-classifier.js';
+import { getWorkingTreeChanges } from '../../scanner/git-utils.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
 import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
 import { listInboxNotes } from '../../storage/cognition-store.js';
@@ -104,8 +104,7 @@ export async function runDefaultWorkflow(query, options = {}) {
                 atomsProcessed: update.processed.length,
                 pendingInbox: pendingInbox.length,
                 activeAtoms: activeAtoms.length,
-                needsReviewAtoms: atoms.filter((atom) => atom.status === 'needs-review')
-                    .length,
+                needsReviewAtoms: atoms.filter((atom) => atom.status === 'needs-review').length,
                 staleAtoms: atoms.filter((atom) => atom.status === 'stale').length,
                 highConfidenceMissingEvidence: activeAtoms.filter((atom) => atom.confidence === 'high' && atom.evidenceRefs.length === 0).length,
                 captureRequired: captureCheck.required,
@@ -250,17 +249,33 @@ function meaningfulTopicOverlap(a, b) {
     const weakTokens = new Set([
         'add',
         'after',
+        'and',
         'behavior',
         'change',
         'changed',
+        'check',
+        'code',
+        'current',
+        'file',
+        'fix',
+        'for',
+        'from',
+        'get',
+        'into',
         'new',
+        'not',
         'old',
         'review',
-        'check',
-        'current',
+        'run',
         'session',
+        'set',
         'smoke',
+        'test',
+        'that',
+        'the',
+        'this',
         'update',
+        'use',
         'with',
     ]);
     const aTokens = new Set(a
@@ -277,12 +292,14 @@ function tokenOverlap(a, b) {
     const aTokens = new Set(a
         .toLowerCase()
         .split(/[^a-z0-9]+/)
-        .filter(Boolean));
-    return b
+        .filter((token) => token.length >= 4));
+    if (aTokens.size === 0)
+        return false;
+    const matches = b
         .toLowerCase()
         .split(/[^a-z0-9]+/)
-        .filter(Boolean)
-        .some((token) => aTokens.has(token));
+        .filter((token) => token.length >= 4 && aTokens.has(token));
+    return matches.length >= 2;
 }
 function matchingInvalidatedAtoms(atoms, topic) {
     const tokens = new Set((topic ?? '')

package/dist/cli/index.js

@@ -130,6 +130,8 @@ function isCliEntrypoint() {
             realpathSync(process.argv[1]));
     }
     catch {
-        return import.meta.url === `file://${process.argv[1]}`;
+        const argv1 = process.argv[1].replace(/\\/g, '/');
+        return (import.meta.url === `file://${argv1}` ||
+            import.meta.url === `file:///${argv1}`);
     }
 }

package/dist/cli/init-prompt.d.ts

@@ -1,8 +1,27 @@
-import type { IntegrationConfig, IntegrationName } from '../types/config.js';
+import type { DomainHint, IntegrationConfig, IntegrationName } from '../types/config.js';
 import type { InitIntegrationRecommendation } from './init-recommendations.js';
+import type { WorkspaceInfo } from './workspace-detection.js';
 export declare function shouldPromptForInitIntegrations(options: {
     explicitIntegrationsRequested: boolean;
     configuredIntegrations: Pick<IntegrationConfig, 'name'>[];
     interactive?: boolean;
 }): boolean;
 export declare function promptForInitIntegrations(recommendations: InitIntegrationRecommendation[]): Promise<IntegrationName[]>;
+export interface ScopeConfirmResult {
+    proceed: boolean;
+    narrowedInclude?: string[];
+}
+/**
+ * If file count exceeds threshold, ask user whether to proceed or narrow scope.
+ * For small repos, returns { proceed: true } without prompting.
+ */
+export declare function promptScopeConfirmation(fileCount: number, threshold?: number): Promise<ScopeConfirmResult>;
+export interface WorkspacePromptResult {
+    applyDomains: boolean;
+    domainHints?: Record<string, DomainHint>;
+}
+/**
+ * If a monorepo workspace is detected, offer to configure domain hints.
+ * For simple projects (no workspace detected), skips silently.
+ */
+export declare function promptWorkspaceSetup(info: WorkspaceInfo): Promise<WorkspacePromptResult>;

package/dist/cli/init-prompt.js

@@ -59,3 +59,60 @@ export async function promptForInitIntegrations(recommendations) {
 function isInteractiveTerminal() {
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 }
+/**
+ * If file count exceeds threshold, ask user whether to proceed or narrow scope.
+ * For small repos, returns { proceed: true } without prompting.
+ */
+export async function promptScopeConfirmation(fileCount, threshold = 500) {
+    if (fileCount <= threshold || !isInteractiveTerminal()) {
+        return { proceed: true };
+    }
+    const action = await clack.select({
+        message: `Found ${fileCount.toLocaleString()} files in scope`,
+        options: [
+            { value: 'proceed', label: 'Continue with all files' },
+            {
+                value: 'narrow',
+                label: 'Narrow to src/ only',
+                hint: 'include: ["src/**"]',
+            },
+            { value: 'cancel', label: "Cancel — I'll edit config.yaml manually" },
+        ],
+    });
+    if (clack.isCancel(action) || action === 'cancel') {
+        return { proceed: false };
+    }
+    if (action === 'narrow') {
+        return { proceed: true, narrowedInclude: ['src/**'] };
+    }
+    return { proceed: true };
+}
+/**
+ * If a monorepo workspace is detected, offer to configure domain hints.
+ * For simple projects (no workspace detected), skips silently.
+ */
+export async function promptWorkspaceSetup(info) {
+    if (!isInteractiveTerminal()) {
+        return { applyDomains: false };
+    }
+    const packageNames = info.packages.map((p) => p.name).join(', ');
+    const action = await clack.select({
+        message: `Detected ${info.tool} workspace (${info.packages.length} packages: ${packageNames})`,
+        options: [
+            {
+                value: 'apply',
+                label: 'Configure domain hints from packages',
+                hint: 'context packs will prefer the active package',
+            },
+            { value: 'skip', label: 'Skip — scan everything flat' },
+        ],
+    });
+    if (clack.isCancel(action) || action === 'skip') {
+        return { applyDomains: false };
+    }
+    const hints = {};
+    for (const pkg of info.packages) {
+        hints[pkg.name] = { paths: [pkg.path + '/**'] };
+    }
+    return { applyDomains: true, domainHints: hints };
+}

package/dist/cli/workspace-detection.d.ts

@@ -0,0 +1,23 @@
+import type { DomainHint, KGraphConfig } from '../types/config.js';
+export interface WorkspaceInfo {
+    tool: string;
+    packages: WorkspacePackage[];
+}
+export interface WorkspacePackage {
+    name: string;
+    path: string;
+}
+/**
+ * Detect monorepo workspace tools and their packages.
+ * Returns null for simple single-package projects.
+ */
+export declare function detectWorkspaces(rootPath: string): Promise<WorkspaceInfo | null>;
+/**
+ * Convert detected workspace packages into domainHints.
+ */
+export declare function workspacesToDomainHints(info: WorkspaceInfo): Record<string, DomainHint>;
+/**
+ * Quick file count using fast-glob (no content read).
+ * Used to warn about large scopes before a full scan.
+ */
+export declare function countScopeFiles(rootPath: string, config: KGraphConfig): Promise<number>;

package/dist/cli/workspace-detection.js

@@ -0,0 +1,169 @@
+import fg from 'fast-glob';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildFastGlobIgnore, readGitignorePatterns, } from '../scanner/file-classifier.js';
+import { pathExists } from '../storage/kgraph-paths.js';
+/**
+ * Detect monorepo workspace tools and their packages.
+ * Returns null for simple single-package projects.
+ */
+export async function detectWorkspaces(rootPath) {
+    // pnpm
+    const pnpmPath = path.join(rootPath, 'pnpm-workspace.yaml');
+    if (await pathExists(pnpmPath)) {
+        const packages = await resolvePnpmPackages(rootPath, pnpmPath);
+        if (packages.length > 1)
+            return { tool: 'pnpm', packages };
+    }
+    // nx
+    const nxPath = path.join(rootPath, 'nx.json');
+    if (await pathExists(nxPath)) {
+        const packages = await resolveNxPackages(rootPath);
+        if (packages.length > 1)
+            return { tool: 'nx', packages };
+    }
+    // lerna
+    const lernaPath = path.join(rootPath, 'lerna.json');
+    if (await pathExists(lernaPath)) {
+        const packages = await resolveLernaPackages(rootPath, lernaPath);
+        if (packages.length > 1)
+            return { tool: 'lerna', packages };
+    }
+    // rush
+    const rushPath = path.join(rootPath, 'rush.json');
+    if (await pathExists(rushPath)) {
+        const packages = await resolveRushPackages(rootPath, rushPath);
+        if (packages.length > 1)
+            return { tool: 'rush', packages };
+    }
+    // npm/yarn workspaces (package.json)
+    const pkgPath = path.join(rootPath, 'package.json');
+    if (await pathExists(pkgPath)) {
+        const packages = await resolveNpmWorkspaces(rootPath, pkgPath);
+        if (packages.length > 1)
+            return { tool: 'npm', packages };
+    }
+    return null;
+}
+/**
+ * Convert detected workspace packages into domainHints.
+ */
+export function workspacesToDomainHints(info) {
+    const hints = {};
+    for (const pkg of info.packages) {
+        hints[pkg.name] = { paths: [pkg.path + '/**'] };
+    }
+    return hints;
+}
+/**
+ * Quick file count using fast-glob (no content read).
+ * Used to warn about large scopes before a full scan.
+ */
+export async function countScopeFiles(rootPath, config) {
+    const gitignorePatterns = await readGitignorePatterns(rootPath);
+    const allExcludes = [...config.exclude, ...gitignorePatterns];
+    const entries = await fg(config.include, {
+        cwd: rootPath,
+        dot: true,
+        onlyFiles: true,
+        unique: true,
+        ignore: buildFastGlobIgnore(allExcludes),
+        stats: false,
+    });
+    return entries.length;
+}
+// --- Resolvers ---
+async function resolvePnpmPackages(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        // Simple YAML parsing for packages: array
+        const lines = content.split(/\r?\n/);
+        const globs = [];
+        let inPackages = false;
+        for (const line of lines) {
+            if (/^packages:/i.test(line.trim())) {
+                inPackages = true;
+                continue;
+            }
+            if (inPackages) {
+                const match = line.match(/^\s+-\s+['"]?([^'"]+)['"]?\s*$/);
+                if (match) {
+                    globs.push(match[1]);
+                }
+                else if (/^\S/.test(line) && line.trim().length > 0) {
+                    break;
+                }
+            }
+        }
+        if (globs.length === 0)
+            globs.push('packages/*');
+        return await resolvePackageGlobs(rootPath, globs);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveNxPackages(rootPath) {
+    // Nx projects live in common dirs
+    const candidates = ['apps/*', 'libs/*', 'packages/*'];
+    return await resolvePackageGlobs(rootPath, candidates);
+}
+async function resolveLernaPackages(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        const globs = Array.isArray(parsed.packages)
+            ? parsed.packages
+            : ['packages/*'];
+        return await resolvePackageGlobs(rootPath, globs);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveRushPackages(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed.projects))
+            return [];
+        return parsed.projects
+            .filter((p) => p.projectFolder)
+            .map((p) => ({
+            name: p.packageName || path.basename(p.projectFolder),
+            path: p.projectFolder,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveNpmWorkspaces(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        const workspaces = parsed.workspaces;
+        if (!workspaces)
+            return [];
+        const globs = Array.isArray(workspaces)
+            ? workspaces
+            : (workspaces.packages ?? []);
+        if (globs.length === 0)
+            return [];
+        return await resolvePackageGlobs(rootPath, globs);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolvePackageGlobs(rootPath, globs) {
+    const dirs = await fg(globs, {
+        cwd: rootPath,
+        onlyDirectories: true,
+        deep: 1,
+    });
+    return dirs.sort().map((dir) => ({
+        name: path.basename(dir),
+        path: dir.split(path.sep).join('/'),
+    }));
+}

package/dist/integrations/adapters/copilot.js

@@ -16,7 +16,11 @@ ${numberedWorkflow('copilot')}
 description: Use KGraph persistent repo intelligence — runs kgraph before answering to provide file maps, symbols, relationships, and durable knowledge atoms.
 ---
 
-## KGraph Workflow
+# KGraph Agent
+
+You are the KGraph agent. You use the \`kgraph\` CLI via the terminal to provide persistent repo intelligence before answering questions or making edits.
+
+## Workflow
 
 ${numberedWorkflow('copilot')}
 `,

package/dist/integrations/agent-skills.js

@@ -45,7 +45,7 @@ name: kgraph-pack
 description: Build a budget-aware KGraph context pack
 ---
 
-Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+Run \`kgraph pack "<topic>" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons. When a symbol item includes an \`excerpt\` field, you already have the source — do not read that file for the symbol.
 `,
     },
     {
@@ -75,7 +75,7 @@ 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.
+Run \`kgraph blame <atom-id>\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
 `,
     },
     {
@@ -127,7 +127,7 @@ name: kgraph-conclude
 description: Store a typed durable KGraph engineering conclusion
 ---
 
-Prefer \`kgraph "<topic>" --capture "$ARGUMENTS" --capture-file <path> --capture-symbol <name>\` when the session produced reusable engineering knowledge. Use low-level \`kgraph conclude "$ARGUMENTS"\` only when the user explicitly asks for the conclude command. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Add file or symbol evidence whenever possible; high-confidence conclusions require evidence. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
+Prefer \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\` when the session produced reusable engineering knowledge. Use low-level \`kgraph conclude "<topic>" --note "<conclusion>"\` only when the user explicitly asks for the conclude command. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Add file or symbol evidence whenever possible; high-confidence conclusions require evidence. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
 `,
     },
     {
@@ -137,7 +137,7 @@ 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.
+Run \`kgraph impact "<file-or-symbol>"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
 `,
     },
     {
@@ -157,7 +157,7 @@ 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.
+Run \`kgraph history\` or \`kgraph history "<topic>"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
 `,
     },
 ];

package/dist/integrations/instruction-blocks.js

@@ -9,7 +9,7 @@ export function upsertManagedBlock(content, integrationName, instructions) {
     if (pattern.test(content)) {
         return content.replace(pattern, block);
     }
-    return normalized ? `${block}\n\n${normalized}\n` : `${block}\n`;
+    return normalized ? `${normalized}\n\n${block}\n` : `${block}\n`;
 }
 export function removeManagedBlock(content, integrationName) {
     return (content
@@ -25,7 +25,7 @@ function renderManagedBlock(integrationName, instructions) {
     ].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)}\\r?\\n?`, 'm');
 }
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/dist/integrations/workflow-steps.d.ts

@@ -7,7 +7,7 @@ export interface WorkflowOptions {
     sessionQualifier?: string;
 }
 /**
- * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Returns the numbered workflow for skill/agent/command files.
  * Used by: copilot (agent file), codex (skill file), claude-code (command file).
  */
 export declare function numberedWorkflow(agentName: string, options?: WorkflowOptions): string;

package/dist/integrations/workflow-steps.js

@@ -8,49 +8,41 @@ 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.`;
-function inboxStep(agentName) {
-    return `If the previous command output contains "pending inbox" or a \`pendingInbox\` field with count > 0, you MUST run \`kgraph "<topic>" --agent ${agentName}\` or \`kgraph update\` immediately before proceeding. Do not skip this step.`;
-}
-function packStep(agentName) {
-    return `For normal coding context, treat \`kgraph pack "<task>" --budget 8000 --json --agent ${agentName}\` as the machine-readable context contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files.`;
-}
+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.`;
+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.`;
+const SCAN_STEP = `After bulk file creation, deletion, or rename (3+ files), run \`kgraph scan\` before the next \`kgraph pack\` so maps stay accurate.`;
 function smartRootStep(agentName) {
     return `Use the root workflow when refresh or memory processing matters: run \`kgraph "<topic>" --agent ${agentName}\` to refresh maps, process inbox notes, and return a briefing; run \`kgraph "<topic>" --final --agent ${agentName}\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent ${agentName}\` when the final check requires durable knowledge.`;
 }
-const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
-const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files. Use \`rg --files\` and quoted paths when a path must be located.`;
-const VERIFY_EDIT_STEP = `After editing, verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.`;
-const ROUTING_STEP = `Route explicit KGraph requests to the matching command before any default context lookup: history/prior work -> \`kgraph history "<topic>"\`; inbox/pending capture/process notes/update cognition -> \`kgraph "<topic>"\` or \`kgraph update\`; remembered knowledge/atoms/provenance -> \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\`; setup/health -> \`kgraph doctor\`.`;
 function sessionStep(agentName, qualifier) {
     const base = `Track meaningful session activity with \`kgraph session start --agent ${agentName}\`, \`kgraph session read <path> --agent ${agentName}\`, \`kgraph session write <path> --agent ${agentName}\`, and \`kgraph session end --agent ${agentName} --conclude --topic "<topic>"\` when durable session memory is useful`;
     return qualifier ? `${base} ${qualifier}.` : `${base}.`;
 }
 /**
- * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Returns the numbered workflow for skill/agent/command files.
  * Used by: copilot (agent file), codex (skill file), claude-code (command file).
  */
 export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
 2. {{KGRAPH_CONTEXT_POLICY}}
-3. ${inboxStep(agentName)}
-4. ${ROUTING_STEP}
-5. Use the returned files, symbols, relationships, and cognition before broad exploration.
-6. ${EXPLORATION_BOUNDARY_STEP}
-7. ${VERIFY_EDIT_STEP}
-8. ${smartRootStep(agentName)}
-9. ${packStep(agentName)}
-10. ${KNOWLEDGE_STEP}
-11. ${DOCTOR_STEP}
-12. ${STALE_STEP}
-13. ${sessionStep(agentName, options.sessionQualifier)}
-14. ${IMPACT_STEP}
+3. When the pack includes a symbol with an \`excerpt\` field, you already have the source code — do not read that file again for that symbol. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
+4. ${EXPLORATION_BOUNDARY_STEP}
+5. ${VERIFY_EDIT_STEP}
+6. ${smartRootStep(agentName)}
+7. ${KNOWLEDGE_STEP}
+8. ${DOCTOR_STEP}
+9. ${STALE_STEP}
+10. ${SCAN_STEP}
+11. ${sessionStep(agentName, options.sessionQualifier)}
+12. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-15. ${REPAIR_STEP}
-16. ${COMPACT_STEP}
-17. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-18. ${HISTORY_STEP}`;
+13. ${REPAIR_STEP}
+14. ${COMPACT_STEP}
+15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph locally with PNG export.
+16. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -58,20 +50,19 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
-- ${inboxStep(agentName)}
-- ${ROUTING_STEP}
+- When the pack includes a symbol with an \`excerpt\` field, you already have the source code — do not read that file again for that symbol. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}
 - ${smartRootStep(agentName)}
-- ${packStep(agentName)}
 - ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}
 - ${STALE_STEP}
+- ${SCAN_STEP}
 - ${sessionStep(agentName, options.sessionQualifier)}
 - ${IMPACT_STEP}
 {{KGRAPH_CAPTURE_POLICY}}
 - ${REPAIR_STEP}
 - ${COMPACT_STEP}
-- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
+- Run \`kgraph visualize\` to open the interactive dependency graph locally with PNG export.
 - ${HISTORY_STEP}`;
 }

package/dist/knowledge/atom-store.js

@@ -33,7 +33,7 @@ export async function readAtomsFile(workspace) {
 }
 export function parseAtomsJsonl(raw) {
     const atoms = [];
-    for (const [index, line] of raw.split('\n').entries()) {
+    for (const [index, line] of raw.split(/\r?\n/).entries()) {
         if (!line.trim())
             continue;
         try {

package/dist/visualization/html-template.js

@@ -1,5 +1,5 @@
 export function renderHtml(graphData, rootPath) {
-    const repoName = escAttr(rootPath.split('/').pop() ?? 'Repository');
+    const repoName = escAttr(rootPath.split(/[\\/]/).pop() ?? 'Repository');
     const { meta } = graphData;
     // Prevent </script> tag injection from embedded JSON
     const safeData = JSON.stringify(graphData).replace(/<\/script>/gi, '<\\/script>');

package/package.json

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