@codragraph/cli 1.6.4 → 2.1.0

package/dist/cli/graphstore.js

@@ -12,7 +12,7 @@ import fs from 'node:fs/promises';
 import { FsCAS, createBranch, createCommit, DEFAULT_BRANCH, deleteBranch, diffSemantic, diffSnapshots, gc as runGc, getJson, listBranches, materializeSnapshot, parseObjectId, readCommit, readHead, resolveHeadCommit, setHead, threeWayMerge, walkCommits, writeHeadBranch, writeHeadDetached, } from '@codragraph/graphstore';
 import { findRepo, loadMeta, saveMeta } from '../storage/repo-manager.js';
 import { GRAPHSTORE_SUBDIR } from '../core/graphstore/index.js';
-import { initLbug, closeLbug } from '../core/lbug/lbug-adapter.js';
+import { initCgdb, closeCgdb } from '../core/cgdb/cgdb-adapter.js';
 import { recordAnalysisSnapshot } from '../core/graphstore/index.js';
 import { getCurrentCommit, hasGitDir } from '../storage/git.js';
 const resolveGraphstore = async (cwd) => {
@@ -84,7 +84,7 @@ export const branchListCommand = async () => {
 // ──────────────────────────────────────────────────────────────────────
 // codragraph diff <from> <to>
 // ──────────────────────────────────────────────────────────────────────
-export const diffCommand = async (from, to) => {
+export const diffCommand = async (from, to, opts = {}) => {
     const ctx = await resolveGraphstore(process.cwd());
     const fromCommitId = await resolveCommitTarget(ctx, from);
     const toCommitId = await resolveCommitTarget(ctx, to);
@@ -95,6 +95,17 @@ export const diffCommand = async (from, to) => {
         from: fromCommit.snapshot,
         to: toCommit.snapshot,
     });
+    // --json: emit a machine-readable payload for downstream consumers
+    // (GitHub Action comment formatter, IDE plugins, etc). Keep human and
+    // JSON paths separate — never sneak JSON into the human path's stdout.
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({
+            from: { commit: fromCommitId, message: fromCommit.message },
+            to: { commit: toCommitId, message: toCommit.message },
+            diff,
+        }, null, 2) + '\n');
+        return;
+    }
     process.stdout.write(`From: ${fromCommitId.slice(7, 7 + 12)}  ${fromCommit.message}\n`);
     process.stdout.write(`To:   ${toCommitId.slice(7, 7 + 12)}  ${toCommit.message}\n\n`);
     let totalAdded = 0;
@@ -153,7 +164,7 @@ export const commitCommand = async (opts = {}) => {
     const repo = await findRepo(process.cwd());
     if (!repo)
         throw new Error('No CodraGraph index found');
-    await initLbug(repo.lbugPath);
+    await initCgdb(repo.cgdbPath);
     try {
         const result = await recordAnalysisSnapshot({
             storagePath: repo.storagePath,
@@ -180,7 +191,7 @@ export const commitCommand = async (opts = {}) => {
         }
     }
     finally {
-        await closeLbug();
+        await closeCgdb();
     }
     // Avoid unused warnings while keeping the import live for future callers.
     void ctx;
@@ -210,10 +221,10 @@ export const branchCreateCommand = async (name, opts = {}) => {
 // ──────────────────────────────────────────────────────────────────────
 //
 // Two modes:
-//   - default       : just move HEAD (no lbug rewrite). Cheap; good for
+//   - default       : just move HEAD (no cgdb rewrite). Cheap; good for
 //                     log/diff inspection from a different vantage point.
 //   - --materialize : also rebuild the live LadybugDB from the target
-//                     snapshot. Destructive of the current lbug state —
+//                     snapshot. Destructive of the current cgdb state —
 //                     run `commit` first if you have unsaved changes.
 export const checkoutCommand = async (target, opts = {}) => {
     const ctx = await resolveGraphstore(process.cwd());
@@ -236,9 +247,9 @@ export const checkoutCommand = async (target, opts = {}) => {
             throw new Error('No CodraGraph index found');
         const commit = await readCommit(ctx.cas, commitId);
         process.stdout.write(`materializing snapshot ${commit.snapshot.slice(7, 7 + 12)}...\n`);
-        // Wipe and reinit lbug.
-        await closeLbug();
-        for (const f of [repo.lbugPath, `${repo.lbugPath}.wal`, `${repo.lbugPath}.lock`]) {
+        // Wipe and reinit cgdb.
+        await closeCgdb();
+        for (const f of [repo.cgdbPath, `${repo.cgdbPath}.wal`, `${repo.cgdbPath}.lock`]) {
             try {
                 await fs.rm(f, { recursive: true, force: true });
             }
@@ -246,9 +257,9 @@ export const checkoutCommand = async (target, opts = {}) => {
                 /* swallow */
             }
         }
-        await initLbug(repo.lbugPath);
+        await initCgdb(repo.cgdbPath);
         try {
-            const sink = await createLbugRowSinkForCheckout(repo.lbugPath);
+            const sink = await createCgdbRowSinkForCheckout(repo.cgdbPath);
             const result = await materializeSnapshot({
                 cas: ctx.cas,
                 snapshotId: commit.snapshot,
@@ -258,14 +269,14 @@ export const checkoutCommand = async (target, opts = {}) => {
                 `${result.stats.edgeRowCount} edges\n`);
         }
         finally {
-            await closeLbug();
+            await closeCgdb();
         }
     }
 };
 // ──────────────────────────────────────────────────────────────────────
 // codragraph materialize <target> --into <path>
 // ──────────────────────────────────────────────────────────────────────
-// Read-only inspection: rebuild a snapshot into a fresh sibling lbug
+// Read-only inspection: rebuild a snapshot into a fresh sibling cgdb
 // without touching the live one. Useful for "let me query the graph as
 // it was at commit X" without disturbing current work.
 export const materializeCommand = async (target, opts) => {
@@ -284,9 +295,9 @@ export const materializeCommand = async (target, opts) => {
     catch {
         /* doesn't exist, good */
     }
-    await initLbug(into);
+    await initCgdb(into);
     try {
-        const sink = await createLbugRowSinkForCheckout(into);
+        const sink = await createCgdbRowSinkForCheckout(into);
         const result = await materializeSnapshot({
             cas: ctx.cas,
             snapshotId: commit.snapshot,
@@ -299,7 +310,7 @@ export const materializeCommand = async (target, opts) => {
             `edges:  ${result.stats.edgeRowCount}\n`);
     }
     finally {
-        await closeLbug();
+        await closeCgdb();
     }
 };
 // ──────────────────────────────────────────────────────────────────────
@@ -375,7 +386,7 @@ const locateSymbolHash = (manifest, symbolId, tableHint) => {
     return null;
 };
 // ──────────────────────────────────────────────────────────────────────
-// LbugRowSink — used by checkout --materialize and `materialize` command.
+// CgdbRowSink — used by checkout --materialize and `materialize` command.
 // ──────────────────────────────────────────────────────────────────────
 //
 // Bulk-loads rows back into a fresh LadybugDB instance. Phase 4 keeps it
@@ -383,9 +394,9 @@ const locateSymbolHash = (manifest, symbolId, tableHint) => {
 // `executeWithReusedStatement` helper. For typical repos (≤100k rows)
 // this finishes in seconds; CSV-based bulk loading is a Phase 4.5
 // optimization once we measure where the bottleneck actually is.
-const createLbugRowSinkForCheckout = async (lbugPath) => {
-    const { executeQuery } = await import('../core/lbug/lbug-adapter.js');
-    const { SCHEMA_QUERIES } = await import('../core/lbug/schema.js');
+const createCgdbRowSinkForCheckout = async (cgdbPath) => {
+    const { executeQuery } = await import('../core/cgdb/cgdb-adapter.js');
+    const { SCHEMA_QUERIES } = await import('../core/cgdb/schema.js');
     // Recreate the schema; the path was just wiped, so this is a clean install.
     for (const ddl of SCHEMA_QUERIES) {
         try {
@@ -413,7 +424,7 @@ const createLbugRowSinkForCheckout = async (lbugPath) => {
         endEdges: async () => { },
         finalize: async () => { },
     };
-    void lbugPath;
+    void cgdbPath;
     return sink;
 };
 const insertNode = async (executeQuery, table, row) => {
@@ -457,7 +468,7 @@ const cypherLiteral = (v) => {
         return JSON.stringify(v);
     if (typeof v === 'number' || typeof v === 'boolean')
         return String(v);
-    // Fall back to JSON for arrays / nested objects; the underlying lbug
+    // Fall back to JSON for arrays / nested objects; the underlying cgdb
     // schema is mostly scalar so this is rare.
     return JSON.stringify(v);
 };
@@ -581,7 +592,7 @@ const formatBytes = (n) => {
 // classified modifications, added/removed APIs, and process changes. We
 // expose it as a separate module-local helper so the CLI handler can
 // dispatch on the flag.
-export const diffSemanticCommand = async (from, to) => {
+export const diffSemanticCommand = async (from, to, opts = {}) => {
     const ctx = await resolveGraphstore(process.cwd());
     const fromCommit = await readCommit(ctx.cas, await resolveCommitTarget(ctx, from));
     const toCommit = await readCommit(ctx.cas, await resolveCommitTarget(ctx, to));
@@ -590,6 +601,17 @@ export const diffSemanticCommand = async (from, to) => {
         from: fromCommit.snapshot,
         to: toCommit.snapshot,
     });
+    // --json: same shape as diff (plain) but with the semantic payload. The
+    // PR-review GitHub Action consumes this directly to render the Markdown
+    // comment without parsing free-form text.
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({
+            from: { ref: from, message: fromCommit.message },
+            to: { ref: to, message: toCommit.message },
+            semantic: d,
+        }, null, 2) + '\n');
+        return;
+    }
     process.stdout.write(`From: ${from}  (${fromCommit.message})\n`);
     process.stdout.write(`To:   ${to}    (${toCommit.message})\n\n`);
     if (d.addedAPIs.length > 0) {

package/dist/cli/index-repo.js

@@ -49,7 +49,7 @@ export const indexCommand = async (inputPathParts, options) => {
         process.exitCode = 1;
         return;
     }
-    const { storagePath, lbugPath } = getStoragePaths(repoPath);
+    const { storagePath, cgdbPath } = getStoragePaths(repoPath);
     // ── Verify .codragraph/ exists ──────────────────────────────────────
     try {
         await fs.access(storagePath);
@@ -60,9 +60,9 @@ export const indexCommand = async (inputPathParts, options) => {
         process.exitCode = 1;
         return;
     }
-    // ── Verify lbug database exists ───────────────────────────────────
+    // ── Verify cgdb database exists ───────────────────────────────────
     try {
-        await fs.access(lbugPath);
+        await fs.access(cgdbPath);
     }
     catch {
         console.log(`  .codragraph/ folder exists but contains no LadybugDB index.`);

package/dist/cli/index.js

@@ -19,6 +19,7 @@ program
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
     .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('--skill-targets <list>', 'CSV of editor targets for --skills (claude, cursor, opencode, codex). Default: claude.')
     .option('--skip-agents-md', 'Skip updating the codragraph section in AGENTS.md and CLAUDE.md')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-git', 'Index a folder without requiring a .git directory')
@@ -28,12 +29,24 @@ program
     'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
+    .option('--no-setup', 'Skip the first-run editor setup (auto-runs once when ~/.codragraph/registry.json is missing)')
+    .option('--compress <encoding>', 'Compress per-row content (RFC 0001 Phase 2). One of: none (default), brotli, zstd. zstd requires Node ≥ 22.15.', 'none')
     .addHelpText('after', '\nEnvironment variables:\n' +
     '  CODRAGRAPH_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .codragraphignore)\n' +
     '  CODRAGRAPH_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
     '\nTip: `.codragraphignore` supports `.gitignore`-style negation. Add e.g.\n' +
     '     `!__tests__/` to index a directory that is auto-filtered by default (#771).')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
+program
+    .command('profile-heap [path]')
+    .description('Run analyze with heap-profile instrumentation (RFC 0002 Phase 1). ' +
+    'Writes per-phase v8 heap snapshots + a JSONL RSS timeline under ' +
+    '.codragraph/heap-profiles/, then prints a summary table.')
+    .option('-f, --force', 'Force full re-index (analyze flag, passed through)')
+    .option('--skip-git', 'Index a folder without requiring a .git directory')
+    .option('--no-setup', 'Skip first-run editor setup')
+    .option('--no-summary', 'Skip the post-run summary table (raw artifacts only)')
+    .action(createLazyAction(() => import('./profile-heap.js'), 'profileHeapCommand'));
 program
     .command('index [path...]')
     .description('Register an existing .codragraph/ folder into the global registry (no re-analysis needed)')
@@ -192,12 +205,13 @@ program
     .command('diff <from> <to>')
     .description('Structural diff between two graph commits or branches')
     .option('--semantic', 'Use the semantic differ (added APIs, classified modifications, processes)')
+    .option('--json', 'Emit machine-readable JSON instead of human-readable text (for CI / GitHub Action consumers)')
     .action(async (from, to, opts) => {
     const mod = await import('./graphstore.js');
     if (opts.semantic)
-        await mod.diffSemanticCommand(from, to);
+        await mod.diffSemanticCommand(from, to, { json: opts.json });
     else
-        await mod.diffCommand(from, to);
+        await mod.diffCommand(from, to, { json: opts.json });
 });
 program
     .command('merge <branch>')

package/dist/cli/profile-heap.d.ts

@@ -0,0 +1,35 @@
+/**
+ * profile-heap — RFC 0002 Phase 1 entry point.
+ *
+ * A thin wrapper around `analyze` that flips on the heap-profile
+ * instrumentation already living in `runFullAnalysis`, then prints a
+ * per-phase RSS / heapUsed summary table after the run finishes.
+ *
+ * Why a dedicated subcommand instead of just documenting the env var?
+ *   - Discoverability: `codragraph --help` lists it next to `analyze`.
+ *   - One-shot UX: users (and the maintainer) get a useful summary table
+ *     without having to spelunk through Chrome DevTools to compare
+ *     snapshots. The `.heapsnapshot` files are still written for deep
+ *     dives; the summary just makes the cheap signal (RSS curve, heapUsed
+ *     curve) visible at a glance.
+ *   - Phase 1 of RFC 0002 is profile-first by design — we ship the tool
+ *     before any mitigation. Don't add compression, eviction, or streaming
+ *     refactors here; that's Phase 2+ once we know which phase is the
+ *     actual bottleneck.
+ *
+ * Side effects: writes `.codragraph/heap-profiles/<ts>-<phase>.heapsnapshot`
+ * (one per phase boundary, ~100-500MB each) plus a small
+ * `profile-summary.jsonl` timeline. Disk usage adds up fast on large
+ * repos — clean up between runs if you don't need the raw snapshots.
+ */
+import { type AnalyzeOptions } from './analyze.js';
+export interface ProfileHeapOptions extends AnalyzeOptions {
+    /**
+     * Commander injects this from the `--no-summary` flag — see CLI
+     * registration. `--no-summary` ⇒ `summary === false`. The dual-name
+     * convention (positive flag name, negated value) is a commander
+     * footgun: a `noSummary?: boolean` field would silently never fire.
+     */
+    summary?: boolean;
+}
+export declare const profileHeapCommand: (inputPath?: string, options?: ProfileHeapOptions) => Promise<void>;

package/dist/cli/profile-heap.js

@@ -0,0 +1,126 @@
+/**
+ * profile-heap — RFC 0002 Phase 1 entry point.
+ *
+ * A thin wrapper around `analyze` that flips on the heap-profile
+ * instrumentation already living in `runFullAnalysis`, then prints a
+ * per-phase RSS / heapUsed summary table after the run finishes.
+ *
+ * Why a dedicated subcommand instead of just documenting the env var?
+ *   - Discoverability: `codragraph --help` lists it next to `analyze`.
+ *   - One-shot UX: users (and the maintainer) get a useful summary table
+ *     without having to spelunk through Chrome DevTools to compare
+ *     snapshots. The `.heapsnapshot` files are still written for deep
+ *     dives; the summary just makes the cheap signal (RSS curve, heapUsed
+ *     curve) visible at a glance.
+ *   - Phase 1 of RFC 0002 is profile-first by design — we ship the tool
+ *     before any mitigation. Don't add compression, eviction, or streaming
+ *     refactors here; that's Phase 2+ once we know which phase is the
+ *     actual bottleneck.
+ *
+ * Side effects: writes `.codragraph/heap-profiles/<ts>-<phase>.heapsnapshot`
+ * (one per phase boundary, ~100-500MB each) plus a small
+ * `profile-summary.jsonl` timeline. Disk usage adds up fast on large
+ * repos — clean up between runs if you don't need the raw snapshots.
+ */
+import path from 'path';
+import * as fsSync from 'node:fs';
+import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { analyzeCommand } from './analyze.js';
+export const profileHeapCommand = async (inputPath, options) => {
+    // Flip on the instrumentation BEFORE delegating to analyze. The env var
+    // is read by `runFullAnalysis` at orchestrator entry, so it must be set
+    // here. Setting it on every profile-heap invocation also guarantees that
+    // a leftover `unset` from a prior shell session can't disable profiling
+    // in this run.
+    process.env.CODRAGRAPH_HEAP_PROFILE = '1';
+    // Resolve the repo path the same way `analyze` does so we can locate the
+    // summary file after the run. Mirroring this avoids touching analyze's
+    // resolution logic, which already handles --skip-git, gitRoot, etc.
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot && !options?.skipGit) {
+            // Let analyze produce its standard error message + exit code rather
+            // than duplicating the message here.
+            await analyzeCommand(inputPath, options);
+            return;
+        }
+        repoPath = gitRoot ?? path.resolve(process.cwd());
+    }
+    if (!hasGitDir(repoPath) && !options?.skipGit) {
+        await analyzeCommand(inputPath, options);
+        return;
+    }
+    // Detect whether we're the outer (pre-re-exec) process. analyzeCommand
+    // calls ensureHeap() which `execFileSync`s a child with
+    // --max-old-space-size=8192 on first invocation; that child runs the
+    // instrumented codepath and prints its own summary before exiting. If
+    // we don't bail here, the outer process re-reads the just-written
+    // summary file and prints it a second time.
+    //
+    // Capture the flag BEFORE the await so a future change to NODE_OPTIONS
+    // mid-flight can't confuse us. (execFileSync's child env doesn't
+    // propagate back to process.env, but be defensive.)
+    const isInnerProcess = (process.env.NODE_OPTIONS || '').includes('--max-old-space-size');
+    await analyzeCommand(inputPath, options);
+    // Outer process: the inner already printed the summary on its way out.
+    if (!isInnerProcess)
+        return;
+    // `--no-summary` → commander sets options.summary === false.
+    if (options?.summary === false)
+        return;
+    const summaryPath = path.join(repoPath, '.codragraph', 'heap-profiles', 'profile-summary.jsonl');
+    if (!fsSync.existsSync(summaryPath)) {
+        // analyze re-execs itself with a larger heap on first invocation; the
+        // outer process never reaches the instrumented codepath. Tell the user
+        // where to find the artifacts in that case.
+        console.log(`\n  Heap profile summary not found at ${summaryPath}.\n` +
+            `  This is expected on the first call (analyze re-execs with --max-old-space-size).\n` +
+            `  Re-run \`codragraph profile-heap\` and the summary will appear in the second pass.\n`);
+        return;
+    }
+    const lines = fsSync
+        .readFileSync(summaryPath, 'utf8')
+        .split('\n')
+        .filter((l) => l.trim().length > 0);
+    const entries = [];
+    for (const line of lines) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            /* skip malformed lines — best-effort */
+        }
+    }
+    if (entries.length === 0) {
+        console.log(`\n  Heap profile summary at ${summaryPath} is empty.\n`);
+        return;
+    }
+    printSummary(entries, summaryPath);
+};
+function printSummary(entries, summaryPath) {
+    const peakRss = entries.reduce((m, e) => (e.rss > m ? e.rss : m), 0);
+    const peakHeapUsed = entries.reduce((m, e) => (e.heapUsed > m ? e.heapUsed : m), 0);
+    const startTs = entries[0].ts;
+    console.log('\n  Heap-profile summary');
+    console.log('  ────────────────────');
+    console.log('  Phase'.padEnd(28) +
+        '  Δt(s)'.padEnd(10) +
+        '  RSS(MB)'.padEnd(12) +
+        '  heapUsed(MB)'.padEnd(16) +
+        '  Snapshot');
+    for (const e of entries) {
+        const dt = ((e.ts - startTs) / 1000).toFixed(1);
+        const rssMb = (e.rss / 1024 / 1024).toFixed(0);
+        const heapMb = (e.heapUsed / 1024 / 1024).toFixed(0);
+        console.log(`  ${e.phase.padEnd(26)}  ${dt.padStart(6)}    ${rssMb.padStart(7)}    ${heapMb.padStart(11)}      ${e.snapshotFile}`);
+    }
+    console.log('  ────────────────────');
+    console.log(`  peak RSS:       ${(peakRss / 1024 / 1024).toFixed(0)} MB`);
+    console.log(`  peak heapUsed:  ${(peakHeapUsed / 1024 / 1024).toFixed(0)} MB`);
+    console.log(`  raw timeline:   ${summaryPath}`);
+    console.log(`  snapshots dir:  ${path.dirname(summaryPath)} (open .heapsnapshot files in Chrome DevTools → Memory → Load)\n`);
+}

package/dist/cli/setup.d.ts

@@ -5,4 +5,17 @@
  * Detects installed AI editors and writes the appropriate MCP config
  * so the CodraGraph MCP server is available in all projects.
  */
+interface SetupResult {
+    configured: string[];
+    skipped: string[];
+    errors: string[];
+}
+export interface RunSetupOptions {
+    /** Suppress the trailing "Next steps" block (used when analyze auto-runs setup). */
+    skipNextSteps?: boolean;
+    /** Suppress the "CodraGraph Setup" header (used when analyze auto-runs setup). */
+    compactHeader?: boolean;
+}
+export declare const runSetup: (options?: RunSetupOptions) => Promise<SetupResult>;
 export declare const setupCommand: () => Promise<void>;
+export {};

package/dist/cli/setup.js

@@ -519,12 +519,17 @@ async function installCodexSkills(result) {
         result.errors.push(`Codex skills: ${err.message}`);
     }
 }
-// ─── Main command ──────────────────────────────────────────────────
-export const setupCommand = async () => {
-    console.log('');
-    console.log('  CodraGraph Setup');
-    console.log('  ==============');
-    console.log('');
+export const runSetup = async (options = {}) => {
+    if (options.compactHeader) {
+        console.log('  CodraGraph: first-run editor setup');
+        console.log('');
+    }
+    else {
+        console.log('');
+        console.log('  CodraGraph Setup');
+        console.log('  ==============');
+        console.log('');
+    }
     // Ensure global directory exists
     const globalDir = getGlobalDir();
     await fs.mkdir(globalDir, { recursive: true });
@@ -569,10 +574,16 @@ export const setupCommand = async () => {
     console.log('  Summary:');
     console.log(`    MCP configured for: ${result.configured.filter((c) => !c.includes('skills')).join(', ') || 'none'}`);
     console.log(`    Skills installed to: ${result.configured.filter((c) => c.includes('skills')).length > 0 ? result.configured.filter((c) => c.includes('skills')).join(', ') : 'none'}`);
+    if (!options.skipNextSteps) {
+        console.log('');
+        console.log('  Next steps:');
+        console.log('    1. cd into any git repo');
+        console.log('    2. Run: codragraph analyze');
+        console.log('    3. Open the repo in your editor — MCP is ready!');
+    }
     console.log('');
-    console.log('  Next steps:');
-    console.log('    1. cd into any git repo');
-    console.log('    2. Run: codragraph analyze');
-    console.log('    3. Open the repo in your editor — MCP is ready!');
-    console.log('');
+    return result;
+};
+export const setupCommand = async () => {
+    await runSetup();
 };

package/dist/cli/skill-gen.d.ts

@@ -13,14 +13,26 @@ export interface GeneratedSkillInfo {
     symbolCount: number;
     fileCount: number;
 }
+/**
+ * Supported skill targets. Project-relative output paths mirror each editor's
+ * convention: Claude / Cursor use `skills/`, OpenCode uses `skill/` (singular)
+ * to match its global config layout, Codex uses `skills/`. The trailing
+ * `generated/` segment isolates auto-generated skills from human-authored ones.
+ */
+export declare const SKILL_TARGETS: readonly ["claude", "cursor", "opencode", "codex"];
+export type SkillTarget = (typeof SKILL_TARGETS)[number];
 /**
  * @brief Generate repo-specific skill files from detected communities
  * @param {string} repoPath - Absolute path to the repository root
  * @param {string} projectName - Human-readable project name
  * @param {PipelineResult} pipelineResult - In-memory pipeline data with communities, processes, graph
- * @returns {Promise<{ skills: GeneratedSkillInfo[], outputPath: string }>} Generated skill metadata
+ * @param {SkillTarget[]} targets - Editor targets to emit to. Defaults to ['claude'].
+ * @returns {Promise<{ skills: GeneratedSkillInfo[], outputPath: string, outputPaths: string[] }>}
+ *          `outputPath` is the Claude path (or first target) for backwards compat;
+ *          `outputPaths` lists every directory written to.
  */
-export declare const generateSkillFiles: (repoPath: string, projectName: string, pipelineResult: PipelineResult) => Promise<{
+export declare const generateSkillFiles: (repoPath: string, projectName: string, pipelineResult: PipelineResult, targets?: SkillTarget[]) => Promise<{
     skills: GeneratedSkillInfo[];
     outputPath: string;
+    outputPaths: string[];
 }>;

package/dist/cli/skill-gen.js

@@ -8,6 +8,20 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
+import { estimateTokens } from './compress-stats.js';
+/**
+ * Supported skill targets. Project-relative output paths mirror each editor's
+ * convention: Claude / Cursor use `skills/`, OpenCode uses `skill/` (singular)
+ * to match its global config layout, Codex uses `skills/`. The trailing
+ * `generated/` segment isolates auto-generated skills from human-authored ones.
+ */
+export const SKILL_TARGETS = ['claude', 'cursor', 'opencode', 'codex'];
+const SKILL_OUTPUT_DIRS = {
+    claude: ['.claude', 'skills', 'generated'],
+    cursor: ['.cursor', 'skills', 'generated'],
+    opencode: ['.opencode', 'skill', 'generated'],
+    codex: ['.codex', 'skills', 'generated'],
+};
 // ============================================================================
 // MAIN EXPORT
 // ============================================================================
@@ -16,14 +30,24 @@ import path from 'path';
  * @param {string} repoPath - Absolute path to the repository root
  * @param {string} projectName - Human-readable project name
  * @param {PipelineResult} pipelineResult - In-memory pipeline data with communities, processes, graph
- * @returns {Promise<{ skills: GeneratedSkillInfo[], outputPath: string }>} Generated skill metadata
+ * @param {SkillTarget[]} targets - Editor targets to emit to. Defaults to ['claude'].
+ * @returns {Promise<{ skills: GeneratedSkillInfo[], outputPath: string, outputPaths: string[] }>}
+ *          `outputPath` is the Claude path (or first target) for backwards compat;
+ *          `outputPaths` lists every directory written to.
  */
-export const generateSkillFiles = async (repoPath, projectName, pipelineResult) => {
+export const generateSkillFiles = async (repoPath, projectName, pipelineResult, targets = ['claude']) => {
     const { communityResult, processResult, graph } = pipelineResult;
-    const outputDir = path.join(repoPath, '.claude', 'skills', 'generated');
+    // Resolve all output dirs once. The "primary" path is Claude (if requested)
+    // or the first target — kept for AGENTS.md / CLAUDE.md generators that link
+    // to skill files relative to .claude/.
+    const effectiveTargets = targets.length > 0 ? targets : ['claude'];
+    const outputDirs = effectiveTargets.map((t) => path.join(repoPath, ...SKILL_OUTPUT_DIRS[t]));
+    const primaryDir = effectiveTargets.includes('claude')
+        ? path.join(repoPath, ...SKILL_OUTPUT_DIRS.claude)
+        : outputDirs[0];
     if (!communityResult || !communityResult.memberships.length) {
         console.log('\n  Skills: no communities detected, skipping skill generation');
-        return { skills: [], outputPath: outputDir };
+        return { skills: [], outputPath: primaryDir, outputPaths: outputDirs };
     }
     console.log('\n  Generating repo-specific skills...');
     // Step 1: Build communities from memberships (not the filtered communities array).
@@ -42,19 +66,21 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
         .slice(0, 20);
     if (significant.length === 0) {
         console.log('\n  Skills: no significant communities found (all below 3-symbol threshold)');
-        return { skills: [], outputPath: outputDir };
+        return { skills: [], outputPath: primaryDir, outputPaths: outputDirs };
     }
     // Step 3: Build lookup maps
     const membershipsByComm = buildMembershipMap(communityResult.memberships);
     const nodeIdToCommunityLabel = buildNodeCommunityLabelMap(communityResult.memberships, communities);
-    // Step 4: Clear and recreate output directory
-    try {
-        await fs.rm(outputDir, { recursive: true, force: true });
-    }
-    catch {
-        /* may not exist */
+    // Step 4: Clear and recreate every output directory we'll write to
+    for (const dir of outputDirs) {
+        try {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+        catch {
+            /* may not exist */
+        }
+        await fs.mkdir(dir, { recursive: true });
     }
-    await fs.mkdir(outputDir, { recursive: true });
     // Step 5: Generate skill files
     const skills = [];
     const usedNames = new Set();
@@ -76,10 +102,13 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
         usedNames.add(kebabName);
         // Generate SKILL.md content
         const content = renderSkillMarkdown(community, projectName, members, files, entryPoints, flows, connections, kebabName);
-        // Write file
-        const skillDir = path.join(outputDir, kebabName);
-        await fs.mkdir(skillDir, { recursive: true });
-        await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+        // Write the same SKILL.md to each requested editor target
+        for (const dir of outputDirs) {
+            const skillDir = path.join(dir, kebabName);
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+        }
+        const skillTokens = estimateTokens(content);
         const info = {
             name: kebabName,
             label: community.label,
@@ -87,10 +116,14 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
             fileCount: files.length,
         };
         skills.push(info);
-        console.log(`    \u2713 ${community.label} (${community.symbolCount} symbols, ${files.length} files)`);
+        // Show the @codragraph/compress headline number per skill: how many
+        // tokens of distilled context this community boils down to.
+        console.log(`    \u2713 ${community.label} (${community.symbolCount} symbols, ${files.length} files) ` +
+            `\u2192 ~${skillTokens.toLocaleString()} tokens`);
     }
-    console.log(`\n  ${skills.length} skills generated \u2192 .claude/skills/generated/`);
-    return { skills, outputPath: outputDir };
+    const targetSummary = effectiveTargets.join(', ');
+    console.log(`\n  ${skills.length} skills generated \u2192 ${targetSummary}`);
+    return { skills, outputPath: primaryDir, outputPaths: outputDirs };
 };
 // ============================================================================
 // FALLBACK COMMUNITY BUILDER