gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/cli/ai-context.js

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { STANDARD_SKILL_CATALOG } from './standard-skills.js';
 import { logger } from '../core/logger.js';
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -81,26 +82,27 @@ export function generateGitNexusContent(projectName, stats, opts = {}) {
     const { generatedSkills, groupNames, noStats, skipSkills, runnerPath = '.gitnexus/run.cjs', defaultBranch = 'main', hasPdg = false, } = opts;
     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\` |`)
+            .map((s) => 
+        // The per-cluster count is as volatile as the header parenthetical,
+        // so --no-stats drops it too (#2907) — otherwise the flag that
+        // promises "omit volatile symbol counts" left a churning one behind.
+        `| Work in the ${s.label} area${noStats ? '' : ` (${s.symbolCount} symbols)`} | \`.claude/skills/${s.name}/SKILL.md\` |`)
             .join('\n')
         : '';
     // Standard skill rows reference files installed by installSkills(). When
     // --skip-skills suppresses that install, these rows must be omitted — else
     // AGENTS.md/CLAUDE.md would direct agents to read files that don't exist.
-    // Community skills (generatedRows) live in .claude/skills/generated/ and
+    // Community skills (generatedRows) live directly under .claude/skills/ and
     // are independent of --skip-skills, so they remain when present.
     const standardSkillsRows = skipSkills
         ? ''
-        : `| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
-| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
-| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
-| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |`;
+        : STANDARD_SKILL_CATALOG.filter((skill) => skill.distributions.project)
+            .map((skill) => `| ${skill.agentTableTask} | \`.claude/skills/${skill.name}/SKILL.md\` |`)
+            .join('\n');
     const tableBody = [standardSkillsRows, generatedRows].filter(Boolean).join('\n');
     const skillsTable = tableBody
         ? `| Task | Read this skill file |
-|------|---------------------|
+| --- | --- |
 ${tableBody}`
         : '';
     // Docs reference the project-local runner `gitnexus analyze` writes (#1945):
@@ -109,22 +111,40 @@ ${tableBody}`
     // stay under the CLAUDE.md block token budget (#856); the cli skill carries the
     // full bootstrap + npm-11 fallback (`node.target is null` npx install crash).
     const runner = `node ${runnerPath}`;
-    const bootstrapNote = `No \`${runnerPath}\` yet? \`npx gitnexus analyze\` ` +
-        '(npm 11 crash → `npm i -g gitnexus`; #1939).';
+    // Bootstrap names every install-free one-shot rather than the one this machine
+    // resolves to: the block is committed, so a host-specific command would make
+    // two contributors on different package managers rewrite it at each other on
+    // every analyze (the per-machine churn of #1706). `bunx` is listed because a
+    // bun-only machine has no npm, npx or pnpm at all, and the npx-only note left
+    // it with a bootstrap command it could not run.
+    const bootstrapNote = `No \`${runnerPath}\` yet? Bootstrap with \`npx\`, \`bunx\`, or \`pnpm dlx\` — ` +
+        'e.g. `bunx gitnexus@latest analyze` (npm 11 npx crash; #1939).';
+    // This block is injected into every user's repo and its total size is capped
+    // by test (ai-context.test.ts, #856) — a new bullet or clause has to be paid
+    // for by trimming an existing one.
+    //
+    // The detect_changes bullet carries the degraded-result rule (#2915): a run
+    // that sets `partial` (a graph query failed) or `truncated` (the changed-symbol
+    // listing was capped) is not the pre-commit gate passing, and `partial` pairs
+    // routinely with changed_count:0 — the exact shape that printed "No changes
+    // detected." and exited 0 on a broken analysis. Same reasoning as the
+    // `risk: UNKNOWN` bullet below: the tool could not answer, so its zero is not
+    // an all-clear.
     return `${GITNEXUS_START_MARKER}
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}. Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}.
 
-> Index stale? Run \`${runner} analyze\` from the project root — it auto-selects an available runner. ${bootstrapNote}
+> Index stale? Run \`${runner} analyze --index-only\` from the project root — it auto-selects an available runner. ${bootstrapNote}
 
 ## Always Do
 
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.${hasPdg
-        ? ` For unified PDG impact, add \`mode: "pdg"\` with optional \`line: <N>\` — it returns statement-level \`affectedStatements\` over CDG + REACHING_DEF and inter-procedural symbols in \`interproceduralByDepth\`/\`byDepth\`; no-layer/degraded PDG results are UNKNOWN-risk notes (\`--pdg\` layer).`
+- **MUST run impact analysis before editing.** Use \`impact({target: "symbolName", direction: "upstream"})\` (MCP) or \`${runner} impact "symbolName" --direction upstream --repo .\` (CLI fallback); report callers, processes, and risk. Never substitute grep for graph analysis.${hasPdg
+        ? ` For unified PDG impact, add \`mode: "pdg"\` with optional \`line: <N>\` — it returns statement-level \`affectedStatements\` over CDG + REACHING_DEF and inter-procedural symbols in \`interproceduralByDepth\`/\`byDepth\`; no-layer/degraded PDG results are UNKNOWN-risk notes (\`--pdg\` layer). CLI equivalent: \`${runner} impact "symbolName" --direction upstream --mode pdg --line <N> --repo .\`.`
         : ''}
