@codragraph/cli 2.1.4 → 2.1.6

package/README.md

@@ -25,6 +25,16 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 The same CLI commands work in Windows PowerShell, macOS bash/zsh, and Linux shells. Use `npx @codragraph/cli ...` for no-install runs or `codragraph ...` after a global install.
 
+Smart analyze now patches the existing graph for normal day-to-day changes:
+source edits, renames, large diffs, and topology-only files replace only the
+affected file-scoped rows, then recompute communities, execution flows, and
+FeatureCluster packs. Package/config or ignore-rule inputs refresh all
+file-scoped rows without falling back to a full cold rebuild. Generated agent
+context, lockfile-only, and ignored asset changes reuse the existing graph and
+advance metadata. Each pass refreshes `.codragraph/structure/`, a compact
+what/why/how/when/where markdown pack with branch/index state, bounded history,
+and SQLite seed SQL for external agent memory.
+
 To configure MCP for your editor, run `npx @codragraph/cli setup` once — or set it up manually below.
 
 `codragraph setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
@@ -55,16 +65,16 @@ If you prefer to configure manually instead of using `codragraph setup`:
 
 ```bash
 # macOS / Linux
-claude mcp add codragraph -- npx -y @codragraph/cli@2.1.2 mcp
+claude mcp add codragraph -- npx -y @codragraph/cli@2.1.6 mcp
 
 # Windows
-claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.2 mcp
+claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.6 mcp
 ```
 
 ### Codex (full support — MCP + skills)
 
 ```bash
-codex mcp add codragraph -- npx -y @codragraph/cli@2.1.2 mcp
+codex mcp add codragraph -- npx -y @codragraph/cli@2.1.6 mcp
 ```
 
 ### Cursor / Windsurf
@@ -76,7 +86,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.2", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.6", "mcp"]
     }
   }
 }
@@ -91,7 +101,7 @@ Add to `~/.config/opencode/config.json`:
   "mcp": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.2", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.6", "mcp"]
     }
   }
 }
@@ -177,6 +187,8 @@ codragraph serve --web hosted      # API only; connect from hosted web UI
 codragraph index                   # Register an existing .codragraph/ folder into the global registry
 codragraph list                    # List all indexed repositories
 codragraph status                  # Show index status for current repo
+codragraph detect-changes --scope unstaged  # Map working-tree diff to symbols/processes
+codragraph detect-changes --scope all       # Include staged + unstaged changes
 codragraph clean                   # Delete index for current repo
 codragraph clean --all --force     # Delete all indexes
 codragraph wiki [path]             # Generate LLM-powered docs from knowledge graph
@@ -297,9 +309,9 @@ It is fixed in **codragraph v1.6.2+**. Upgrade to the current workspace
 version, or pin the version your team has validated:
 
 ```bash
-npx @codragraph/cli@2.1.2 analyze          # no global install
+npx @codragraph/cli@2.1.6 analyze          # no global install
 # or
-npm install -g @codragraph/cli@2.1.2       # upgrade a global install
+npm install -g @codragraph/cli@2.1.6       # upgrade a global install
 ```
 
 If you still hit npm install issues after upgrading, these generic workarounds
@@ -342,6 +354,23 @@ echo "vendor/" >> .codragraphignore
 echo "dist/" >> .codragraphignore
 ```
 
+If the analyzer reports a worker sub-batch timeout or falls back to sequential
+parsing while files are still being processed, reduce worker batch memory and
+allow a longer idle window:
+
+```bash
+# macOS/Linux bash/zsh
+CODRAGRAPH_WORKER_SUB_BATCH_SIZE=100 CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS=180000 npx @codragraph/cli analyze
+
+# Windows PowerShell
+$env:CODRAGRAPH_WORKER_SUB_BATCH_SIZE = "100"
+$env:CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS = "180000"
+npx @codragraph/cli analyze
+```
+
+The worker timer is an idle guard. Parser progress resets it, so a slow repo
+should keep moving instead of paying the old 30-second wall-clock fallback.
+
 If you want to know **which phase** is dragging the heap up before
 deciding what to mitigate, run `codragraph profile-heap`. It writes a
 v8 heap snapshot at every phase boundary plus a JSONL timeline of

