@codragraph/cli 1.6.2

package/dist/cli/ai-context.js

@@ -0,0 +1,270 @@
+/**
+ * AI Context Generator
+ *
+ * Creates AGENTS.md and CLAUDE.md with full inline CodraGraph context.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
+ * CLAUDE.md is for Claude Code which only reads that file.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// ESM equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CODRAGRAPH_START_MARKER = '<!-- codragraph:start -->';
+const CODRAGRAPH_END_MARKER = '<!-- codragraph:end -->';
+/**
+ * Find the index of a section marker that occupies its own line.
+ * Unlike `indexOf`, this rejects inline prose references like
+ * `` See the `<!-- codragraph:start -->` block `` that appear
+ * mid-sentence (#1041). A marker counts as section-position only when:
+ *   - preceded by newline or start-of-file, AND
+ *   - followed by newline, `\r` (CRLF files), or end-of-file.
+ * The generator always emits each marker alone on its line, so this
+ * matches every legitimate section and none of the inline mentions.
+ *
+ * `startFrom` lets the end-marker lookup start after the already-found
+ * start marker, avoiding a scan from 0 and guaranteeing we never pick
+ * up an end marker that appears earlier in the file than the start.
+ */
+function findSectionMarkerIndex(content, marker, startFrom = 0) {
+    let idx = content.indexOf(marker, startFrom);
+    while (idx !== -1) {
+        const atLineStart = idx === 0 || content[idx - 1] === '\n';
+        const endPos = idx + marker.length;
+        const atLineEnd = endPos === content.length || content[endPos] === '\n' || content[endPos] === '\r';
+        if (atLineStart && atLineEnd)
+            return idx;
+        idx = content.indexOf(marker, idx + 1);
+    }
+    return -1;
+}
+/**
+ * Generate the full CodraGraph context content.
+ *
+ * Design principles (learned from real agent behavior and industry research):
+ * - Inline critical workflows — skills are skipped 56% of the time (Vercel eval data)
+ * - Use RFC 2119 language (MUST, NEVER, ALWAYS) — models follow imperative rules
+ * - Three-tier boundaries (Always/When/Never) — proven to change model behavior
+ * - Keep under 120 lines — adherence degrades past 150 lines
+ * - Exact tool commands with parameters — vague directives get ignored
+ * - Self-review checklist — forces model to verify its own work
+ */
+async function findGroupsContainingRegistryName(registryName) {
+    const { listGroups, getDefaultCodragraphDir, getGroupDir } = await import('../core/group/storage.js');
+    const { loadGroupConfig } = await import('../core/group/config-parser.js');
+    const names = await listGroups();
+    const hits = [];
+    for (const g of names) {
+        try {
+            const config = await loadGroupConfig(getGroupDir(getDefaultCodragraphDir(), g));
+            if (Object.values(config.repos).some((r) => r === registryName))
+                hits.push(config.name);
+        }
+        catch {
+            // skip invalid or unreadable groups
+        }
+    }
+    return hits;
+}
+function generateCodraGraphContent(projectName, stats, generatedSkills, groupNames, noStats) {
+    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/codragraph/codragraph-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/codragraph/codragraph-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/codragraph/codragraph-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/codragraph/codragraph-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`.claude/skills/codragraph/codragraph-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`.claude/skills/codragraph/codragraph-cli/SKILL.md\` |${generatedRows ? '\n' + generatedRows : ''}`;
+    return `${CODRAGRAPH_START_MARKER}
+# CodraGraph — Code Intelligence
+
+This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}. Use the CodraGraph MCP tools to understand code, assess impact, and navigate safely.
+
+> If any CodraGraph tool warns the index is stale, run \`npx codragraph analyze\` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`codragraph_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`codragraph_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 \`codragraph_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 \`codragraph_context({name: "symbolName"})\`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`codragraph_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use \`codragraph_rename\` which understands the call graph.
+- NEVER commit changes without running \`codragraph_detect_changes()\` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`codragraph://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`codragraph://repo/${projectName}/clusters\` | All functional areas |
+| \`codragraph://repo/${projectName}/processes\` | All execution flows |
+| \`codragraph://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+${groupNames && groupNames.length > 0
+        ? `## Cross-Repo Groups
+
+This repository is listed under CodraGraph **group(s): ${groupNames.join(', ')}** (see \`~/.codragraph/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx codragraph group list\`, \`npx codragraph group sync <name>\`, \`npx codragraph group impact <name> --target <symbol> --repo <group-path>\`.
+
+`
+        : ''}## CLI
+
+${skillsTable}
+
+${CODRAGRAPH_END_MARKER}`;
+}
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create or update CodraGraph section in a file
+ * - If file doesn't exist: create with CodraGraph content
+ * - If file exists without CodraGraph section: append
+ * - If file exists with CodraGraph section: replace that section
+ */
+async function upsertCodraGraphSection(filePath, content) {
+    const exists = await fileExists(filePath);
+    if (!exists) {
+        await fs.writeFile(filePath, content, 'utf-8');
+        return 'created';
+    }
+    const existingContent = await fs.readFile(filePath, 'utf-8');
+    // Check if CodraGraph section already exists. Matching is restricted
+    // to markers that occupy their own line so that inline prose
+    // references (e.g. `` See the `<!-- codragraph:start -->` block `` in
+    // the shipped CLAUDE.md) are NOT treated as section delimiters
+    // (#1041). The end-marker scan starts after the start-marker so it
+    // can never pick up an earlier end in the file.
+    const startIdx = findSectionMarkerIndex(existingContent, CODRAGRAPH_START_MARKER);
+    const endIdx = findSectionMarkerIndex(existingContent, CODRAGRAPH_END_MARKER, startIdx === -1 ? 0 : startIdx);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing section
+        const before = existingContent.substring(0, startIdx);
+        const after = existingContent.substring(endIdx + CODRAGRAPH_END_MARKER.length);
+        const newContent = before + content + after;
+        await fs.writeFile(filePath, newContent.trim() + '\n', 'utf-8');
+        return 'updated';
+    }
+    // Append new section
+    const newContent = existingContent.trim() + '\n\n' + content + '\n';
+    await fs.writeFile(filePath, newContent, 'utf-8');
+    return 'appended';
+}
+/**
+ * Install CodraGraph skills to .claude/skills/codragraph/
+ * Works natively with Claude Code, Cursor, and GitHub Copilot
+ */
+async function installSkills(repoPath) {
+    const skillsDir = path.join(repoPath, '.claude', 'skills', '@codragraph/cli');
+    const installedSkills = [];
+    // Skill definitions bundled with the package
+    const skills = [
+        {
+            name: 'codragraph-exploring',
+            description: 'Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"',
+        },
+        {
+            name: 'codragraph-debugging',
+            description: 'Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug"',
+        },
+        {
+            name: 'codragraph-impact-analysis',
+            description: 'Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?"',
+        },
+        {
+            name: 'codragraph-refactoring',
+            description: 'Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"',
+        },
+        {
+            name: 'codragraph-guide',
+            description: 'Use when the user asks about CodraGraph itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What CodraGraph tools are available?", "How do I use CodraGraph?"',
+        },
+        {
+            name: 'codragraph-cli',
+            description: 'Use when the user needs to run CodraGraph CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: "Index this repo", "Reanalyze the codebase", "Generate a wiki"',
+        },
+    ];
+    for (const skill of skills) {
+        const skillDir = path.join(skillsDir, skill.name);
+        const skillPath = path.join(skillDir, 'SKILL.md');
+        try {
+            // Create skill directory
+            await fs.mkdir(skillDir, { recursive: true });
+            // Try to read from package skills directory
+            const packageSkillPath = path.join(__dirname, '..', '..', 'skills', `${skill.name}.md`);
+            let skillContent;
+            try {
+                skillContent = await fs.readFile(packageSkillPath, 'utf-8');
+            }
+            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 CodraGraph tools to accomplish this task.
+`;
+            }
+            await fs.writeFile(skillPath, skillContent, 'utf-8');
+            installedSkills.push(skill.name);
+        }
+        catch (err) {
+            // Skip on error, don't fail the whole process
+            console.warn(`Warning: Could not install skill ${skill.name}:`, err);
+        }
+    }
+    return installedSkills;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, generatedSkills, options) {
+    const groupNames = await findGroupsContainingRegistryName(projectName);
+    const content = generateCodraGraphContent(projectName, stats, generatedSkills, groupNames, options?.noStats);
+    const createdFiles = [];
+    if (!options?.skipAgentsMd) {
+        // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
+        const agentsPath = path.join(repoPath, 'AGENTS.md');
+        const agentsResult = await upsertCodraGraphSection(agentsPath, content);
+        createdFiles.push(`AGENTS.md (${agentsResult})`);
+        // Create CLAUDE.md (for Claude Code)
+        const claudePath = path.join(repoPath, 'CLAUDE.md');
+        const claudeResult = await upsertCodraGraphSection(claudePath, content);
+        createdFiles.push(`CLAUDE.md (${claudeResult})`);
+    }
+    else {
+        createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
+        createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
+    }
+    // Install skills to .claude/skills/codragraph/
+    const installedSkills = await installSkills(repoPath);
+    if (installedSkills.length > 0) {
+        createdFiles.push(`.claude/skills/codragraph/ (${installedSkills.length} skills)`);
+    }
+    return { files: createdFiles };
+}

