@kentwynn/kgraph 0.2.22 → 0.2.24

package/README.md

@@ -41,22 +41,33 @@ The CLI presents this as **Atom Core**: lightweight local atoms plus determinist
 
 ## The Workflow
 
-Use KGraph in two steps:
+Use KGraph with one setup command and one normal daily command:
 
 ```bash
-# Required once per repository
-kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline
+# Required once per repository.
+# Creates .kgraph/, runs the first scan, and detects likely AI tools.
+kgraph init
 
-# Normal daily command
+# Normal daily command.
+# Refreshes maps, processes pending capture notes, and returns focused context.
 kgraph "auth token refresh"
 ```
 
-That second command runs the full practical workflow:
+AI tool integrations are optional. During `kgraph init`, KGraph detects likely local tools such as Codex, Copilot, Claude Code, and Gemini, then prompts or prints a suggested `kgraph integrate add ...` command. You can accept the recommendation, choose custom integrations, skip the step, or configure them later.
+
+If you already know exactly which integrations you want, you can pass them during init:
+
+```bash
+kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline
+```
+
+The daily command runs the full practical workflow:
 
 1. Refreshes the repository scan.
 2. Updates file, symbol, import, and relationship maps.
 3. Processes any Markdown capture notes waiting in `.kgraph/inbox/` into knowledge atoms.
-4. Returns compact context for the topic you asked about.
+4. Reports memory health and actionable next steps.
+5. Returns compact context for the topic you asked about.
 
 You can also run just:
 
@@ -134,10 +145,11 @@ KGraph's core functionality is free and local-first. It does not require account
 From the root of a repository:
 
 ```bash
-# 1. Create the local KGraph workspace
+# 1. Create the local KGraph workspace and run the first scan
 kgraph init
 
-# 2. Optional: connect AI tools so they know the KGraph workflow
+# 2. Optional: accept detected AI tool recommendations during init,
+# or add integrations later when you want KGraph-managed instructions
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
 
 # 3. Run the normal workflow for a topic
@@ -147,7 +159,7 @@ kgraph "auth token refresh"
 kgraph doctor
 ```
 
-`kgraph init` now scans once, then prints relevant next steps. When KGraph can detect likely AI tools on the machine, it recommends matching integrations.
+`kgraph init` scans once, prints repo language coverage, detects likely local AI tools, and recommends matching integrations. Integrations are still optional: they only write local instruction files so tools know when to run KGraph. They do not start background agents or call AI providers.
 
 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`.
 
@@ -183,13 +195,13 @@ This is optional. Claude Code can use generated hook scripts for automatic captu
 kgraph init
 ```
 
-Required once per repo. Creates `.kgraph/`, writes the local config, runs the first scan, and prints suggested next actions based on the detected repo languages and likely local AI tools.
+Required once per repo. Creates `.kgraph/`, writes the local config, initializes the knowledge store, runs the first scan, detects likely local AI tools, and prints suggested next actions based on repo languages and detected tools.
 
 ```bash
 kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline
 ```
 
-Initializes KGraph and writes local instruction files for supported AI tools.
+Initializes KGraph and immediately writes local instruction files for the named AI tools. This is optional; plain `kgraph init` can detect likely tools and recommend or prompt for integrations instead.
 
 ```bash
 kgraph "some topic"
@@ -356,6 +368,10 @@ Show processed capture history. Add a query to find historical work by title, su
 
 KGraph integrations are local files. They do not start background agents, call AI providers, or send data anywhere.
 
+You do not need integrations to use KGraph manually. They are useful when you want Codex, Copilot, Cursor, Claude Code, Gemini, Windsurf, or Cline to see repo-local KGraph workflow instructions automatically.
+
+`kgraph init` detects likely local tools and recommends integrations when possible. You can also manage them explicitly:
+
 ```bash
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
 kgraph integrate add copilot --mode smart
@@ -424,9 +440,17 @@ KGraph deeply scans:
 - Java and Kotlin
 - C and C++
 - C#
+- PHP
+- Ruby
+- Shell
+- SQL
 
 Other languages keep practical file, import, and symbol depth without full call graph analysis. Common file types still appear in the file map with generic metadata, so context queries can still point to docs, config, SQL, CSS, HTML, YAML, and similar files.
 