-- **MUST run \`detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
+- **MUST analyze graph changes before committing.** Use \`detect_changes({scope: "all"})\` (MCP) or \`${runner} detect-changes --scope all --repo .\` (CLI fallback). \`partial: true\` or \`truncated: true\` is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\` or \`${runner} detect-changes --scope compare --base-ref ${JSON.stringify(markdownSafeBranch(defaultBranch))} --repo .\`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- **MUST treat \`risk: UNKNOWN\` as unresolved, not as low.** An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). \`impact\` pairs \`UNKNOWN\` with a \`riskNote\` saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
 - When exploring unfamiliar code, use \`query({search_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 \`context({name: "symbolName"})\`.
 - For security review, \`explain({target: "fileOrSymbol"})\` lists taint findings (source→sink flows; needs \`analyze --pdg\`).${hasPdg
@@ -133,15 +153,15 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 
 ## Never Do
 
-- NEVER edit a function, class, or method without first running \`impact\` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER edit a function, class, or method before MCP/CLI impact analysis.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read \`UNKNOWN\` as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
 - NEVER rename symbols with find-and-replace — use \`rename\` which understands the call graph.
-- NEVER commit changes without running \`detect_changes()\` to check affected scope.
+- NEVER commit before MCP/CLI graph change analysis.
 
 ## Resources
 
 | Resource | Use for |
-|----------|---------|
+| --- | --- |
 | \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
 | \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
 | \`gitnexus://repo/${projectName}/processes\` | All execution flows |
@@ -173,16 +193,40 @@ async function fileExists(filePath) {
         return false;
     }
 }
+/**
+ * Replace the block's volatile counts — the header parenthetical and the
+ * per-cluster symbol counts in the skills table — with fixed placeholders, so
+ * two renderings that differ only in those numbers compare equal.
+ *
+ * Placeholders rather than deletions: `--no-stats` REMOVES the parenthetical,
+ * which must still be written through. Deleting instead of substituting would
+ * make a with-counts block and a without-counts block compare equal, and the
+ * flag would silently stop taking effect on an already-injected file.
+ */
+function stripVolatileCounts(section) {
+    return section
+        .replace(/ \(\d+ symbols, \d+ relationships, \d+ execution flows\)/g, ' (<counts>)')
+        .replace(/ \(\d+ symbols\)/g, ' (<count>)');
+}
 /**
  * Create or update GitNexus section in a file
  * - If file doesn't exist: create with GitNexus content
  * - If file exists without GitNexus section: append
- * - If file exists with GitNexus section: replace that section
+ * - If file exists with GitNexus section: replace that section, UNLESS the only
+ *   delta is the volatile counts (#2907). AGENTS.md and CLAUDE.md are the agent
+ *   guides teams commit, and the counts move with any code change, so a
+ *   count-only rewrite dirties a tracked file on every reindex for no reader
+ *   benefit. Live counts stay available from `gitnexus status` and
+ *   `gitnexus://repo/{name}/context`; the committed block keeps whichever
+ *   numbers it was last materially updated with.
  */
 async function upsertGitNexusSection(filePath, content, projectName, stats, noStats) {
     const exists = await fileExists(filePath);
     if (!exists) {
-        await fs.writeFile(filePath, content, 'utf-8');
+        // Same `.trim() + '\n'` shape the update paths write. Creating without the
+        // trailing newline made the NEXT analyze dirty a freshly committed file
+        // even at unchanged counts, purely to append it (#2907).
+        await fs.writeFile(filePath, content.trim() + '\n', 'utf-8');
         return 'created';
     }
     const existingContent = await fs.readFile(filePath, 'utf-8');
@@ -230,6 +274,11 @@ async function upsertGitNexusSection(filePath, content, projectName, stats, noSt
             const statsPattern = /^(?:Indexed as|indexed by GitNexus as) \*\*[^*]+\*\*(?: \([^)]+\))?/m;
             if (statsPattern.test(existingSection)) {
                 const updatedSection = existingSection.replace(statsPattern, statsLine);
+                // Count-only delta — leave the committed lean block alone (#2907). A
+                // project rename, or --no-stats dropping the parenthetical, still writes.
+                if (stripVolatileCounts(updatedSection) === stripVolatileCounts(existingSection)) {
+                    return 'preserved';
+                }
                 const before = existingContent.substring(0, startIdx);
                 const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);
                 await fs.writeFile(filePath, (before + updatedSection + after).trim() + '\n', 'utf-8');
@@ -240,7 +289,11 @@ async function upsertGitNexusSection(filePath, content, projectName, stats, noSt
             // don't mis-report this as 'updated' (which would imply a write).
             return 'preserved';
         }
-        // No keep marker — replace existing section with full verbose content
+        // No keep marker — replace existing section with full verbose content,
+        // unless the counts are the only thing that moved (#2907).
+        if (stripVolatileCounts(existingSection) === stripVolatileCounts(content)) {
+            return 'preserved';
+        }
         const before = existingContent.substring(0, startIdx);
         const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);
         const newContent = before + content + after;
