@codragraph/cli 1.6.3 → 2.0.0

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

@@ -18,20 +18,38 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
 /**
- * Resolve the absolute path to the `@codragraph/cli` binary if it's installed
+ * Resolve the absolute path to the `codragraph` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
+ *
+ * Note: the npm package is `@codragraph/cli`, but the executable it installs
+ * is `codragraph` (see package.json `bin`). PATH lookup must use the bin name.
+ *
+ * Windows specifics: `where codragraph` returns every PATH entry, in order:
+ * the extensionless Unix shim npm creates first (a sh script — Node's
+ * spawn/execFile cannot launch it on Windows), then `codragraph.cmd`,
+ * then `codragraph.ps1`. We must pick the .cmd / .exe / .bat entry; writing
+ * the extensionless path into a downstream MCP config produces a launcher
+ * that fails on every spawn.
  */
 function resolveCodragraphBin() {
     try {
         const cmd = process.platform === 'win32' ? 'where' : 'which';
-        const resolved = execFileSync(cmd, ['@codragraph/cli'], {
+        const stdout = execFileSync(cmd, ['codragraph'], {
             encoding: 'utf-8',
             timeout: 5000,
             stdio: ['ignore', 'pipe', 'ignore'],
-        })
-            .split('\n')[0]
-            .trim();
-        return resolved || null;
+        });
+        const lines = stdout
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean);
+        if (process.platform === 'win32') {
+            // Prefer a Windows-executable shim. If none is on PATH, return null so
+            // the caller falls through to the `cmd /c npx -y @codragraph/cli` path.
+            const exe = lines.find((l) => /\.(cmd|exe|bat)$/i.test(l));
+            return exe ?? null;
+        }
+        return lines[0] ?? null;
     }
     catch {
         return null;
@@ -40,28 +58,38 @@ function resolveCodragraphBin() {
 /**
  * The MCP server entry for all editors.
  *
- * Prefers the globally-installed `@codragraph/cli` binary (starts in ~1 s) over
- * `npx -y codragraph@latest` (cold-cache install of native deps can take
+ * Prefers the globally-installed `codragraph` binary (starts in ~1 s) over
+ * `npx -y @codragraph/cli@latest` (cold-cache install of native deps can take
  * >60 s, exceeding Claude Code's 30 s MCP connection timeout).
  *
  * Falls back to npx when the binary isn't on PATH — e.g. first-time
- * users who ran `npx codragraph analyze` but haven't done `npm i -g`.
+ * users who ran `npx @codragraph/cli analyze` but haven't done `npm i -g`.
+ *
+ * Windows note: even when the bin is on PATH, we launch via `cmd /c codragraph
+ * mcp` rather than writing the resolved path. Reason: `where codragraph`
+ * returns the extensionless Unix shim before `codragraph.cmd`, and Node's
+ * spawn/execFile cannot launch the extensionless shim on Windows. Letting
+ * cmd resolve via PATHEXT is the only reliable path that works for npm-,
+ * pnpm-, and yarn-installed shims alike.
  */
 function getMcpEntry() {
     const bin = resolveCodragraphBin();
     if (bin) {
+        if (process.platform === 'win32') {
+            return { command: 'cmd', args: ['/c', 'codragraph', 'mcp'] };
+        }
         return { command: bin, args: ['mcp'] };
     }
     // Fallback: npx (works without a global install, but slow cold-start)
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', 'codragraph@latest', 'mcp'],
+            args: ['/c', 'npx', '-y', '@codragraph/cli@latest', 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', 'codragraph@latest', 'mcp'],
+        args: ['-y', '@codragraph/cli@latest', 'mcp'],
     };
 }
 /**
@@ -71,12 +99,18 @@ function getMcpEntry() {
 function getOpenCodeMcpEntry() {
     const bin = resolveCodragraphBin();
     if (bin) {
+        if (process.platform === 'win32') {
+            return { type: 'local', command: ['cmd', '/c', 'codragraph', 'mcp'] };
+        }
         return { type: 'local', command: [bin, 'mcp'] };
     }
     if (process.platform === 'win32') {
-        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', 'codragraph@latest', 'mcp'] };
+        return {
+            type: 'local',
+            command: ['cmd', '/c', 'npx', '-y', '@codragraph/cli@latest', 'mcp'],
+        };
     }
-    return { type: 'local', command: ['npx', '-y', 'codragraph@latest', 'mcp'] };
+    return { type: 'local', command: ['npx', '-y', '@codragraph/cli@latest', 'mcp'] };
 }
 /**
  * Merge codragraph entry into an existing MCP config JSON object.
@@ -239,7 +273,7 @@ async function installClaudeCodeHooks(result) {
     // Source hooks bundled within the codragraph package (hooks/claude/)
     const pluginHooksPath = path.join(__dirname, '..', '..', 'hooks', 'claude');
     // Copy unified hook script to ~/.claude/hooks/codragraph/
-    const destHooksDir = path.join(claudeDir, 'hooks', '@codragraph/cli');
+    const destHooksDir = path.join(claudeDir, 'hooks', 'codragraph');
     try {
         await fs.mkdir(destHooksDir, { recursive: true });
         const src = path.join(pluginHooksPath, 'codragraph-hook.cjs');
@@ -291,7 +325,7 @@ async function setupOpenCode(result) {
     }
     const configPath = path.join(opencodeDir, 'opencode.json');
     try {
-        const ok = await mergeJsoncFile(configPath, ['mcp', '@codragraph/cli'], getOpenCodeMcpEntry());
+        const ok = await mergeJsoncFile(configPath, ['mcp', 'codragraph'], getOpenCodeMcpEntry());
         if (ok) {
             result.configured.push('OpenCode');
         }
@@ -339,9 +373,10 @@ async function setupCodex(result) {
     }
     try {
         const entry = getMcpEntry();
-        await execFileAsync('codex', ['mcp', 'add', '@codragraph/cli', '--', entry.command, ...entry.args], {
-            shell: process.platform === 'win32',
-        });
+        // On Windows, npm-installed CLIs ship as .cmd shims that Node's execFile
+        // can only invoke when the file extension is explicit (no PATHEXT lookup).
+        const codexBin = process.platform === 'win32' ? 'codex.cmd' : 'codex';
+        await execFileAsync(codexBin, ['mcp', 'add', 'codragraph', '--', entry.command, ...entry.args]);
         result.configured.push('Codex');
         return;
     }
@@ -484,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 });
@@ -534,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
@@ -103,7 +136,7 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
  * @param {string} repoPath - Repository root for path normalization
  * @returns {CommunityNode[]} Synthetic community nodes built from membership data
  */
-const buildCommunitiesFromMemberships = (memberships, graph, repoPath) => {
+const buildCommunitiesFromMemberships = (memberships, graph, _repoPath) => {
     // Group memberships by communityId
     const groups = new Map();
     for (const m of memberships) {

package/dist/cli/tool.js

@@ -16,6 +16,7 @@
  */
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
+import { emitTokenStats } from './compress-stats.js';
 let _backend = null;
 async function getBackend() {
     if (_backend)
@@ -68,6 +69,7 @@ export async function queryCommand(queryText, options) {
         repo: options?.repo,
     });
     output(result);
+    emitTokenStats(result);
 }
 export async function contextCommand(name, options) {
     if (!name?.trim() && !options?.uid) {
@@ -83,6 +85,7 @@ export async function contextCommand(name, options) {
         repo: options?.repo,
     });
     output(result);
+    emitTokenStats(result);
 }
 export async function impactCommand(target, options) {
     if (!target?.trim()) {
@@ -99,6 +102,7 @@ export async function impactCommand(target, options) {
             repo: options?.repo,
         });
         output(result);
+        emitTokenStats(result);
     }
     catch (err) {
         // Belt-and-suspenders: catch infrastructure failures (getBackend, callTool transport)

package/dist/config/ignore-service.js

@@ -285,7 +285,7 @@ export const shouldIgnorePath = (filePath) => {
     // Ignore hidden files (starting with .)
     if (fileName.startsWith('.') && fileName !== '.') {
         // But allow some important config files
-        const allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
+        const _allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
         // Actually, let's NOT ignore all dot files - many are important configs
         // Just rely on the explicit lists above
     }

package/dist/core/embeddings/embedding-pipeline.js

@@ -16,6 +16,7 @@ import { extractStructuralNames } from './structural-extractor.js';
 import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
+import { decodeContentField } from '../lbug/content-read.js';
 const isDev = process.env.NODE_ENV === 'development';
 /**
  * Bump this when the embedding text template changes in a way that should
@@ -46,12 +47,17 @@ const queryEmbeddableNodes = async (executeQuery) => {
     for (const label of EMBEDDABLE_LABELS) {
         try {
             let query;
+            // RFC 0001 Phase 2: pull contentEncoding alongside content so we
+            // hand DECODED text to the embedder. Embedding compressed bytes
+            // would silently destroy semantic search quality without any
+            // visible error — decode is mandatory at this boundary.
             if (label === LABEL_METHOD) {
                 // Method has parameterCount and returnType
                 query = `
           MATCH (n:Method)
           RETURN n.id AS id, n.name AS name, 'Method' AS label,
                  n.filePath AS filePath, n.content AS content,
+                 n.contentEncoding AS contentEncoding,
                  n.startLine AS startLine, n.endLine AS endLine,
                  n.isExported AS isExported, n.description AS description,
                  n.parameterCount AS parameterCount, n.returnType AS returnType
@@ -63,6 +69,7 @@ const queryEmbeddableNodes = async (executeQuery) => {
           MATCH (n:\`${label}\`)
           RETURN n.id AS id, n.name AS name, '${label}' AS label,
                  n.filePath AS filePath, n.content AS content,
+                 n.contentEncoding AS contentEncoding,
                  n.startLine AS startLine, n.endLine AS endLine,
                  n.isExported AS isExported, n.description AS description
         `;
@@ -73,6 +80,7 @@ const queryEmbeddableNodes = async (executeQuery) => {
           MATCH (n:\`${label}\`)
           RETURN n.id AS id, n.name AS name, '${label}' AS label,
                  n.filePath AS filePath, n.content AS content,
+                 n.contentEncoding AS contentEncoding,
                  n.startLine AS startLine, n.endLine AS endLine,
                  n.description AS description
         `;
@@ -80,20 +88,29 @@ const queryEmbeddableNodes = async (executeQuery) => {
             const rows = await executeQuery(query);
             for (const row of rows) {
                 const hasExportedColumn = label === LABEL_METHOD || LABELS_WITH_EXPORTED.has(label);
+                // Column layout (every variant of the query above shares the
+                // first six positions; later columns differ by label):
+                //   0=id, 1=name, 2=label, 3=filePath,
+                //   4=content, 5=contentEncoding,
+                //   6=startLine, 7=endLine,
+                //   8=isExported  (Method + LABELS_WITH_EXPORTED only)
+                //   8 or 9=description (depending on isExported presence)
+                //   10=parameterCount, 11=returnType (Method only)
+                const decoded = decodeContentField(row.content ?? row[4], row.contentEncoding ?? row[5]);
                 allNodes.push({
                     id: row.id ?? row[0],
                     name: row.name ?? row[1],
                     label: row.label ?? row[2],
                     filePath: row.filePath ?? row[3],
-                    content: row.content ?? row[4] ?? '',
-                    startLine: row.startLine ?? row[5],
-                    endLine: row.endLine ?? row[6],
-                    isExported: hasExportedColumn ? (row.isExported ?? row[7]) : undefined,
-                    description: row.description ?? (hasExportedColumn ? row[8] : row[7]),
+                    content: decoded ?? '',
+                    startLine: row.startLine ?? row[6],
+                    endLine: row.endLine ?? row[7],
+                    isExported: hasExportedColumn ? (row.isExported ?? row[8]) : undefined,
+                    description: row.description ?? (hasExportedColumn ? row[9] : row[8]),
                     ...(label === LABEL_METHOD
                         ? {
-                            parameterCount: row.parameterCount ?? row[9],
-                            returnType: row.returnType ?? row[10],
+                            parameterCount: row.parameterCount ?? row[10],
+                            returnType: row.returnType ?? row[11],
                         }
                         : {}),
                 });