+KGraph also extracts basic symbols/imports for Swift, Terraform/HCL,
+GraphQL, Protocol Buffers, Lua, Dart, Elixir, Scala, and R. Structured file extraction covers
+YAML, JSON, TOML, Dockerfile/Containerfile, Markdown/MDX, HTML, CSS, SCSS, Sass, Less, and XML.
+
 ## Visualization
 
 ```bash

package/dist/cli/commands/knowledge.js

@@ -1,5 +1,7 @@
-import { readKnowledgeAtoms, updateKnowledgeAtom, } from '../../knowledge/atom-store.js';
+import { atomToCognitionNote, readKnowledgeAtoms, updateKnowledgeAtom, } from '../../knowledge/atom-store.js';
+import { rebuildDomainRecords } from '../../cognition/domain-records.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
 export function registerKnowledgeCommand(program) {
     const knowledge = program
@@ -70,6 +72,7 @@ export function registerKnowledgeCommand(program) {
             provenance: { ...current.provenance, updatedAt: now },
             lifecycle: { ...current.lifecycle, archivedAt: now },
         }));
+        await rebuildActiveDomainRecords(workspace);
         console.log(options.json
             ? JSON.stringify(atom, null, 2)
             : `Archived knowledge atom: ${atom.id}`);
@@ -99,12 +102,23 @@ export function registerKnowledgeCommand(program) {
                 supersedes: [...new Set([...current.lifecycle.supersedes, oldId])],
             },
         }));
+        await rebuildActiveDomainRecords(workspace);
         const result = { old: oldAtom, new: newAtom };
         console.log(options.json
             ? JSON.stringify(result, null, 2)
             : `Superseded ${oldId} with ${newId}`);
     }));
 }
+async function rebuildActiveDomainRecords(workspace) {
+    const maps = await readMaps(workspace);
+    const activeNotes = (await readKnowledgeAtoms(workspace))
+        .filter((atom) => atom.status !== 'archived')
+        .map(atomToCognitionNote);
+    await rebuildDomainRecords(workspace, activeNotes, {
+        files: maps.fileMap.files,
+        symbols: maps.symbolMap.symbols,
+    });
+}
 async function requireAtom(workspace, atomId) {
     const atom = (await readKnowledgeAtoms(workspace)).find((candidate) => candidate.id === atomId);
     if (!atom)

package/dist/cli/help.js

@@ -20,7 +20,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         sectionTitle(theme, `${accent} Start`),
         command('init', 'Required once: create .kgraph/ workspace'),
-        command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
+        command('init --integrations codex,gemini', 'Optional: initialize and connect named AI tools'),
         '',
         sectionTitle(theme, `${accent} Daily workflow`),
         command('kgraph', 'Refresh scan maps and process pending capture notes'),
@@ -68,7 +68,8 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('--capture-symbol <name>', 'Attach symbol evidence to root capture'),
         '',
         sectionTitle(theme, `${accent} Examples`),
-        '  kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline',
+        '  kgraph init',
+        '  kgraph integrate add codex copilot cursor claude-code gemini windsurf cline',
         '  kgraph "blog admin token usage"',
         '  kgraph "blog admin token usage" --final',
         '  kgraph "blog admin token usage" --capture "Author filter now uses display names" --capture-file www/app/blog/page.tsx',

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

@@ -1,7 +1,7 @@
 import type { IntegrationConfig } from '../types/config.js';
 import type { RepositoryFile } from '../types/maps.js';
 import { type InitIntegrationRecommendation } from './init-recommendations.js';
-type CoverageLevel = 'deep' | 'basic' | 'generic';
+type CoverageLevel = 'deep' | 'basic' | 'structured' | 'generic';
 export interface InitLanguageSummary {
     language: string;
     label: string;

package/dist/cli/init-summary.js

@@ -12,15 +12,32 @@ const LANGUAGE_PRESENTATION = {
     c: { label: 'C', coverage: 'deep' },
     cpp: { label: 'C++', coverage: 'deep' },
     csharp: { label: 'C#', coverage: 'deep' },
-    yaml: { label: 'YAML', coverage: 'generic' },
-    json: { label: 'JSON', coverage: 'generic' },
-    toml: { label: 'TOML', coverage: 'generic' },
-    xml: { label: 'XML', coverage: 'generic' },
-    graphql: { label: 'GraphQL', coverage: 'generic' },
-    sql: { label: 'SQL', coverage: 'generic' },
-    shell: { label: 'Shell', coverage: 'generic' },
+    php: { label: 'PHP', coverage: 'deep' },
+    swift: { label: 'Swift', coverage: 'basic' },
+    ruby: { label: 'Ruby', coverage: 'deep' },
+    shell: { label: 'Shell', coverage: 'deep' },
+    lua: { label: 'Lua', coverage: 'basic' },
+    dart: { label: 'Dart', coverage: 'basic' },
+    elixir: { label: 'Elixir', coverage: 'basic' },
+    scala: { label: 'Scala', coverage: 'basic' },
+    r: { label: 'R', coverage: 'basic' },
+    sql: { label: 'SQL', coverage: 'deep' },
+    terraform: { label: 'Terraform/HCL', coverage: 'basic' },
+    graphql: { label: 'GraphQL', coverage: 'basic' },
+    protobuf: { label: 'Protocol Buffers', coverage: 'basic' },
+    yaml: { label: 'YAML', coverage: 'structured' },
+    json: { label: 'JSON', coverage: 'structured' },
+    toml: { label: 'TOML', coverage: 'structured' },
+    dockerfile: { label: 'Dockerfile', coverage: 'structured' },
+    markdown: { label: 'Markdown', coverage: 'structured' },
+    html: { label: 'HTML', coverage: 'structured' },
+    css: { label: 'CSS', coverage: 'structured' },
+    scss: { label: 'SCSS', coverage: 'structured' },
+    sass: { label: 'Sass', coverage: 'structured' },
+    less: { label: 'Less', coverage: 'structured' },
+    xml: { label: 'XML', coverage: 'structured' },
 };
-const EXCLUDED_LANGUAGES = new Set(['unknown', 'markdown', 'restructuredtext']);
+const EXCLUDED_LANGUAGES = new Set(['unknown', 'restructuredtext']);
 export function summarizeInitLanguages(files) {
     const byLabel = new Map();
     for (const file of files) {
@@ -103,6 +120,7 @@ function moreDetailedCoverage(left, right) {
     const rank = {
         deep: 3,
         basic: 2,
+        structured: 2,
         generic: 1,
     };
     return rank[left] >= rank[right] ? left : right;
@@ -113,6 +131,8 @@ function coverageDescription(coverage) {
             return 'deep built-in extraction';
         case 'basic':
             return 'basic built-in extraction';
+        case 'structured':
+            return 'structured file extraction';
         default:
             return 'generic file coverage';
     }

package/dist/cognition/cognition-quality.js

@@ -26,7 +26,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
         unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
         unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
-        duplicateTitleCount: countDuplicateAtomTopics(activeAtoms),
+        duplicateTitleCount: countDuplicateTitles(notes),
         generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         expensiveFileCount: countExpensiveFiles(maps.fileMap),
         highConfidenceMissingEvidenceCount: countHighConfidenceMissingEvidence(activeAtoms),
@@ -148,13 +148,23 @@ export async function repairCognition(workspace, maps, dryRun = false) {
     };
 }
 function countUnresolvedLocalImports(dependencyMap) {
-    return (dependencyMap?.dependencies.filter((dependency) => dependency.kind === 'local' && !dependency.resolvedFile).length ?? 0);
+    return (dependencyMap?.dependencies.filter((dependency) => dependency.kind === 'local' &&
+        !dependency.resolvedFile &&
+        isActionableUnresolvedLocalImport(dependency)).length ?? 0);
+}
+function isActionableUnresolvedLocalImport(dependency) {
+    if (dependency.fromFile.endsWith('/next-env.d.ts') &&
+        dependency.specifier.includes('.next/')) {
+        return false;
+    }
+    return true;
 }
 function countUnresolvedCalls(symbolMap, relationshipMap) {
     const symbolIds = new Set(symbolMap.symbols.map((symbol) => symbol.id));
     const symbolNames = new Set(symbolMap.symbols.map((symbol) => symbol.name));
     return (relationshipMap?.relationships.filter((relationship) => relationship.relationshipType === 'calls' &&
         relationship.targetType === 'symbol' &&
+        relationship.confidence !== 'low' &&
         !symbolIds.has(relationship.targetId) &&
         !symbolNames.has(relationship.targetId) &&
         ![...symbolNames].some((name) => relationship.targetId.endsWith(`#${name}`))).length ?? 0);
