@kentwynn/kgraph 0.2.15 → 0.2.16

package/README.md

@@ -4,6 +4,8 @@ Persistent repository intelligence for AI coding tools.
 
 KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable knowledge atoms from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
 
+The CLI presents this as **Atom Core**: lightweight local atoms plus deterministic repo maps, context packs, and session history that remain inspectable under `.kgraph/`.
+
 ## The Workflow
 
 Use KGraph in two steps:

package/dist/cli/commands/context.js

@@ -25,11 +25,20 @@ export function registerContextCommand(program) {
     }));
 }
 export function renderContextMarkdown(response) {
-    const lines = [`# KGraph Context`, ``, `Query: ${response.query}`, ``];
-    lines.push('## Matched Domains', '');
-    lines.push(...formatList(response.matchedDomains.map((item) => `- ${item.item.name} because ${formatReasons(item.reasons)}`)));
-    lines.push('', '## Relevant Files', '');
-    lines.push(...formatList(response.relevantFiles.map((item) => {
+    const lines = [
+        `KGraph Context · ${response.query}`,
+        `local-first · deterministic · inspectable`,
+        ``,
+        `● Signal`,
+        `  confidence   ${contextConfidence(response)}`,
+        `  source       ${contextSources(response).join(' + ') || 'file map'}`,
+        `  warnings     ${response.warnings.length > 0 ? response.warnings.length : 'none'}`,
+        ``,
+    ];
+    lines.push('● Matched Domains', '');
+    lines.push(...formatList(response.matchedDomains.map((item) => atomLine(item.item.name, formatReasons(item.reasons)))));
+    lines.push('', '● Source', '');
+    lines.push(...formatList(limited(response.relevantFiles, 5).map((item) => {
         const f = item.item;
         const meta = [
             f.language,
@@ -37,32 +46,34 @@ export function renderContextMarkdown(response) {
         ]
             .filter(Boolean)
             .join(', ');
-        return `- ${f.path}${meta ? ` [${meta}]` : ''} because ${formatReasons(item.reasons)}`;
+        return atomLine(`${f.path}${meta ? ` [${meta}]` : ''}`, formatReasons(item.reasons));
     })));
-    lines.push('', '## Relevant Symbols', '');
-    lines.push(...formatList(response.relevantSymbols.map((item) => {
+    appendMore(lines, response.relevantFiles.length, 5, 'source item');
+    lines.push('', '● Symbols', '');
+    lines.push(...formatList(limited(response.relevantSymbols, 6).map((item) => {
         const s = item.item;
         const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(item.reasons)}`;
+        return atomLine(`${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`, formatReasons(item.reasons));
     })));
-    lines.push('', '## Relevant Cognition', '');
-    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}] because ${formatReasons(item.reasons)}`)));
-    lines.push('', '## Relationships', '');
-    lines.push(...formatGroupedRelationships(response.relationships, response.relationshipExplanations));
-    lines.push('', '## Nearby Symbols (1-hop imports)', '');
+    appendMore(lines, response.relevantSymbols.length, 6, 'symbol');
+    lines.push('', '● Atoms', '');
+    lines.push(...formatList(response.relevantCognition.map((item) => atomLine(`${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}]`, formatReasons(item.reasons)))));
+    lines.push('', '● Graph', '');
+    lines.push(...formatGroupedRelationships(relevantGraphRelationships(response), response.relationshipExplanations));
+    lines.push('', '● Nearby Symbols (1-hop imports)', '');
     lines.push(...formatList(nearbySymbolItems(response).map(({ symbol: s, reasons }) => {
         const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(reasons)}`;
+        return atomLine(`${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`, formatReasons(reasons));
     })));
-    lines.push('', '## Stale References', '');
-    lines.push(...formatList(response.staleReferences.map((ref) => `- ${ref}`)));
-    lines.push('', '## Recent Git Changes', '');
+    lines.push('', '● Stale References', '');
+    lines.push(...formatList(response.staleReferences.map((ref) => `  ◌ ${ref}`)));
+    lines.push('', '● Recent Git Changes', '');
     if (response.gitChanges && response.gitChanges.length > 0) {
         const staged = response.gitChanges.filter((c) => c.status === 'staged');
         const unstaged = response.gitChanges.filter((c) => c.status === 'unstaged');
@@ -70,22 +81,29 @@ export function renderContextMarkdown(response) {
         if (staged.length > 0) {
             lines.push('Staged:');
             for (const c of staged)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
         if (unstaged.length > 0) {
             lines.push('Unstaged:');
             for (const c of unstaged)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
         if (recent.length > 0) {
             lines.push('Recent commits:');
             for (const c of recent)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
     }
     else {
         lines.push('- None');
     }
+    lines.push('', '● Next', '');
+    if (response.relevantFiles.some((item) => (item.item.tokenEstimate ?? 0) > 4000)) {
+        lines.push(`  use budgeted source ranges: kgraph pack "${response.query}" --budget 4000`);
+    }
+    else {
+        lines.push(`  read the ranked source, edit, verify, conclude only if durable knowledge changed`);
+    }
     return lines.join('\n');
 }
 function formatGroupedRelationships(relationships, explanations) {
@@ -105,33 +123,49 @@ function formatGroupedRelationships(relationships, explanations) {
     const lines = [];
     if (imports.length > 0) {
         lines.push('Imports:');
-        for (const r of imports) {
+        for (const r of imports.slice(0, 6)) {
             lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, imports.length, 6, 'import edge');
     }
     if (calls.length > 0) {
         lines.push('Calls:');
-        for (const r of calls) {
+        for (const r of calls.slice(0, 6)) {
             lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, calls.length, 6, 'call edge');
     }
     if (contains.length > 0) {
         lines.push('Contains:');
-        for (const r of contains) {
+        for (const r of contains.slice(0, 6)) {
             lines.push(`  ${r.sourceId} contains ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, contains.length, 6, 'containment edge');
     }
     if (other.length > 0) {
         lines.push('Other:');
-        for (const r of other) {
+        for (const r of other.slice(0, 6)) {
             lines.push(`  ${r.sourceId} ${r.relationshipType} ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, other.length, 6, 'graph edge');
     }
     return lines.length > 0 ? lines : ['- None'];
 }
 function formatList(items) {
     return items.length > 0 ? items : ['- None'];
 }
+function limited(items, count) {
+    return items.slice(0, count);
+}
+function appendMore(lines, total, shown, label) {
+    const remaining = total - shown;
+    if (remaining > 0) {
+        lines.push(`  ◌ ${remaining} more ${label}${remaining === 1 ? '' : 's'} omitted from display`);
+    }
+}
+function atomLine(title, detail) {
+    return `  ● ${title}\n    because ${detail}`;
+}
 function formatReasons(reasons) {
     if (reasons.length === 0) {
         return 'it is near the query';
@@ -151,6 +185,39 @@ function nearbySymbolItems(response) {
         reasons: ['exported symbol from 1-hop import'],
     }));
 }
+function relevantGraphRelationships(response) {
+    const anchorPaths = response.relevantFiles
+        .filter((item) => !item.reasons.some((reason) => reason.includes('generic path-only match penalty')))
+        .slice(0, 3)
+        .map((item) => item.item.path);
+    const paths = anchorPaths.length > 0
+        ? anchorPaths
+        : response.relevantFiles.slice(0, 1).map((item) => item.item.path);
+    if (paths.length === 0)
+        return response.relationships;
+    return response.relationships.filter((relationship) => paths.some((path) => relationship.sourceId.includes(path) ||
+        relationship.targetId.includes(path)));
+}
+function contextConfidence(response) {
+    const confidence = response.relevantCognition
+        .map((item) => item.item.confidence)
+        .find(Boolean);
+    return confidence ?? (response.relevantFiles.length > 0 ? 'medium' : 'low');
+}
+function contextSources(response) {
+    const sources = [];
+    if (response.relevantCognition.length > 0)
+        sources.push('atom');
+    if ((response.gitChanges ?? []).length > 0)
+        sources.push('git change');
+    if (response.relevantSymbols.length > 0)
+        sources.push('symbol');
+    if (relevantGraphRelationships(response).length > 0)
+        sources.push('graph');
+    if (response.relevantFiles.length > 0)
+        sources.push('file');
+    return sources;
+}
 function formatRelationshipReason(relationship, reasonsByRelationship) {
     const reasons = reasonsByRelationship.get(relationshipKey(relationship));
     return reasons && reasons.length > 0

package/dist/cli/help.js

@@ -1,31 +1,32 @@
 import { Chalk } from 'chalk';
-import figlet from 'figlet';
 export function renderRootHelp(useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
-    const logo = renderLogo();
+    const accent = atomAccent(theme);
     return [
         '',
-        theme.hex('#7dd3fc').bold(logo),
+        renderAtomLogo(theme),
         '',
-        `  ${theme.bold('KGraph')} ${theme.dim('Persistent repo intelligence for AI coding tools')}`,
+        renderSignalPanel(theme, [
+            ['purpose', 'durable engineering memory for AI coding tools'],
+            ['storage', '.kgraph/ atoms, maps, indexes, and session history'],
+            ['stance', 'local-first · deterministic-first · inspectable'],
+            ['agents', 'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline'],
+        ]),
         '',
-        `  ${theme.hex('#c084fc')('Build a local knowledge layer that helps Codex, Copilot, Cursor,')}`,
-        `  ${theme.hex('#c084fc')('Claude Code, Gemini, Windsurf, and Cline reuse repo intelligence.')}`,
-        '',
-        theme.bold('Usage'),
+        sectionTitle(theme, `${accent} Usage`),
         '  kgraph [topic]',
         '  kgraph <command> [options]',
         '',
-        theme.bold('Start'),
+        sectionTitle(theme, `${accent} Start`),
         command('init', 'Required once: create .kgraph/ workspace'),
         command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
         '',
-        theme.bold('Daily workflow'),
+        sectionTitle(theme, `${accent} Daily workflow`),
         command('kgraph', 'Refresh scan maps and process pending capture notes'),
         command('kgraph "auth token refresh"', 'Refresh everything and return compact context for a topic'),
         '',
-        theme.bold('Workflows'),
+        sectionTitle(theme, `${accent} Workflows`),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
         command('session', 'Show agent read/write activity and token estimates'),
         command('session read src/auth.ts --agent codex', 'Record an agent file read'),
@@ -48,7 +49,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
         '',
-        theme.bold('Integrations'),
+        sectionTitle(theme, `${accent} Integrations`),
         command('integrate list', 'Show configured AI tool integrations'),
         command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
         command('integrate add copilot --mode smart', 'Run KGraph for repo-specific Copilot work only'),
@@ -56,21 +57,24 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
         '',
-        theme.bold('Options'),
+        sectionTitle(theme, `${accent} Options`),
         command('-V, --version', 'Show version'),
         command('-h, --help', 'Show this help'),
         '',
-        `${theme.yellow('Examples')}`,
+        sectionTitle(theme, `${accent} Examples`),
         '  kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline',
         '  kgraph "blog admin token usage"',
+        '  kgraph pack "about page update" --budget 4000',
         '  kgraph doctor',
         '',
         theme.dim('Docs: https://github.com/kentwynn/KGraph#readme'),
+        theme.dim('Powered by Kent Wynn: https://kentwynn.com'),
         '',
     ].join('\n');
 }
 export function renderWorkflowBanner(stats, useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
+    const accent = atomAccent(theme);
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
     const integrationLine = stats.integrations && stats.integrations.length > 0
         ? stats.integrations
@@ -81,11 +85,11 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         : 'none configured';
     return [
         '',
-        theme.hex('#7dd3fc').bold(renderLogo()),
+        renderAtomLogo(theme),
         '',
-        `  ${theme.bold('KGraph')} ${theme.dim('repo intelligence refreshed')}`,
+        `  ${theme.bold('KGraph')} ${theme.dim('· repo intelligence refreshed')}`,
         '',
-        theme.bold('Refresh Complete'),
+        sectionTitle(theme, `${accent} Refresh Complete`),
         command('files', String(stats.files) +
             (stats.skippedFiles
                 ? ` (${stats.skippedFiles} unchanged, skipped)`
@@ -94,7 +98,7 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('capture notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),
         '',
-        theme.bold('Next'),
+        sectionTitle(theme, `${accent} Next`),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
         command('kgraph doctor --quality', 'Check atom quality'),
@@ -104,17 +108,27 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('kgraph --help', 'Show all commands'),
     ].join('\n');
 }
-function renderLogo() {
-    try {
-        return figlet.textSync('KGraph', {
-            font: 'ANSI Shadow',
-            horizontalLayout: 'default',
-            verticalLayout: 'default',
-        });
-    }
-    catch {
-        return 'KGraph';
-    }
+function renderAtomLogo(theme) {
+    const title = `${theme.hex('#38bdf8').bold('KGraph')} ${theme.dim('·')} ${theme.hex('#c084fc').bold('Atom Core')}`;
+    const atom = theme.hex('#22d3ee').bold('⚛');
+    const memory = theme.hex('#a78bfa')('persistent repo intelligence for AI coding tools');
+    return [
+        `  ${atom}  ${theme.dim('atoms · evidence · context packs')}`,
+        `     ${title}`,
+        `     ${memory}`,
+    ].join('\n');
+}
+function renderSignalPanel(theme, rows) {
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    return rows
+        .map(([label, value]) => `  ${theme.hex('#22d3ee')('●')} ${theme.bold(label.padEnd(labelWidth))}  ${theme.dim(value)}`)
+        .join('\n');
+}
+function sectionTitle(theme, title) {
+    return theme.bold(title);
+}
+function atomAccent(theme) {
+    return theme.hex('#22d3ee')('●');
 }
 function supportsColor() {
     return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -47,7 +47,6 @@
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
-    "figlet": "^1.11.0",
     "tree-sitter-c": "^0.24.1",
     "tree-sitter-c-sharp": "^0.23.5",
     "tree-sitter-cpp": "^0.23.4",