@@ -253,40 +306,31 @@ async function upsertGitNexusSection(filePath, content, projectName, stats, noSt
     return 'appended';
 }
 /**
- * Install GitNexus skills to .claude/skills/gitnexus/
- * Works natively with Claude Code, Cursor, and GitHub Copilot
+ * Some agents read skills from a repo-local `.agents/skills/` directory and
+ * prefer it over the global `~/.agents/skills/` install. When the repo contains
+ * an `.agents/` directory, skills written to `.claude/skills/` are mirrored
+ * there too so those agents serve the up-to-date copies.
+ */
+export async function shouldMirrorSkillsToAgents(repoPath) {
+    try {
+        const stat = await fs.stat(path.join(repoPath, '.agents'));
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install GitNexus skills as direct children of .claude/skills/
+ * Works natively with Claude Code, Cursor, and GitHub Copilot.
+ * Mirrored to .agents/skills/ when .agents/ exists.
  */
 async function installSkills(repoPath) {
-    const skillsDir = path.join(repoPath, '.claude', 'skills', 'gitnexus');
+    const skillsDir = path.join(repoPath, '.claude', 'skills');
+    const legacySkillsDir = path.join(skillsDir, 'gitnexus');
     const installedSkills = [];
-    // Skill definitions bundled with the package
-    const skills = [
-        {
-            name: 'gitnexus-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: 'gitnexus-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: 'gitnexus-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: 'gitnexus-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: 'gitnexus-guide',
-            description: 'Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?"',
-        },
-        {
-            name: 'gitnexus-cli',
-            description: 'Use when the user needs to run GitNexus 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 agentsMirror = await shouldMirrorSkillsToAgents(repoPath);
+    for (const skill of STANDARD_SKILL_CATALOG.filter((entry) => entry.distributions.project && entry.distributions.npm)) {
         const skillDir = path.join(skillsDir, skill.name);
         const skillPath = path.join(skillDir, 'SKILL.md');
         try {
@@ -302,25 +346,45 @@ async function installSkills(repoPath) {
                 // Fallback: generate minimal skill content
                 skillContent = `---
 name: ${skill.name}
-description: ${skill.description}
+description: ${skill.fallbackDescription}
 ---
 
 # ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
 
-${skill.description}
+${skill.fallbackDescription}
 
 Use GitNexus tools to accomplish this task.
 `;
             }
             await fs.writeFile(skillPath, skillContent, 'utf-8');
+            // Mirror to .agents/skills/ for agents that read repo-local skills
+            if (agentsMirror) {
+                try {
+                    const agentsSkillDir = path.join(repoPath, '.agents', 'skills', skill.name);
+                    await fs.mkdir(agentsSkillDir, { recursive: true });
+                    await fs.writeFile(path.join(agentsSkillDir, 'SKILL.md'), skillContent, 'utf-8');
+                }
+                catch (err) {
+                    logger.warn({ err }, `Warning: Could not mirror skill ${skill.name} to .agents/skills:`);
+                }
+            }
             installedSkills.push(skill.name);
+            // Previous releases installed these known standard skills one level too
+            // deep. Remove only the child owned by this installer; unknown siblings
+            // under the legacy grouping directory may be user-authored and survive.
+            try {
+                await fs.rm(path.join(legacySkillsDir, skill.name), { recursive: true, force: true });
+            }
+            catch (err) {
+                logger.warn({ err }, `Warning: Could not remove legacy skill ${skill.name}:`);
+            }
         }
         catch (err) {
             // Skip on error, don't fail the whole process
             logger.warn({ err }, `Warning: Could not install skill ${skill.name}:`);
         }
     }
-    return installedSkills;
+    return { skills: installedSkills, agentsMirror };
 }
 /**
  * Generate AI context files after indexing
@@ -366,15 +430,18 @@ 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)');
     }
-    // Install skills to .claude/skills/gitnexus/ (unless --skip-skills)
+    // Install standard skills directly under .claude/skills/ (unless --skip-skills)
     if (!options?.skipSkills) {
-        const installedSkills = await installSkills(repoPath);
+        const { skills: installedSkills, agentsMirror } = await installSkills(repoPath);
         if (installedSkills.length > 0) {
-            createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
+            createdFiles.push(`.claude/skills/gitnexus-*/ (${installedSkills.length} skills)`);
+            if (agentsMirror) {
+                createdFiles.push(`.agents/skills/gitnexus-*/ (${installedSkills.length} skills mirrored for .agents)`);
+            }
         }
     }
     else {
-        createdFiles.push('.claude/skills/gitnexus/ (skipped via --skip-skills)');
+        createdFiles.push('.claude/skills/gitnexus-*/ (skipped via --skip-skills)');
     }
     return { files: createdFiles };
 }

package/dist/cli/analyze-config.d.ts

@@ -27,7 +27,7 @@
  * documented precedence). Conflicting *aliases at the same level* (e.g. both
  * `defaultBranch` and `branch`) are rejected.
  */
-import type { AnalyzeOptions } from './analyze.js';
+import type { AnalyzeOptions } from './analyze-options.js';
 export declare const GITNEXUS_RC_FILENAME = ".gitnexusrc";
 /** Final fallback when no branch is configured or detectable. */
 export declare const DEFAULT_BRANCH_FALLBACK = "main";

package/dist/cli/analyze-options.d.ts

@@ -0,0 +1,131 @@
+/**
+ * CLI-facing `analyze` option shape.
+ *
+ * This is the *flag* shape: it mirrors what Commander parses off the command
+ * line and what `.gitnexusrc` may set, before `analyze` translates it into the
+ * core orchestrator's own `AnalyzeOptions` (`core/run-analyze.ts`) — a
+ * different, deliberately separate interface (`stats` here vs `noStats`
+ * there, `embeddings?: boolean | string` here vs a resolved
+ * `embeddingsNodeLimit` there).
+ *
+ * It lives in this leaf module because both `analyze.ts` (which consumes the
+ * flags) and `analyze-config.ts` (which maps `.gitnexusrc` keys onto them)
+ * need it, and `analyze.ts` already imports the config loader — a type import
+ * back the other way put the two files, plus `core/run-analyze.ts`, in an
+ * import cycle. `analyze.ts` re-exports the type for existing importers.
+ */
+export interface AnalyzeOptions {
+    force?: boolean;
+    repairFts?: boolean;
+    /**
+     * Embedding generation toggle. Commander parses `--embeddings [limit]` as:
+     *   - `undefined` when the flag is omitted
+     *   - `true` when passed without an argument (use default 50K node cap)
+     *   - a string when passed with an argument (`--embeddings 0` disables the
+     *     cap, `--embeddings <n>` uses `<n>` as the cap)
+     */
+    embeddings?: boolean | string;
+    /**
+     * Explicitly drop existing embeddings on rebuild instead of preserving
+     * them. Without this flag, a routine `analyze` keeps any embeddings
+     * already present in the index even when `--embeddings` is omitted.
+     */
+    dropEmbeddings?: boolean;
+    skills?: boolean;
+    verbose?: boolean;
+    /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
+    skipAgentsMd?: boolean;
+    /**
+     * Build the control-flow-graph / PDG substrate (#2081 M1). Opt-in; off by
+     * default. Threaded to both the worker (CFG build) and scope-resolution
+     * (BasicBlock/CFG emit).
+     */
+    pdg?: boolean;
+    /**
+     * Stats inclusion in AGENTS.md and CLAUDE.md.
+     *
+     * Commander.js represents `--no-stats` as `stats: boolean` (default
+     * `true`; `false` when the user passes `--no-stats`), NOT as
+     * `noStats: boolean`. Reading the negated form would always be
+     * `undefined` and the flag would silently no-op (#1477). Consumers
+     * that want "did the user request --no-stats?" should compare with
+     * `=== false` to distinguish the explicit-off case from the
+     * default-on case.
+     */
+    stats?: boolean;
+    /**
+     * Opt-in auto-commit of any AGENTS.md/CLAUDE.md changes this `analyze` run
+     * makes. Scoped to only those two files (never `git add -A`); no-ops
+     * silently if neither exists, neither changed, or the commit step itself
+     * fails (e.g. no git identity configured). See #2639.
+     */
+    selfCommit?: boolean;
+    /** Skip installing standard GitNexus skill files directly under .claude/skills/. */
+    skipSkills?: boolean;
+    /**
+     * Default branch for the generated regression-compare example (#243). From
+     * `--default-branch`; may also be supplied via `.gitnexusrc`. Resolved to a
+     * concrete branch (CLI > `.gitnexusrc` > auto-detected origin/HEAD > "main")
+     * before being threaded into the generated AGENTS.md / CLAUDE.md content.
+     */
+    defaultBranch?: string;
+    /**
+     * Index-branch selector (#2106). From `--branch`. Distinct from
+     * `defaultBranch` (cosmetic base_ref): this routes the index to a per-branch
+     * slot. NOT sourced from `.gitnexusrc` — the `.gitnexusrc` `branch` key is an
+     * alias for `defaultBranch` and must not change index placement. Defaults to
+     * the checked-out branch inside `runFullAnalysis` when omitted.
+     */
+    branch?: string;
+    /** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
+    indexOnly?: 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
+     * `GITNEXUS_MAX_FILE_SIZE` for the rest of the pipeline.
+     */
+    maxFileSize?: string;
+    /** Override worker sub-batch idle timeout in seconds. */
+    workerTimeout?: string;
+    /** Control LadybugDB WAL auto-checkpoint threshold during analyze. */
+    walCheckpointThreshold?: string;
+    /** Parse worker pool size (>=1); 0 is rejected (no sequential mode). */
+    workers?: string;
+    embeddingThreads?: string;
+    embeddingBatchSize?: string;
+    embeddingSubBatchSize?: string;
+    embeddingDevice?: string;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers (#1589/#1852
+     * residual). Supplied via `.gitnexusrc` `fetchWrappers: [...]`. Threaded into
+     * the routes phase, where the cross-file consumer scan unions them with the
+     * auto-detected `fetch()` wrappers so a custom/axios-based wrapper named
+     * outside the built-in convention still produces `route_map` consumers.
+     */
+    fetchWrappers?: string[];
+    /** OpenAI-compatible embeddings base URL (incl. /v1). Overrides GITNEXUS_EMBEDDING_URL. */
+    embeddingBaseUrl?: string;
+    /** Embedding model name. Overrides GITNEXUS_EMBEDDING_MODEL. */
+    embeddingModel?: string;
+    /** Bearer token for the embeddings endpoint. Overrides GITNEXUS_EMBEDDING_API_KEY. Never logged. */
+    embeddingAuthToken?: string;
+    /** Embedding vector dimensions (positive integer string). Overrides GITNEXUS_EMBEDDING_DIMS. */
+    embeddingDims?: string;
+}

package/dist/cli/analyze-options.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/analyze.d.ts

@@ -7,123 +7,32 @@
  * This CLI wrapper handles: heap management, progress bar, SIGINT,
  * skill generation (--skills), summary output, and process.exit().
  */
+import { type AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
+import type { AnalyzeOptions } from './analyze-options.js';
 /**
- * RAM-aware re-exec heap cap (MB): `0.75 × effective RAM`, clamped to
- * `>= DEFAULT_HEAP_MB`. Kept BELOW physical RAM on purpose — a cap `>=` RAM makes
- * V8 collect lazily and inflate the heap into swap-thrash (observed analyzing the
- * Linux kernel at a 30GB cap on a 31GB box). `constrainedBytes` is the cgroup
- * limit or `null`; it is honored only as a real, smaller-than-physical cap, because
+ * RAM-aware re-exec heap cap (MB) — the formula itself is single-sourced in
+ * `core/ingestion/utils/effective-ram.ts` (`heapCapMbFor`), shared with the
+ * server's analyze fork. `constrainedBytes` is the cgroup limit or `null`;
+ * it is honored only as a real, smaller-than-physical cap, because
  * `process.constrainedMemory()` returns a huge sentinel when UNCONSTRAINED.
+ * (Observed rationale: a cap ≥ RAM made V8 collect lazily and swap-thrash —
+ * the #2649 worker-timeout cascade on 16 GB boxes.)
  */
 export declare function computeHeapCapMb(totalBytes: number, constrainedBytes: number | null): number;
-export interface AnalyzeOptions {
-    force?: boolean;
-    repairFts?: boolean;
-    /**
-     * Embedding generation toggle. Commander parses `--embeddings [limit]` as:
-     *   - `undefined` when the flag is omitted
-     *   - `true` when passed without an argument (use default 50K node cap)
-     *   - a string when passed with an argument (`--embeddings 0` disables the
-     *     cap, `--embeddings <n>` uses `<n>` as the cap)
-     */
-    embeddings?: boolean | string;
-    /**
-     * Explicitly drop existing embeddings on rebuild instead of preserving
-     * them. Without this flag, a routine `analyze` keeps any embeddings
-     * already present in the index even when `--embeddings` is omitted.
-     */
-    dropEmbeddings?: boolean;
-    skills?: boolean;
-    verbose?: boolean;
-    /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
-    skipAgentsMd?: boolean;
-    /**
-     * Build the control-flow-graph / PDG substrate (#2081 M1). Opt-in; off by
-     * default. Threaded to both the worker (CFG build) and scope-resolution
-     * (BasicBlock/CFG emit).
-     */
-    pdg?: boolean;
-    /**
-     * Stats inclusion in AGENTS.md and CLAUDE.md.
-     *
-     * Commander.js represents `--no-stats` as `stats: boolean` (default
-     * `true`; `false` when the user passes `--no-stats`), NOT as
-     * `noStats: boolean`. Reading the negated form would always be
-     * `undefined` and the flag would silently no-op (#1477). Consumers
-     * that want "did the user request --no-stats?" should compare with
-     * `=== false` to distinguish the explicit-off case from the
-     * default-on case.
-     */
-    stats?: boolean;
-    /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
-    skipSkills?: boolean;
-    /**
-     * Default branch for the generated regression-compare example (#243). From
-     * `--default-branch`; may also be supplied via `.gitnexusrc`. Resolved to a
-     * concrete branch (CLI > `.gitnexusrc` > auto-detected origin/HEAD > "main")
-     * before being threaded into the generated AGENTS.md / CLAUDE.md content.
-     */
-    defaultBranch?: string;
-    /**
-     * Index-branch selector (#2106). From `--branch`. Distinct from
-     * `defaultBranch` (cosmetic base_ref): this routes the index to a per-branch
-     * slot. NOT sourced from `.gitnexusrc` — the `.gitnexusrc` `branch` key is an
-     * alias for `defaultBranch` and must not change index placement. Defaults to
-     * the checked-out branch inside `runFullAnalysis` when omitted.
-     */
-    branch?: string;
-    /** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
-    indexOnly?: 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
-     * `GITNEXUS_MAX_FILE_SIZE` for the rest of the pipeline.
-     */
-    maxFileSize?: string;
-    /** Override worker sub-batch idle timeout in seconds. */
-    workerTimeout?: string;
-    /** Control LadybugDB WAL auto-checkpoint threshold during analyze. */
-    walCheckpointThreshold?: string;
-    /** Parse worker pool size (>=1); 0 is rejected (no sequential mode). */
-    workers?: string;
-    embeddingThreads?: string;
-    embeddingBatchSize?: string;
-    embeddingSubBatchSize?: string;
-    embeddingDevice?: string;
-    /**
-     * Extra fetch-wrapper function names to treat as HTTP consumers (#1589/#1852
-     * residual). Supplied via `.gitnexusrc` `fetchWrappers: [...]`. Threaded into
-     * the routes phase, where the cross-file consumer scan unions them with the
-     * auto-detected `fetch()` wrappers so a custom/axios-based wrapper named
-     * outside the built-in convention still produces `route_map` consumers.
-     */
-    fetchWrappers?: string[];
-    /** OpenAI-compatible embeddings base URL (incl. /v1). Overrides GITNEXUS_EMBEDDING_URL. */
-    embeddingBaseUrl?: string;
-    /** Embedding model name. Overrides GITNEXUS_EMBEDDING_MODEL. */
-    embeddingModel?: string;
-    /** Bearer token for the embeddings endpoint. Overrides GITNEXUS_EMBEDDING_API_KEY. Never logged. */
-    embeddingAuthToken?: string;
-    /** Embedding vector dimensions (positive integer string). Overrides GITNEXUS_EMBEDDING_DIMS. */
-    embeddingDims?: string;
-}
+/**
+ * Last `--max-old-space-size` value (MB) in a NODE_OPTIONS string, or `null`
+ * when absent/unparseable. Last occurrence wins, matching V8's own
+ * later-flag-wins semantics when NODE_OPTIONS repeats a flag.
+ */
+export declare function parseMaxOldSpaceMb(nodeOptions: string): number | null;
+/**
+ * CLI `analyze` flag shape. Defined in `./analyze-options.js` so
+ * `analyze-config.ts` can reference it without importing this module back —
+ * that type import closed a cycle over `analyze` → `analyze-config` and
+ * `analyze` → `run-analyze` → `analyze-config`. Re-exported here because this
+ * is where callers have always imported it from.
+ */
+export type { AnalyzeOptions };
 /**
  * Whether the post-index skill step should run.
  *
@@ -138,4 +47,6 @@ export interface AnalyzeOptions {
  * without booting the full analyze pipeline (#742 review).
  */
 export declare const shouldGenerateCommunitySkillFiles: (options: Pick<AnalyzeOptions, "skills" | "indexOnly"> | undefined, pipelineResult: unknown) => boolean;
-export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions, runnerIdentityAtBootstrap?: AnalyzerRunnerIdentity) => Promise<void>;
+/** Commander entrypoint used only by the capture-before-import lazy bootstrap. */
+export declare const analyzeCommandWithRunnerIdentity: (runnerIdentityAtBootstrap: AnalyzerRunnerIdentity, inputPath?: string, options?: AnalyzeOptions) => Promise<void>;