gitnexus 1.4.1 → 1.4.5

package/dist/cli/ai-context.js

@@ -24,84 +24,111 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * - Exact tool commands with parameters — vague directives get ignored
  * - Self-review checklist — forces model to verify its own work
  */
-function generateGitNexusContent(projectName, stats) {
-    return `${GITNEXUS_START_MARKER}
-# GitNexus — Code Intelligence
-
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
-
-> If any GitNexus tool warns the index is stale, run \`npx gitnexus analyze\` in terminal first.
-
-## Always Do
-
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
-
-## When Debugging
-
-1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
-2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
-3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
-4. For regressions: \`gitnexus_detect_changes({scope: "compare", base_ref: "main"})\` — see what your branch changed
-
-## When Refactoring
-
-- **Renaming**: MUST use \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with \`dry_run: false\`.
-- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
-- After any refactor: run \`gitnexus_detect_changes({scope: "all"})\` to verify only expected files changed.
-
-## Never Do
-
-- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use \`gitnexus_rename\` which understands the call graph.
-- NEVER commit changes without running \`gitnexus_detect_changes()\` to check affected scope.
-
-## Tools Quick Reference
-
-| Tool | When to use | Command |
-|------|-------------|---------|
-| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
-| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
-| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
-| \`detect_changes\` | Pre-commit scope check | \`gitnexus_detect_changes({scope: "staged"})\` |
-| \`rename\` | Safe multi-file rename | \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` |
-| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
-| d=2 | LIKELY AFFECTED — indirect deps | Should test |
-| d=3 | MAY NEED TESTING — transitive | Test if critical path |
-
-## Resources
-
-| Resource | Use for |
-|----------|---------|
-| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
-| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
-| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
-| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
-
-## Self-Check Before Finishing
-
-Before completing any code modification task, verify:
-1. \`gitnexus_impact\` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. \`gitnexus_detect_changes()\` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
-
-## CLI
-
-- Re-index: \`npx gitnexus analyze\`
-- Check freshness: \`npx gitnexus status\`
-- Generate docs: \`npx gitnexus wiki\`
-
+function generateGitNexusContent(projectName, stats, generatedSkills) {
+    const generatedRows = (generatedSkills && generatedSkills.length > 0)
+        ? generatedSkills.map(s => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`).join('\n')
+        : '';
+    const skillsTable = `| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |${generatedRows ? '\n' + generatedRows : ''}`;
+    return `${GITNEXUS_START_MARKER}
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run \`npx gitnexus analyze\` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
+
+## When Debugging
+
+1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
+2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
+3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
+4. For regressions: \`gitnexus_detect_changes({scope: "compare", base_ref: "main"})\` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with \`dry_run: false\`.
+- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
+- After any refactor: run \`gitnexus_detect_changes({scope: "all"})\` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use \`gitnexus_rename\` which understands the call graph.
+- NEVER commit changes without running \`gitnexus_detect_changes()\` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
+| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
+| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
+| \`detect_changes\` | Pre-commit scope check | \`gitnexus_detect_changes({scope: "staged"})\` |
+| \`rename\` | Safe multi-file rename | \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` |
+| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. \`gitnexus_impact\` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. \`gitnexus_detect_changes()\` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+\`\`\`bash
+npx gitnexus analyze
+\`\`\`
+
+If the index previously included embeddings, preserve them by adding \`--embeddings\`:
+
+\`\`\`bash
+npx gitnexus analyze --embeddings
+\`\`\`
+
+To check whether embeddings exist, inspect \`.gitnexus/meta.json\` — the \`stats.embeddings\` field shows the count (0 means no embeddings). **Running analyze without \`--embeddings\` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after \`git commit\` and \`git merge\`.
+
+## CLI
+
+${skillsTable}
+
 ${GITNEXUS_END_MARKER}`;
 }
 /**
@@ -193,16 +220,16 @@ async function installSkills(repoPath) {
             }
             catch {
                 // Fallback: generate minimal skill content
-                skillContent = `---
-name: ${skill.name}
-description: ${skill.description}
----
-
-# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
-
-${skill.description}
-
-Use GitNexus tools to accomplish this task.
+                skillContent = `---
+name: ${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
+
+${skill.description}
+
+Use GitNexus tools to accomplish this task.
 `;
             }
             await fs.writeFile(skillPath, skillContent, 'utf-8');
@@ -218,8 +245,8 @@ Use GitNexus tools to accomplish this task.
 /**
  * Generate AI context files after indexing
  */