@@ -176,12 +186,8 @@ function countDuplicateAtomTopics(atoms) {
     const seen = new Set();
     const duplicates = new Set();
     for (const atom of atoms) {
-        const key = [
-            atom.type,
-            atom.topic.trim().toLowerCase(),
-            atom.claim.trim().toLowerCase(),
-        ].join('\0');
-        if (!atom.topic.trim())
+        const key = atom.topic.trim().toLowerCase();
+        if (!key)
             continue;
         if (seen.has(key))
             duplicates.add(key);

package/dist/cognition/compact.js

@@ -1,7 +1,8 @@
 import { mkdir, rename } from 'node:fs/promises';
 import path from 'node:path';
 import { atomToCognitionNote, refreshKnowledgeAtomStatuses, writeKnowledgeAtoms, } from '../knowledge/atom-store.js';
-import { overwriteDomainRecord, readDomainRecords, slugify, writeCognitionNote, } from '../storage/cognition-store.js';
+import { rebuildDomainRecords } from './domain-records.js';
+import { slugify, writeCognitionNote, } from '../storage/cognition-store.js';
 import { pathExists } from '../storage/kgraph-paths.js';
 import { readMaps } from '../storage/map-store.js';
 import { evaluateReferenceStatus } from './cognition-updater.js';
@@ -194,34 +195,6 @@ function mergeNotes(notes, currentMaps) {
         referencesStatus: evaluateReferenceStatus(relatedFiles, relatedSymbols, currentMaps),
     };
 }
-async function rebuildDomainRecords(workspace, notes, currentMaps) {
-    const existingDomains = await readDomainRecords(workspace);
-    const existingByName = new Map(existingDomains.map((domain) => [domain.name, domain]));
-    const domainNames = new Set([
-        ...existingDomains.map((domain) => domain.name),
-        ...notes.map((note) => note.domain ?? 'general'),
-    ]);
-    const fileSet = new Set(currentMaps.files.map((file) => file.path));
-    const symbolSet = new Set(currentMaps.symbols.map((symbol) => symbol.name));
-    for (const name of domainNames) {
-        const relatedNotes = notes.filter((note) => (note.domain ?? 'general') === name);
-        const existing = existingByName.get(name);
-        const next = {
-            name,
-            description: existing?.description,
-            pathHints: unique(relatedNotes.flatMap((note) => note.relatedFiles)),
-            tags: unique(relatedNotes.flatMap((note) => note.tags)),
-            files: unique(relatedNotes
-                .flatMap((note) => note.relatedFiles)
-                .filter((file) => fileSet.has(file))),
-            symbols: unique(relatedNotes
-                .flatMap((note) => note.relatedSymbols)
-                .filter((symbol) => symbolSet.has(symbol))),
-            cognitionNotes: relatedNotes.map((note) => note.id),
-        };
-        await overwriteDomainRecord(workspace, next);
-    }
-}
 async function archiveNote(workspace, note, reason) {
     const source = path.join(workspace.cognitionPath, `${note.id}.md`);
     if (!(await pathExists(source)))

package/dist/cognition/conclusion.js

@@ -67,7 +67,7 @@ export async function concludeTopic(workspace, input) {
         agent: input.agent,
         sessionId: input.sessionId,
         createdAt: note.createdAt,
-        idSeed: note.id,
+        idSeed: title,
     }, maps);
     return note;
 }