package/dist/cli/analyze.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .codragraph/
+ *
+ * Delegates core analysis to the shared runFullAnalysis orchestrator.
+ * This CLI wrapper handles: heap management, progress bar, SIGINT,
+ * skill generation (--skills), summary output, and process.exit().
+ */
+export interface AnalyzeOptions {
+    force?: boolean;
+    embeddings?: boolean;
+    skills?: boolean;
+    verbose?: boolean;
+    /** Skip AGENTS.md and CLAUDE.md codragraph block updates. */
+    skipAgentsMd?: boolean;
+    /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
+    noStats?: boolean;
+    /** Index the folder even when no .git directory is present. */
+    skipGit?: boolean;
+    /**
+     * Override the default basename-derived registry `name` with a
+     * user-supplied alias (#829). Disambiguates repos whose paths share a
+     * basename. Persisted — subsequent re-analyses of the same path without
+     * `--name` preserve the alias.
+     */
+    name?: string;
+    /**
+     * Allow registration even when another path already uses the same
+     * `--name` alias (#829). Intentionally a distinct flag from `--force`
+     * because the user may want to coexist under the same name WITHOUT
+     * paying the cost of a pipeline re-index. Maps to registerRepo's
+     * `allowDuplicateName` option end-to-end.
+     */
+    allowDuplicateName?: boolean;
+    /**
+     * Override the walker's large-file skip threshold (#991). Value in KB;
+     * clamped downstream to the tree-sitter 32 MB ceiling. Sets
+     * `CODRAGRAPH_MAX_FILE_SIZE` for the rest of the pipeline.
+     */
+    maxFileSize?: string;
+}
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -0,0 +1,312 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .codragraph/
+ *
+ * Delegates core analysis to the shared runFullAnalysis orchestrator.
+ * This CLI wrapper handles: heap management, progress bar, SIGINT,
+ * skill generation (--skills), summary output, and process.exit().
+ */
+import path from 'path';
+import { execFileSync } from 'child_process';
+import v8 from 'v8';
+import cliProgress from 'cli-progress';
+import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, } from '../storage/repo-manager.js';
+import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { runFullAnalysis } from '../core/run-analyze.js';
+import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
+import fs from 'fs/promises';
+const HEAP_MB = 8192;
+const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
+/** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
+const STACK_KB = 4096;
+const STACK_FLAG = `--stack-size=${STACK_KB}`;
+/** Re-exec the process with an 8GB heap and larger stack if we're currently below that. */
+function ensureHeap() {
+    const nodeOpts = process.env.NODE_OPTIONS || '';
+    if (nodeOpts.includes('--max-old-space-size'))
+        return false;
+    const v8Heap = v8.getHeapStatistics().heap_size_limit;
+    if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+        return false;
+    // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+,
+    // so pass it only as a direct CLI argument, not via the environment.
+    const cliFlags = [HEAP_FLAG];
+    if (!nodeOpts.includes('--stack-size'))
+        cliFlags.push(STACK_FLAG);
+    try {
+        execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
+            stdio: 'inherit',
+            env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
+        });
+    }
+    catch (e) {
+        process.exitCode = e.status ?? 1;
+    }
+    return true;
+}
+export const analyzeCommand = async (inputPath, options) => {
+    if (ensureHeap())
+        return;
+    if (options?.verbose) {
+        process.env.CODRAGRAPH_VERBOSE = '1';
+    }
+    if (options?.maxFileSize) {
+        process.env.CODRAGRAPH_MAX_FILE_SIZE = options.maxFileSize;
+    }
+    console.log('\n  CodraGraph Analyzer\n');
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            if (!options?.skipGit) {
+                console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+                process.exitCode = 1;
+                return;
+            }
+            // --skip-git: fall back to cwd as the root
+            repoPath = path.resolve(process.cwd());
+        }
+        else {
+            repoPath = gitRoot;
+        }
+    }
+    const repoHasGit = hasGitDir(repoPath);
+    if (!repoHasGit && !options?.skipGit) {
+        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!repoHasGit) {
+        console.log('  Warning: no .git directory found \u2014 commit-tracking and incremental updates disabled.\n');
+    }
+    // KuzuDB migration cleanup is handled by runFullAnalysis internally.
+    // Note: --skills is handled after runFullAnalysis using the returned pipelineResult.
+    if (process.env.CODRAGRAPH_NO_GITIGNORE) {
+        console.log('  CODRAGRAPH_NO_GITIGNORE is set — skipping .gitignore (still reading .codragraphignore)\n');
+    }
+    const maxFileSizeBanner = getMaxFileSizeBannerMessage();
+    if (maxFileSizeBanner) {
+        console.log(`${maxFileSizeBanner}\n`);
+    }
+    // ── CLI progress bar setup ─────────────────────────────────────────
+    const bar = new cliProgress.SingleBar({
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    }, cliProgress.Presets.shades_grey);
+    bar.start(100, 0, { phase: 'Initializing...' });
+    // Graceful SIGINT handling
+    let aborted = false;
+    const sigintHandler = () => {
+        if (aborted)
+            process.exit(1);
+        aborted = true;
+        bar.stop();
+        console.log('\n  Interrupted — cleaning up...');
+        closeLbug()
+            .catch(() => { })
+            .finally(() => process.exit(130));
+    };
+    process.on('SIGINT', sigintHandler);
+    // Route console output through bar.log() to prevent progress bar corruption
+    const origLog = console.log.bind(console);
+    const origWarn = console.warn.bind(console);
+    const origError = console.error.bind(console);
+    let barCurrentValue = 0;
+    const barLog = (...args) => {
+        process.stdout.write('\x1b[2K\r');
+        origLog(args.map((a) => (typeof a === 'string' ? a : String(a))).join(' '));
+        bar.update(barCurrentValue);
+    };
+    console.log = barLog;
+    console.warn = barLog;
+    console.error = barLog;
+    // Track elapsed time per phase
+    let lastPhaseLabel = 'Initializing...';
+    let phaseStart = Date.now();
+    const updateBar = (value, phaseLabel) => {
+        barCurrentValue = value;
+        if (phaseLabel !== lastPhaseLabel) {
+            lastPhaseLabel = phaseLabel;
+            phaseStart = Date.now();
+        }
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        const display = elapsed >= 3 ? `${phaseLabel} (${elapsed}s)` : phaseLabel;
+        bar.update(value, { phase: display });
+    };
+    const elapsedTimer = setInterval(() => {
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        if (elapsed >= 3) {
+            bar.update({ phase: `${lastPhaseLabel} (${elapsed}s)` });
+        }
+    }, 1000);
+    const t0 = Date.now();
+    // ── Run shared analysis orchestrator ───────────────────────────────
+    try {
+        const result = await runFullAnalysis(repoPath, {
+            // Pipeline re-index — OR'd with --skills because skill generation
+            // needs a fresh pipelineResult. Has no bearing on the registry
+            // collision guard (see allowDuplicateName below).
+            force: options?.force || options?.skills,
+            embeddings: options?.embeddings,
+            skipGit: options?.skipGit,
+            skipAgentsMd: options?.skipAgentsMd,
+            noStats: options?.noStats,
+            registryName: options?.name,
+            // Registry-collision bypass — its own CLI flag, intentionally NOT
+            // overloading --force. A user who hits the collision guard should
+            // be able to accept the duplicate name without also paying the
+            // cost of a full pipeline re-index. See #829 review round 2.
+            allowDuplicateName: options?.allowDuplicateName,
+        }, {
+            onProgress: (_phase, percent, message) => {
+                updateBar(percent, message);
+            },
+            onLog: barLog,
+        });
+        if (result.alreadyUpToDate) {
+            clearInterval(elapsedTimer);
+            process.removeListener('SIGINT', sigintHandler);
+            console.log = origLog;
+            console.warn = origWarn;
+            console.error = origError;
+            bar.stop();
+            console.log('  Already up to date\n');
+            // Safe to return without process.exit(0) — the early-return path in
+            // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
+            return;
+        }
+        // Skill generation (CLI-only, uses pipeline result from analysis)
+        if (options?.skills && result.pipelineResult) {
+            updateBar(99, 'Generating skill files...');
+            try {
+                const { generateSkillFiles } = await import('./skill-gen.js');
+                const { generateAIContextFiles } = await import('./ai-context.js');
+                const skillResult = await generateSkillFiles(repoPath, result.repoName, result.pipelineResult);
+                if (skillResult.skills.length > 0) {
+                    barLog(`  Generated ${skillResult.skills.length} skill files`);
+                    // Re-generate AI context files now that we have skill info
+                    const s = result.stats;
+                    const communityResult = result.pipelineResult?.communityResult;
+                    let aggregatedClusterCount = 0;
+                    if (communityResult?.communities) {
+                        const groups = new Map();
+                        for (const c of communityResult.communities) {
+                            const label = c.heuristicLabel || c.label || 'Unknown';
+                            groups.set(label, (groups.get(label) || 0) + c.symbolCount);
+                        }
+                        aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
+                    }
+                    const { storagePath: sp } = getStoragePaths(repoPath);
+                    await generateAIContextFiles(repoPath, sp, result.repoName, {
+                        files: s.files ?? 0,
+                        nodes: s.nodes ?? 0,
+                        edges: s.edges ?? 0,
+                        communities: s.communities,
+                        clusters: aggregatedClusterCount,
+                        processes: s.processes,
+                    }, skillResult.skills, { skipAgentsMd: options?.skipAgentsMd, noStats: options?.noStats });
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        const totalTime = ((Date.now() - t0) / 1000).toFixed(1);
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        console.warn = origWarn;
+        console.error = origError;
+        bar.update(100, { phase: 'Done' });
+        bar.stop();
+        // ── Summary ────────────────────────────────────────────────────
+        const s = result.stats;
+        console.log(`\n  Repository indexed successfully (${totalTime}s)\n`);
+        console.log(`  ${(s.nodes ?? 0).toLocaleString()} nodes | ${(s.edges ?? 0).toLocaleString()} edges | ${s.communities ?? 0} clusters | ${s.processes ?? 0} flows`);
+        console.log(`  ${repoPath}`);
+        try {
+            await fs.access(getGlobalRegistryPath());
+        }
+        catch {
+            console.log('\n  Tip: Run `codragraph setup` to configure MCP for your editor.');
+        }
+        console.log('');
+    }
+    catch (err) {
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        console.warn = origWarn;
+        console.error = origError;
+        bar.stop();
+        const msg = err.message || String(err);
+        // Registry name-collision from --name (#829) — surface as an
+        // actionable error rather than a generic stack-trace.
+        if (err instanceof RegistryNameCollisionError) {
+            console.error(`\n  Registry name collision:\n`);
+            console.error(`    "${err.registryName}" is already used by "${err.existingPath}".\n`);
+            console.error(`  Options:`);
+            console.error(`    • Pick a different alias:  codragraph analyze --name <alias>`);
+            console.error(`    • Allow the duplicate:     codragraph analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)`);
+            console.error('');
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`\n  Analysis failed: ${msg}\n`);
+        // Provide helpful guidance for known failure modes
+        if (msg.includes('Maximum call stack size exceeded') ||
+            msg.includes('call stack') ||
+            msg.includes('Map maximum size') ||
+            msg.includes('Invalid array length') ||
+            msg.includes('Invalid string length') ||
+            msg.includes('allocation failed') ||
+            msg.includes('heap out of memory') ||
+            msg.includes('JavaScript heap')) {
+            console.error('  This error typically occurs on very large repositories.');
+            console.error('  Suggestions:');
+            console.error('    1. Add large vendored/generated directories to .codragraphignore');
+            console.error('    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"');
+            console.error('    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"');
+            console.error('');
+        }
+        else if (msg.includes('ERESOLVE') || msg.includes('Could not resolve dependency')) {
+            // Note: the original arborist "Cannot destructure property 'package' of
+            // 'node.target'" crash happens inside npm *before* codragraph code runs,
+            // so it can't be caught here.  This branch handles dependency-resolution
+            // errors that surface at runtime (e.g. dynamic require failures).
+            console.error('  This looks like an npm dependency resolution issue.');
+            console.error('  Suggestions:');
+            console.error('    1. Clear the npm cache:    npm cache clean --force');
+            console.error('    2. Update npm:             npm install -g npm@latest');
+            console.error('    3. Reinstall codragraph:     npm install -g codragraph@latest');
+            console.error('    4. Or try npx directly:    npx codragraph@latest analyze');
+            console.error('');
+        }
+        else if (msg.includes('MODULE_NOT_FOUND') ||
+            msg.includes('Cannot find module') ||
+            msg.includes('ERR_MODULE_NOT_FOUND')) {
+            console.error('  A required module could not be loaded. The installation may be corrupt.');
+            console.error('  Suggestions:');
+            console.error('    1. Reinstall:   npm install -g codragraph@latest');
+            console.error('    2. Clear cache: npm cache clean --force && npx codragraph@latest analyze');
+            console.error('');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // 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.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: codragraph augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+export declare function augmentCommand(pattern: string): Promise<void>;

package/dist/cli/augment.js

@@ -0,0 +1,33 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: codragraph augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+import { augment } from '../core/augmentation/engine.js';
+export async function augmentCommand(pattern) {
+    if (!pattern || pattern.length < 3) {
+        process.exit(0);
+    }
+    try {
+        const result = await augment(pattern, process.cwd());
+        if (result) {
+            // IMPORTANT: Write to stderr, NOT stdout.
+            // 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.
+            process.stderr.write(result + '\n');
+        }
+    }
+    catch {
+        // Graceful failure — never break the calling hook
+        process.exit(0);
+    }
+}