-export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats) {
-    const content = generateGitNexusContent(projectName, stats);
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, generatedSkills) {
+    const content = generateGitNexusContent(projectName, stats, generatedSkills);
     const createdFiles = [];
     // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
     const agentsPath = path.join(repoPath, 'AGENTS.md');

package/dist/cli/analyze.d.ts

@@ -6,5 +6,7 @@
 export interface AnalyzeOptions {
     force?: boolean;
     embeddings?: boolean;
+    skills?: boolean;
+    verbose?: boolean;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -8,14 +8,15 @@ import { execFileSync } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
-import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex, loadCachedEmbeddings } from '../core/kuzu/kuzu-adapter.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, createFTSIndex, loadCachedEmbeddings } from '../core/lbug/lbug-adapter.js';
 // Embedding imports are lazy (dynamic import) so onnxruntime-node is never
 // loaded when embeddings are not requested. This avoids crashes on Node
 // versions whose ABI is not yet supported by the native binary (#89).
 // disposeEmbedder intentionally not called — ONNX Runtime segfaults on cleanup (see #38)
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath, cleanupOldKuzuFiles } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
+import { generateSkillFiles } from './skill-gen.js';
 import fs from 'fs/promises';
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
@@ -50,7 +51,7 @@ const PHASE_LABELS = {
     communities: 'Detecting communities',
     processes: 'Detecting processes',
     complete: 'Pipeline complete',
-    kuzu: 'Loading into KuzuDB',
+    lbug: 'Loading into LadybugDB',
     fts: 'Creating search indexes',
     embeddings: 'Generating embeddings',
     done: 'Done',
@@ -58,6 +59,9 @@ const PHASE_LABELS = {
 export const analyzeCommand = async (inputPath, options) => {
     if (ensureHeap())
         return;
+    if (options?.verbose) {
+        process.env.GITNEXUS_VERBOSE = '1';
+    }
     console.log('\n  GitNexus Analyzer\n');
     let repoPath;
     if (inputPath) {
@@ -77,13 +81,22 @@ export const analyzeCommand = async (inputPath, options) => {
         process.exitCode = 1;
         return;
     }
-    const { storagePath, kuzuPath } = getStoragePaths(repoPath);
+    const { storagePath, lbugPath } = getStoragePaths(repoPath);
+    // Clean up stale KuzuDB files from before the LadybugDB migration.
+    // If kuzu existed but lbug doesn't, we're doing a migration re-index — say so.
+    const kuzuResult = await cleanupOldKuzuFiles(storagePath);
+    if (kuzuResult.found && kuzuResult.needsReindex) {
+        console.log('  Migrating from KuzuDB to LadybugDB — rebuilding index...\n');
+    }
     const currentCommit = getCurrentCommit(repoPath);
     const existingMeta = await loadMeta(storagePath);
-    if (existingMeta && !options?.force && existingMeta.lastCommit === currentCommit) {
+    if (existingMeta && !options?.force && !options?.skills && existingMeta.lastCommit === currentCommit) {
         console.log('  Already up to date\n');
         return;
     }
+    if (process.env.GITNEXUS_NO_GITIGNORE) {
+        console.log('  GITNEXUS_NO_GITIGNORE is set — skipping .gitignore (still reading .gitnexusignore)\n');
+    }
     // Single progress bar for entire pipeline
     const bar = new cliProgress.SingleBar({
         format: '  {bar} {percentage}% | {phase}',
@@ -104,7 +117,7 @@ export const analyzeCommand = async (inputPath, options) => {
         aborted = true;
         bar.stop();
         console.log('\n  Interrupted — cleaning up...');
-        closeKuzu().catch(() => { }).finally(() => process.exit(130));
+        closeLbug().catch(() => { }).finally(() => process.exit(130));
     };
     process.on('SIGINT', sigintHandler);
     // Route all console output through bar.log() so the bar doesn't stamp itself
@@ -150,15 +163,15 @@ export const analyzeCommand = async (inputPath, options) => {
     if (options?.embeddings && existingMeta && !options?.force) {
         try {
             updateBar(0, 'Caching embeddings...');
-            await initKuzu(kuzuPath);
+            await initLbug(lbugPath);
             const cached = await loadCachedEmbeddings();
             cachedEmbeddingNodeIds = cached.embeddingNodeIds;
             cachedEmbeddings = cached.embeddings;
-            await closeKuzu();
+            await closeLbug();
         }
         catch {
             try {
-                await closeKuzu();
+                await closeLbug();
             }
             catch { }
         }
@@ -169,26 +182,26 @@ export const analyzeCommand = async (inputPath, options) => {
         const scaled = Math.round(progress.percent * 0.6);
         updateBar(scaled, phaseLabel);
     });
-    // ── Phase 2: KuzuDB (60–85%) ──────────────────────────────────────
-    updateBar(60, 'Loading into KuzuDB...');
-    await closeKuzu();
-    const kuzuFiles = [kuzuPath, `${kuzuPath}.wal`, `${kuzuPath}.lock`];
-    for (const f of kuzuFiles) {
+    // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────────
+    updateBar(60, 'Loading into LadybugDB...');
+    await closeLbug();
+    const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`];
+    for (const f of lbugFiles) {
         try {
             await fs.rm(f, { recursive: true, force: true });
         }
         catch { }
     }
-    const t0Kuzu = Date.now();
-    await initKuzu(kuzuPath);
-    let kuzuMsgCount = 0;
-    const kuzuResult = await loadGraphToKuzu(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
-        kuzuMsgCount++;
-        const progress = Math.min(84, 60 + Math.round((kuzuMsgCount / (kuzuMsgCount + 10)) * 24));
+    const t0Lbug = Date.now();
+    await initLbug(lbugPath);
+    let lbugMsgCount = 0;
+    const lbugResult = await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
+        lbugMsgCount++;
+        const progress = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24));
         updateBar(progress, msg);
     });
-    const kuzuTime = ((Date.now() - t0Kuzu) / 1000).toFixed(1);
-    const kuzuWarnings = kuzuResult.warnings;
+    const lbugTime = ((Date.now() - t0Lbug) / 1000).toFixed(1);
+    const lbugWarnings = lbugResult.warnings;
     // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
     updateBar(85, 'Creating search indexes...');
     const t0Fts = Date.now();
@@ -217,7 +230,7 @@ export const analyzeCommand = async (inputPath, options) => {
         }
     }
     // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
-    const stats = await getKuzuStats();
+    const stats = await getLbugStats();
     let embeddingTime = '0.0';
     let embeddingSkipped = true;
     let embeddingSkipReason = 'off (use --embeddings to enable)';
@@ -242,6 +255,13 @@ export const analyzeCommand = async (inputPath, options) => {
     }
     // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
     updateBar(98, 'Saving metadata...');
+    // Count embeddings in the index (cached + newly generated)
+    let embeddingCount = 0;
+    try {
+        const embResult = await executeQuery(`MATCH (e:CodeEmbedding) RETURN count(e) AS cnt`);
+        embeddingCount = embResult?.[0]?.cnt ?? 0;
+    }
+    catch { /* table may not exist if embeddings never ran */ }
     const meta = {
         repoPath,
         lastCommit: currentCommit,
@@ -252,6 +272,7 @@ export const analyzeCommand = async (inputPath, options) => {
             edges: stats.edges,
             communities: pipelineResult.communityResult?.stats.totalCommunities,
             processes: pipelineResult.processResult?.stats.totalProcesses,
+            embeddings: embeddingCount,
         },
     };
     await saveMeta(storagePath, meta);
@@ -267,6 +288,12 @@ export const analyzeCommand = async (inputPath, options) => {
         }
         aggregatedClusterCount = Array.from(groups.values()).filter(count => count >= 5).length;
     }
+    let generatedSkills = [];
+    if (options?.skills && pipelineResult.communityResult) {
+        updateBar(99, 'Generating skill files...');
+        const skillResult = await generateSkillFiles(repoPath, projectName, pipelineResult);
+        generatedSkills = skillResult.skills;
+    }
     const aiContext = await generateAIContextFiles(repoPath, storagePath, projectName, {
         files: pipelineResult.totalFileCount,
         nodes: stats.nodes,
@@ -274,8 +301,8 @@ export const analyzeCommand = async (inputPath, options) => {
         communities: pipelineResult.communityResult?.stats.totalCommunities,
         clusters: aggregatedClusterCount,
         processes: pipelineResult.processResult?.stats.totalProcesses,
-    });
-    await closeKuzu();
+    }, generatedSkills);
+    await closeLbug();
     // Note: we intentionally do NOT call disposeEmbedder() here.
     // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs.
     // Since the process exits immediately after, Node.js reclaims everything.
@@ -291,18 +318,18 @@ export const analyzeCommand = async (inputPath, options) => {
     const embeddingsCached = cachedEmbeddings.length > 0;
     console.log(`\n  Repository indexed successfully (${totalTime}s)${embeddingsCached ? ` [${cachedEmbeddings.length} embeddings cached]` : ''}\n`);
     console.log(`  ${stats.nodes.toLocaleString()} nodes | ${stats.edges.toLocaleString()} edges | ${pipelineResult.communityResult?.stats.totalCommunities || 0} clusters | ${pipelineResult.processResult?.stats.totalProcesses || 0} flows`);
-    console.log(`  KuzuDB ${kuzuTime}s | FTS ${ftsTime}s | Embeddings ${embeddingSkipped ? embeddingSkipReason : embeddingTime + 's'}`);
+    console.log(`  LadybugDB ${lbugTime}s | FTS ${ftsTime}s | Embeddings ${embeddingSkipped ? embeddingSkipReason : embeddingTime + 's'}`);
     console.log(`  ${repoPath}`);
     if (aiContext.files.length > 0) {
         console.log(`  Context: ${aiContext.files.join(', ')}`);
     }
     // Show a quiet summary if some edge types needed fallback insertion
-    if (kuzuWarnings.length > 0) {
-        const totalFallback = kuzuWarnings.reduce((sum, w) => {
+    if (lbugWarnings.length > 0) {
+        const totalFallback = lbugWarnings.reduce((sum, w) => {
             const m = w.match(/\((\d+) edges\)/);
             return sum + (m ? parseInt(m[1]) : 0);
         }, 0);
-        console.log(`  Note: ${totalFallback} edges across ${kuzuWarnings.length} types inserted via fallback (schema will be updated in next release)`);
+        console.log(`  Note: ${totalFallback} edges across ${lbugWarnings.length} types inserted via fallback (schema will be updated in next release)`);
     }
     try {
         await fs.access(getGlobalRegistryPath());
@@ -311,7 +338,7 @@ export const analyzeCommand = async (inputPath, options) => {
         console.log('\n  Tip: Run `gitnexus setup` to configure MCP for your editor.');
     }
     console.log('');
-    // KuzuDB's native module holds open handles that prevent Node from exiting.
+    // LadybugDB's native module holds open handles that prevent Node from exiting.
     // ONNX Runtime also registers native atexit hooks that segfault on some
     // platforms (#38, #40). Force-exit to ensure clean termination.
     process.exit(0);

package/dist/cli/augment.js

@@ -19,7 +19,7 @@ export async function augmentCommand(pattern) {
         const result = await augment(pattern, process.cwd());
         if (result) {
             // IMPORTANT: Write to stderr, NOT stdout.
-            // KuzuDB's native module captures stdout fd at OS level during init,
+            // LadybugDB's native module captures stdout fd at OS level during init,
             // which makes stdout permanently broken in subprocess contexts.
             // stderr is never captured, so it works reliably everywhere.
             // The hook reads from the subprocess's stderr.

package/dist/cli/eval-server.d.ts

@@ -1,7 +1,7 @@
 /**
  * Eval Server — Lightweight HTTP server for SWE-bench evaluation
  *
- * Keeps KuzuDB warm in memory so tool calls from the agent are near-instant.
+ * Keeps LadybugDB warm in memory so tool calls from the agent are near-instant.
  * Designed to run inside Docker containers during SWE-bench evaluation.
  *
  * KEY DESIGN: Returns LLM-friendly text, not raw JSON.

package/dist/cli/eval-server.js

@@ -1,7 +1,7 @@
 /**
  * Eval Server — Lightweight HTTP server for SWE-bench evaluation
  *
- * Keeps KuzuDB warm in memory so tool calls from the agent are near-instant.
+ * Keeps LadybugDB warm in memory so tool calls from the agent are near-instant.
  * Designed to run inside Docker containers during SWE-bench evaluation.
  *
  * KEY DESIGN: Returns LLM-friendly text, not raw JSON.

package/dist/cli/index.js

@@ -2,18 +2,8 @@
 // Heap re-spawn removed — only analyze.ts needs the 8GB heap (via its own ensureHeap()).
 // Removing it from here improves MCP server startup time significantly.
 import { Command } from 'commander';
-import { analyzeCommand } from './analyze.js';
-import { serveCommand } from './serve.js';
-import { listCommand } from './list.js';
-import { statusCommand } from './status.js';
-import { mcpCommand } from './mcp.js';
-import { cleanCommand } from './clean.js';
-import { setupCommand } from './setup.js';
-import { augmentCommand } from './augment.js';
-import { wikiCommand } from './wiki.js';
-import { queryCommand, contextCommand, impactCommand, cypherCommand } from './tool.js';
-import { evalServerCommand } from './eval-server.js';
 import { createRequire } from 'node:module';
+import { createLazyAction } from './lazy-action.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
@@ -24,37 +14,40 @@ program
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode')
-    .action(setupCommand);
+    .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
-    .action(analyzeCommand);
+    .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
+    .addHelpText('after', '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)')
+    .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 program
     .command('serve')
     .description('Start local HTTP server for web UI connection')
     .option('-p, --port <port>', 'Port number', '4747')
     .option('--host <host>', 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)')
-    .action(serveCommand);
+    .action(createLazyAction(() => import('./serve.js'), 'serveCommand'));
 program
     .command('mcp')
     .description('Start MCP server (stdio) — serves all indexed repos')
-    .action(mcpCommand);
+    .action(createLazyAction(() => import('./mcp.js'), 'mcpCommand'));
 program
     .command('list')
     .description('List all indexed repositories')
-    .action(listCommand);
+    .action(createLazyAction(() => import('./list.js'), 'listCommand'));
 program
     .command('status')
     .description('Show index status for current repo')
-    .action(statusCommand);
+    .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
-    .action(cleanCommand);
+    .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')
@@ -64,11 +57,11 @@ program
     .option('--api-key <key>', 'LLM API key (saved to ~/.gitnexus/config.json)')
     .option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
     .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
-    .action(wikiCommand);
+    .action(createLazyAction(() => import('./wiki.js'), 'wikiCommand'));
 program
     .command('augment <pattern>')
     .description('Augment a search pattern with knowledge graph context (used by hooks)')
-    .action(augmentCommand);
+    .action(createLazyAction(() => import('./augment.js'), 'augmentCommand'));
 // ─── Direct Tool Commands (no MCP overhead) ────────────────────────
 // These invoke LocalBackend directly for use in eval, scripts, and CI.
 program
@@ -79,7 +72,7 @@ program
     .option('-g, --goal <text>', 'What you want to find')
     .option('-l, --limit <n>', 'Max processes to return (default: 5)')
     .option('--content', 'Include full symbol source code')
-    .action(queryCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
 program
     .command('context [name]')
     .description('360-degree view of a code symbol: callers, callees, processes')
@@ -87,7 +80,7 @@ program
     .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
     .option('-f, --file <path>', 'File path to disambiguate common names')
     .option('--content', 'Include full symbol source code')
-    .action(contextCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
     .command('impact <target>')
     .description('Blast radius analysis: what breaks if you change a symbol')
@@ -95,17 +88,17 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('--depth <n>', 'Max relationship depth (default: 3)')
     .option('--include-tests', 'Include test files in results')
-    .action(impactCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'impactCommand'));
 program
     .command('cypher <query>')
     .description('Execute raw Cypher query against the knowledge graph')
     .option('-r, --repo <name>', 'Target repository')
-    .action(cypherCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')
     .description('Start lightweight HTTP server for fast tool calls during evaluation')
     .option('-p, --port <port>', 'Port number', '4848')
     .option('--idle-timeout <seconds>', 'Auto-shutdown after N seconds idle (0 = disabled)', '0')
-    .action(evalServerCommand);
+    .action(createLazyAction(() => import('./eval-server.js'), 'evalServerCommand'));
 program.parse(process.argv);

package/dist/cli/lazy-action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates a lazy-loaded CLI action that defers module import until invocation.
+ * The generic constraints ensure the export name is a valid key of the module
+ * at compile time — catching typos when used with concrete module imports.
+ */
+export declare function createLazyAction<TModule extends Record<string, unknown>, TKey extends string & keyof TModule>(loader: () => Promise<TModule>, exportName: TKey): (...args: unknown[]) => Promise<void>;

package/dist/cli/lazy-action.js

@@ -0,0 +1,18 @@
+/**
+ * Creates a lazy-loaded CLI action that defers module import until invocation.
+ * The generic constraints ensure the export name is a valid key of the module
+ * at compile time — catching typos when used with concrete module imports.
+ */
+function isCallable(value) {
+    return typeof value === 'function';
+}
+export function createLazyAction(loader, exportName) {
+    return async (...args) => {
+        const module = await loader();
+        const action = module[exportName];
+        if (!isCallable(action)) {
+            throw new Error(`Lazy action export not found: ${exportName}`);
+        }
+        await action(...args);
+    };
+}