package/dist/cognition/domain-records.d.ts

@@ -0,0 +1,4 @@
+import type { KGraphWorkspace } from '../types/config.js';
+import type { CognitionNote } from '../types/cognition.js';
+import type { ScanResult } from '../types/maps.js';
+export declare function rebuildDomainRecords(workspace: KGraphWorkspace, notes: CognitionNote[], currentMaps: Pick<ScanResult, 'files' | 'symbols'>): Promise<void>;

package/dist/cognition/domain-records.js

@@ -0,0 +1,32 @@
+import { overwriteDomainRecord, readDomainRecords, } from '../storage/cognition-store.js';
+export async function rebuildDomainRecords(workspace, notes, currentMaps) {
+    const existingDomains = await readDomainRecords(workspace);
+    const existingByName = new Map(existingDomains.map((domain) => [domain.name, domain]));
+    const domainNames = new Set([
+        ...existingDomains.map((domain) => domain.name),
+        ...notes.map((note) => note.domain ?? 'general'),
+    ]);
+    const fileSet = new Set(currentMaps.files.map((file) => file.path));
+    const symbolSet = new Set(currentMaps.symbols.map((symbol) => symbol.name));
+    for (const name of domainNames) {
+        const relatedNotes = notes.filter((note) => (note.domain ?? 'general') === name);
+        const existing = existingByName.get(name);
+        const next = {
+            name,
+            description: existing?.description,
+            pathHints: unique(relatedNotes.flatMap((note) => note.relatedFiles)),
+            tags: unique(relatedNotes.flatMap((note) => note.tags)),
+            files: unique(relatedNotes
+                .flatMap((note) => note.relatedFiles)
+                .filter((file) => fileSet.has(file))),
+            symbols: unique(relatedNotes
+                .flatMap((note) => note.relatedSymbols)
+                .filter((symbol) => symbolSet.has(symbol))),
+            cognitionNotes: relatedNotes.map((note) => note.id),
+        };
+        await overwriteDomainRecord(workspace, next);
+    }
+}
+function unique(items) {
+    return [...new Set(items)];
+}