package/dist/cli/ai-context.js

@@ -8,11 +8,14 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { execFileSync } from 'node:child_process';
 // 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 -->';
+const AGENT_STRUCTURE_DIR = 'structure';
+const AGENT_HISTORY_LIMIT = 20;
 /**
  * Find the index of a section marker that occupies its own line.
  * Unlike `indexOf`, this rejects inline prose references like
@@ -113,6 +116,7 @@ This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` ($
 | \`codragraph://repo/${projectName}/feature/{name}\` | Focused files, line ranges, flows, dependencies |
 | \`codragraph://repo/${projectName}/processes\` | All execution flows |
 | \`codragraph://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+| \`.codragraph/structure/README.md\` | Local what/why/how/when/where memory, branch state, and SQLite seed |
 
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
@@ -174,6 +178,292 @@ async function upsertCodraGraphSection(filePath, content) {
     await fs.writeFile(filePath, newContent, 'utf-8');
     return 'appended';
 }
+async function readJsonFile(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function gitValue(repoPath, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function statValue(value) {
+    return value === undefined || value === null || value === '' ? 'unknown' : String(value);
+}
+function shortCommit(value) {
+    return value ? value.slice(0, 12) : 'unknown';
+}
+function sqlString(value) {
+    return String(value ?? '').replace(/'/g, "''");
+}
+async function buildAgentStructureState(repoPath, storagePath, projectName, stats) {
+    const meta = await readJsonFile(path.join(storagePath, 'meta.json'));
+    const currentGitHead = gitValue(repoPath, ['rev-parse', 'HEAD']);
+    const currentBranch = gitValue(repoPath, ['branch', '--show-current']) ||
+        gitValue(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    return {
+        projectName,
+        repoPath,
+        storagePath,
+        generatedAt: new Date().toISOString(),
+        indexedAt: meta?.indexedAt,
+        currentBranch: currentBranch || undefined,
+        currentGitHead: currentGitHead || undefined,
+        indexedCommit: meta?.lastCommit || currentGitHead || undefined,
+        remoteUrl: meta?.remoteUrl,
+        schemaVersion: meta?.schemaVersion,
+        compress: meta?.compress,
+        graphstoreBranch: meta?.currentBranch,
+        graphstoreHeadCommit: meta?.headCommit,
+        stats: {
+            files: stats.files ?? meta?.stats?.files,
+            nodes: stats.nodes ?? meta?.stats?.nodes,
+            edges: stats.edges ?? meta?.stats?.edges,
+            communities: stats.communities ?? meta?.stats?.communities,
+            clusters: stats.clusters ?? meta?.stats?.featureClusters,
+            processes: stats.processes ?? meta?.stats?.processes,
+            embeddings: meta?.stats?.embeddings,
+        },
+    };
+}
+function buildStructureDocs(state) {
+    const statsTable = `| Metric | Value |
+|---|---|
+| Files | ${statValue(state.stats.files)} |
+| Symbols | ${statValue(state.stats.nodes)} |
+| Relationships | ${statValue(state.stats.edges)} |
+| Feature clusters | ${statValue(state.stats.clusters)} |
+| Execution flows | ${statValue(state.stats.processes)} |
+| Embeddings | ${statValue(state.stats.embeddings)} |
+| Compression | ${statValue(state.compress)} |
+| Schema version | ${statValue(state.schemaVersion)} |`;
+    const branchTable = `| Field | Value |
+|---|---|
+| Current git branch | ${statValue(state.currentBranch)} |
+| Current git HEAD | ${statValue(state.currentGitHead)} |
+| Indexed commit | ${statValue(state.indexedCommit)} |
+| Indexed at | ${statValue(state.indexedAt)} |
+| Graphstore branch | ${statValue(state.graphstoreBranch)} |
+| Graphstore head commit | ${statValue(state.graphstoreHeadCommit)} |
+| Remote | ${statValue(state.remoteUrl)} |`;
+    return {
+        'README.md': `# CodraGraph Agent Structure
+
+Generated: ${state.generatedAt}
+
+This folder is the small, pre-seeded context pack for AI agents. It is rebuilt
+by \`codragraph analyze\` so agents can read stable markdown instead of guessing
+from stale terminal output.
+
+Read order:
+
+1. [WHAT.md](WHAT.md) - what this index represents.
+2. [WHY.md](WHY.md) - why the agent should use graph context first.
+3. [HOW.md](HOW.md) - how to query, analyze, and recover safely.
+4. [WHEN.md](WHEN.md) - when to refresh, reuse, or clean the index.
+5. [WHERE.md](WHERE.md) - where local storage, MCP, HTTP, and docs live.
+6. [BRANCHES.md](BRANCHES.md) - branch, commit, and graphstore state.
+7. [SQLITE.md](SQLITE.md) - SQLite-compatible seed data for external agent memory.
+`,
+        'WHAT.md': `# What
+
+CodraGraph index name: **${state.projectName}**
+
+This index stores a local code graph for the repository at:
+
+\`${state.repoPath}\`
+
+The graph includes file structure, symbols, relationships, imports, execution
+flows, feature clusters, Markdown graph docs, and optional embeddings. Agents
+should use this pack as the first local orientation layer, then ask MCP/CLI for
+live graph details.
+
+${statsTable}
+`,
+        'WHY.md': `# Why
+
+AI agents should not rebuild project understanding from raw grep every time.
+This folder gives them a compact, reusable map of the current indexed state.
+
+Use it to avoid:
+
+- Querying the wrong registered repo.
+- Running multiple analyzers against the same .codragraph store.
+- Treating stale branch or commit context as fresh.
+- Enabling embeddings by default when BM25 and graph search are enough.
+- Deleting index files when a targeted analyze or clean command is safer.
+`,
+        'HOW.md': `# How
+
+Safe command flow for agents:
+
+1. Read this folder and \`AGENTS.md\` / \`CLAUDE.md\`.
+2. Run \`codragraph status\` or \`npx @codragraph/cli status\`.
+3. Use MCP \`query\`, \`context\`, \`impact\`, and \`detect_changes\` for graph work.
+4. Run \`codragraph analyze\` only when the index is missing or stale.
+5. Use \`--repo ${state.projectName}\` when running from outside this checkout.
+
+Do not run \`analyze\`, \`detect-changes\`, \`clean\`, or DB-writing commands from
+editor hooks. Hooks should stay bounded and read-only.
+`,
+        'WHEN.md': `# When
+
+Refresh with \`codragraph analyze\` when:
+
+- The repo was never indexed.
+- MCP or CLI reports stale graph context.
+- Source files, Markdown graph docs, language config, or path topology changed.
+- Schema, compression, or embedding settings changed.
+
+Reuse the existing graph when only generated agent context, lockfiles, or
+ignored assets changed. Use \`codragraph analyze --force\` when ignore rules
+changed or corruption is suspected. Ask before \`codragraph clean --force\`.
+`,
+        'WHERE.md': `# Where
+
+| Item | Location |
+|---|---|
+| Repository | \`${state.repoPath}\` |
+| Local index storage | \`${state.storagePath}\` |
+| Agent structure pack | \`${path.join(state.storagePath, AGENT_STRUCTURE_DIR)}\` |
+| Root agent instructions | \`AGENTS.md\`, \`CLAUDE.md\` |
+| Claude skills | \`.claude/skills/@codragraph/cli/\` |
+| HTTP API | \`http://127.0.0.1:4747/api/info\` after \`codragraph serve\` |
+| MCP tools | \`codragraph mcp\` |
+`,
+        'BRANCHES.md': `# Branches And Commits
+
+${branchTable}
+
+The indexed commit is the source-of-truth for whether graph answers are fresh.
+If \`Current git HEAD\` and \`Indexed commit\` differ, agents should say the graph
+is stale and run \`codragraph analyze\` before relying on impact, context, or
+detect-changes output.
+`,
+        'INDEX.md': `# Index Snapshot
+
+${statsTable}
+
+Storage notes:
+
+- BM25 and graph traversal work without embeddings.
+- Embeddings are optional and should be preserved with \`--embeddings\` only
+  when semantic/vector search is intentionally required.
+- Compression mode is recorded in \`.codragraph/meta.json\`.
+- This markdown pack is small and should not be embedded or vectorized.
+`,
+        'SQLITE.md': `# SQLite Seed
+
+\`agent-memory.sql\` is a SQLite-compatible seed file for external agent memory
+stores. CodraGraph writes it as plain SQL so installs stay light on Node 20 and
+do not pull native SQLite dependencies into the CLI hot path.
+
+Optional import:
+
+\`\`\`sh
+sqlite3 agent-memory.sqlite < agent-memory.sql
+\`\`\`
+
+The canonical live source remains \`.codragraph/meta.json\` plus the graph DB.
+`,
+    };
+}
+function buildSqlSeed(state) {
+    const rows = [
+        ['project_name', state.projectName],
+        ['repo_path', state.repoPath],
+        ['storage_path', state.storagePath],
+        ['generated_at', state.generatedAt],
+        ['indexed_at', state.indexedAt],
+        ['current_branch', state.currentBranch],
+        ['current_git_head', state.currentGitHead],
+        ['indexed_commit', state.indexedCommit],
+        ['remote_url', state.remoteUrl],
+        ['schema_version', state.schemaVersion],
+        ['compress', state.compress],
+        ['graphstore_branch', state.graphstoreBranch],
+        ['graphstore_head_commit', state.graphstoreHeadCommit],
+        ['stats_json', JSON.stringify(state.stats)],
+    ];
+    const values = rows
+        .map(([key, value]) => `('${sqlString(key)}', '${sqlString(value)}', '${sqlString(state.generatedAt)}')`)
+        .join(',\n');
+    return `BEGIN;
+CREATE TABLE IF NOT EXISTS codragraph_agent_context (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+DELETE FROM codragraph_agent_context;
+INSERT INTO codragraph_agent_context (key, value, updated_at) VALUES
+${values};
+COMMIT;
+`;
+}
+async function buildHistoryContent(historyPath, state) {
+    const entryId = (state.indexedCommit || 'no-git').replace(/[^a-zA-Z0-9._-]/g, '_');
+    const entry = `<!-- codragraph:history-entry:${entryId} -->
+## ${shortCommit(state.indexedCommit)} - ${state.generatedAt}
+
+- Branch: ${statValue(state.currentBranch)}
+- Indexed commit: ${statValue(state.indexedCommit)}
+- Git HEAD: ${statValue(state.currentGitHead)}
+- Graphstore: ${statValue(state.graphstoreBranch)} / ${statValue(state.graphstoreHeadCommit)}
+- Stats: ${statValue(state.stats.nodes)} symbols, ${statValue(state.stats.edges)} relationships, ${statValue(state.stats.processes)} flows
+<!-- /codragraph:history-entry -->`;
+    let existing = '';
+    try {
+        existing = await fs.readFile(historyPath, 'utf-8');
+    }
+    catch {
+        /* first run */
+    }
+    const blocks = [];
+    const regex = /<!-- codragraph:history-entry:([^ ]+) -->[\s\S]*?<!-- \/codragraph:history-entry -->/g;
+    let match;
+    while ((match = regex.exec(existing)) !== null) {
+        if (match[1] !== entryId)
+            blocks.push(match[0]);
+    }
+    return `# Analyze History
+
+Most recent CodraGraph analyze or smart-reuse events. Bounded to the latest
+${AGENT_HISTORY_LIMIT} entries so this file remains small.
+
+${[entry, ...blocks].slice(0, AGENT_HISTORY_LIMIT).join('\n\n')}
+`;
+}
+async function generateAgentStructurePack(repoPath, storagePath, projectName, stats) {
+    const structureDir = path.join(storagePath, AGENT_STRUCTURE_DIR);
+    await fs.mkdir(structureDir, { recursive: true });
+    const state = await buildAgentStructureState(repoPath, storagePath, projectName, stats);
+    const docs = buildStructureDocs(state);
+    const written = [];
+    for (const [fileName, content] of Object.entries(docs)) {
+        await fs.writeFile(path.join(structureDir, fileName), content.trim() + '\n', 'utf-8');
+        written.push(fileName);
+    }
+    await fs.writeFile(path.join(structureDir, 'state.json'), JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    written.push('state.json');
+    await fs.writeFile(path.join(structureDir, 'agent-memory.sql'), buildSqlSeed(state), 'utf-8');
+    written.push('agent-memory.sql');
+    const historyPath = path.join(structureDir, 'HISTORY.md');
+    await fs.writeFile(historyPath, await buildHistoryContent(historyPath, state), 'utf-8');
+    written.push('HISTORY.md');
+    return written;
+}
 /**
  * Install CodraGraph skills to .claude/skills/codragraph/
  * Works natively with Claude Code, Cursor, and GitHub Copilot
@@ -265,6 +555,13 @@ export async function generateAIContextFiles(repoPath, _storagePath, projectName
         createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
         createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
     }
+    try {
+        const structureFiles = await generateAgentStructurePack(repoPath, _storagePath, projectName, stats);
+        createdFiles.push(`.codragraph/structure/ (${structureFiles.length} files)`);
+    }
+    catch (err) {
+        console.warn('Warning: Could not generate .codragraph/structure agent pack:', err);
+    }
     // Install skills to .claude/skills/codragraph/
     const installedSkills = await installSkills(repoPath);
     if (installedSkills.length > 0) {

package/dist/cli/analyze.d.ts

@@ -7,9 +7,14 @@
  * This CLI wrapper handles: heap management, progress bar, SIGINT,
  * skill generation (--skills), summary output, and process.exit().
  */
+import { type AnalyzeProfileOption, type CompressionOption, type EmbeddingMode } from '../core/adaptive-profile.js';
 export interface AnalyzeOptions {
     force?: boolean;
     embeddings?: boolean;
+    /** Adaptive runtime profile. `auto` detects CPU/RAM/heap and chooses lean/balanced/power. */
+    profile?: AnalyzeProfileOption;
+    /** Embedding policy. `--embeddings` is kept as a shortcut for `on`. */
+    embeddingMode?: EmbeddingMode;
     skills?: boolean;
     verbose?: boolean;
     /** Skip AGENTS.md and CLAUDE.md codragraph block updates. */
@@ -54,12 +59,12 @@ export interface AnalyzeOptions {
      */
     skillTargets?: string;
     /**
-     * RFC 0001 Phase 2 — opt-in per-row content compression. Accepts
-     * `'none'` (default), `'brotli'` (Node ≥ 18), or `'zstd'` (Node ≥
-     * 22.15). Compressed indexes are still queryable via the standard
+     * RFC 0001 Phase 2 - per-row content compression. Accepts `'auto'`
+     * (default), `'none'`, `'brotli'` (Node >= 18), or `'zstd'`
+     * (Node >= 22.15). Compressed indexes are still queryable via the standard
      * read path; decode happens at every external-consumer boundary
      * (MCP, HTTP API, embeddings, CLI tools).
      */
-    compress?: 'none' | 'brotli' | 'zstd';
+    compress?: CompressionOption;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -17,6 +17,7 @@ import { closeCgdb } from '../core/cgdb/cgdb-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 { parseAnalyzeProfile, parseCompressionOption, parseEmbeddingMode, } from '../core/adaptive-profile.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import fs from 'fs/promises';
 import { formatBytes, LARGE_INDEX_WARNING_BYTES, summarizeIndexStorage } from './status.js';
@@ -28,10 +29,14 @@ 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}`;
+function hasNodeFlag(flagName, nodeOpts, execArgv) {
+    return (nodeOpts.includes(flagName) ||
+        execArgv.some((arg) => arg === flagName || arg.startsWith(`${flagName}=`)));
+}
 /** 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'))
+    if (hasNodeFlag('--max-old-space-size', nodeOpts, process.execArgv))
         return false;
     const v8Heap = v8.getHeapStatistics().heap_size_limit;
     if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
@@ -39,10 +44,14 @@ function ensureHeap() {
     // --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'))
+    if (!hasNodeFlag('--stack-size', nodeOpts, process.execArgv))
         cliFlags.push(STACK_FLAG);
     try {
-        execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
+        // Preserve loader/debug flags from the outer process. This is required
+        // for source-mode invocations such as `tsx src/cli/index.ts analyze`;
+        // otherwise the child runs plain node against .ts files and cannot
+        // resolve the emitted .js import specifiers.
+        execFileSync(process.execPath, [...process.execArgv, ...cliFlags, ...process.argv.slice(1)], {
             stdio: 'inherit',
             env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
         });
@@ -58,18 +67,31 @@ export const analyzeCommand = async (inputPath, options) => {
     if (options?.verbose) {
         process.env.CODRAGRAPH_VERBOSE = '1';
     }
-    // RFC 0001 Phase 2 — validate --compress before doing any work. Catching
+    try {
+        parseAnalyzeProfile(options?.profile);
+        parseEmbeddingMode(options?.embeddingMode);
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exitCode = 2;
+        return;
+    }
+    // RFC 0001 Phase 2 - validate --compress before doing any work. Catching
     // a typo or an unsupported encoding here is much friendlier than failing
     // mid-analyze with an opaque CSV-write error. Node-version gating for
     // zstd lives in @codragraph/graphstore via isEncodingSupported, but we
     // import the check here so the CLI can offer the brotli fallback hint.
-    if (options?.compress && options.compress !== 'none') {
-        if (options.compress !== 'brotli' && options.compress !== 'zstd') {
-            console.error(`  --compress must be one of: none, brotli, zstd (got: ${options.compress})`);
-            process.exitCode = 2;
-            return;
-        }
-        if (options.compress === 'zstd') {
+    const requestedCompress = options?.compress ?? 'auto';
+    try {
+        parseCompressionOption(requestedCompress);
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (requestedCompress !== 'auto' && requestedCompress !== 'none') {
+        if (requestedCompress === 'zstd') {
             const { isEncodingSupported } = await import('@codragraph/graphstore');
             if (!isEncodingSupported('zstd')) {
                 console.error('  --compress zstd requires Node ≥ 22.15.0 (native node:zlib zstd).\n' +
@@ -84,7 +106,7 @@ export const analyzeCommand = async (inputPath, options) => {
         // gracefully falls back to name-only matches instead of tokenising
         // base64 garbage. Surface the trade-off so users know what they're
         // opting into.
-        console.warn(`  Note: --compress ${options.compress} reduces .codragraph/cgdb size.\n` +
+        console.warn(`  Note: --compress ${requestedCompress} reduces .codragraph/cgdb size.\n` +
             `  BM25 search will index symbol names only (function bodies are not tokenised\n` +
             `  when compressed); embeddings, graph queries, and \`context\` / \`impact\` are\n` +
             `  unaffected. Run with --compress none if you rely on full-text search inside\n` +
@@ -241,8 +263,10 @@ export const analyzeCommand = async (inputPath, options) => {
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options?.allowDuplicateName,
             // RFC 0001 Phase 2 — pass through the per-row encoding choice.
-            // Default 'none' / undefined keeps the pre-Phase-2 wire layout.
+            // Default 'auto' lets the adaptive profile choose the storage tier.
             compress: options?.compress,
+            profile: options?.profile,
+            embeddingMode: options?.embeddingMode,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);