package/dist/config/config.js

@@ -7,6 +7,10 @@ export const DEFAULT_CONFIG = {
     exclude: [
         '.git',
         'node_modules',
+        'venv',
+        '.venv',
+        '__pycache__',
+        '.pytest_cache',
         'dist',
         'build',
         '.next',
@@ -67,6 +71,47 @@ export const DEFAULT_CONFIG = {
             '.hxx',
             // C#
             '.cs',
+            // PHP / Swift / Ruby
+            '.php',
+            '.swift',
+            '.rb',
+            '.rake',
+            // Shell
+            '.sh',
+            '.bash',
+            '.zsh',
+            '.fish',
+            // Web / styles
+            '.html',
+            '.htm',
+            '.css',
+            '.scss',
+            '.sass',
+            '.less',
+            // Data / config / schema
+            '.json',
+            '.jsonc',
+            '.yaml',
+            '.yml',
+            '.toml',
+            '.dockerfile',
+            '.xml',
+            '.graphql',
+            '.gql',
+            '.sql',
+            '.tf',
+            '.proto',
+            // Docs
+            '.md',
+            '.mdx',
+            // Additional app languages
+            '.lua',
+            '.r',
+            '.R',
+            '.dart',
+            '.ex',
+            '.exs',
+            '.scala',
         ],
     },
     maxContextItems: 8,

package/dist/knowledge/atom-store.js

@@ -423,7 +423,7 @@ function buildIndexes(atoms) {
     const terms = {};
     const refs = {};
     const topics = {};
-    for (const atom of atoms) {
+    for (const atom of atoms.filter((item) => item.status !== 'archived')) {
         for (const term of tokenize([atom.topic, atom.claim, atom.summary ?? ''].join(' '))) {
             addIndex(terms, term, atom.id);
         }

package/dist/scanner/broad-symbol-extractor.d.ts

@@ -0,0 +1,3 @@
+import type { SymbolExtractionResult } from './ts-symbol-extractor.js';
+export declare function extractBroadSymbols(sourceText: string, filePath: string, language: string): Promise<SymbolExtractionResult>;
+export declare function supportsBroadExtraction(language: string): boolean;