gitnexus 1.6.6-rc.130 → 1.6.6-rc.131

package/dist/cli/ai-context.d.ts

@@ -18,12 +18,45 @@ export interface AIContextOptions {
     skipAgentsMd?: boolean;
     noStats?: boolean;
     skipSkills?: boolean;
+    /**
+     * Default branch used by the generated regression-compare example (#243).
+     * Resolved by the CLI (CLI flag > `.gitnexusrc` > auto-detect > "main"); a
+     * plain caller that omits it gets "main", preserving prior behavior.
+     */
+    defaultBranch?: string;
 }
-export declare function generateGitNexusContent(projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[], groupNames?: string[], noStats?: boolean, skipSkills?: boolean, runnerPath?: string): string;
+/**
+ * Strip backticks from a branch name before it is embedded in a Markdown
+ * inline-code span (#1996 tri-review P1). validateBranchName already rejects
+ * backticks for CLI/config/auto-detect inputs; this is the last-line defense at
+ * the generation sink so the embedding is provably safe regardless of caller.
+ */
+export declare function markdownSafeBranch(branch: string): string;
+export declare function generateGitNexusContent(projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[], groupNames?: string[], noStats?: boolean, skipSkills?: boolean, runnerPath?: string, defaultBranch?: string): string;
 /**
  * Generate AI context files after indexing
  */
 export declare function generateAIContextFiles(repoPath: string, storagePath: string, projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[], options?: AIContextOptions): Promise<{
     files: string[];
 }>;
+/**
+ * Refresh only the `base_ref: "..."` value inside the GitNexus block of an
+ * already-generated AGENTS.md / CLAUDE.md, in place (#1996 tri-review P2).
+ *
+ * The `alreadyUpToDate` analyze fast path returns before the normal
+ * {@link generateAIContextFiles} call, so a changed `.gitnexusrc` defaultBranch
+ * (or `--default-branch`) would otherwise not take effect until the next
+ * re-index. This does a surgical line update that preserves the rest of the
+ * block — including community-skill rows written by a prior `--skills` run —
+ * rather than regenerating (which would drop those rows on a no-`--skills` run).
+ *
+ * Best-effort: missing files, a missing/blank block, or a block with no
+ * `base_ref` line (e.g. a user-trimmed keep block) are silently skipped. Writes
+ * only when the value actually changes, so a routine up-to-date run is a no-op.
+ */
+export declare function refreshBaseRefLine(repoPath: string, defaultBranch: string, options?: {
+    skipAgentsMd?: boolean;
+}): Promise<{
+    files: string[];
+}>;
 export {};

package/dist/cli/ai-context.js

@@ -68,11 +68,28 @@ async function findGroupsContainingRegistryName(registryName) {
     }
     return hits;
 }
+/**
+ * Strip backticks from a branch name before it is embedded in a Markdown
+ * inline-code span (#1996 tri-review P1). validateBranchName already rejects
+ * backticks for CLI/config/auto-detect inputs; this is the last-line defense at
+ * the generation sink so the embedding is provably safe regardless of caller.
+ */
+export function markdownSafeBranch(branch) {
+    return branch.replace(/`/g, '');
+}
 export function generateGitNexusContent(projectName, stats, generatedSkills, groupNames, noStats, skipSkills, 
 // Project-relative path to the runner `gitnexus analyze` drops next to the
 // index (#1945). Referenced by docs so a single CLI-neutral command resolves
 // the available runner (global `gitnexus` → `pnpm dlx` → `npx`) at call time.
-runnerPath = '.gitnexus/run.cjs') {
+runnerPath = '.gitnexus/run.cjs', 
+// Default branch for the regression-compare example (#243). Configurable so
+// projects on `develop`/`master`/etc. don't get `base_ref: "main"` rewritten
+// back over their fix on every analyze. The value is embedded inside a
+// Markdown inline-code span: validateBranchName rejects backticks upstream,
+// and `markdownSafeBranch` strips any remaining backtick here as defense in
+// depth, so JSON.stringify's quote/escape handling is sufficient and the
+// branch cannot break out of the span (#1996 tri-review P1).
+defaultBranch = 'main') {
     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\` |`)
@@ -115,7 +132,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 ## Always Do
 
 - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`gitnexus_detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
 - When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
@@ -331,7 +348,7 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
     catch (err) {
         logger.warn(`Could not write GitNexus runner to ${runnerPath}: ${String(err)}`);
     }
-    const content = generateGitNexusContent(projectName, stats, generatedSkills, groupNames, options?.noStats, options?.skipSkills, runnerPath);
+    const content = generateGitNexusContent(projectName, stats, generatedSkills, groupNames, options?.noStats, options?.skipSkills, runnerPath, options?.defaultBranch ?? 'main');
     const createdFiles = [];
     if (!options?.skipAgentsMd) {
         // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
@@ -359,3 +376,58 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
     }
     return { files: createdFiles };
 }
+/**
+ * Refresh only the `base_ref: "..."` value inside the GitNexus block of an
+ * already-generated AGENTS.md / CLAUDE.md, in place (#1996 tri-review P2).
+ *
+ * The `alreadyUpToDate` analyze fast path returns before the normal
+ * {@link generateAIContextFiles} call, so a changed `.gitnexusrc` defaultBranch
+ * (or `--default-branch`) would otherwise not take effect until the next
+ * re-index. This does a surgical line update that preserves the rest of the
+ * block — including community-skill rows written by a prior `--skills` run —
+ * rather than regenerating (which would drop those rows on a no-`--skills` run).
+ *
+ * Best-effort: missing files, a missing/blank block, or a block with no
+ * `base_ref` line (e.g. a user-trimmed keep block) are silently skipped. Writes
+ * only when the value actually changes, so a routine up-to-date run is a no-op.
+ */
+export async function refreshBaseRefLine(repoPath, defaultBranch, options) {
+    if (options?.skipAgentsMd)
+        return { files: [] };
+    const replacement = `base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}`;
+    const updated = [];
+    for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+        const filePath = path.join(repoPath, name);
+        if (!(await fileExists(filePath)))
+            continue;
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const startIdx = findSectionMarkerIndex(content, GITNEXUS_START_MARKER);
+        if (startIdx === -1)
+            continue;
+        const endIdx = findSectionMarkerIndex(content, GITNEXUS_END_MARKER, startIdx);
+        if (endIdx === -1 || endIdx <= startIdx)
+            continue;
+        const blockEnd = endIdx + GITNEXUS_END_MARKER.length;
+        const block = content.substring(startIdx, blockEnd);
+        // Only the generated regression example carries a base_ref line, and only
+        // one per block; replace its quoted value while leaving the rest untouched.
+        const newBlock = block.replace(/base_ref: "(?:[^"\\]|\\.)*"/, replacement);
+        if (newBlock === block)
+            continue; // no base_ref line present, or already current
+        const newContent = content.substring(0, startIdx) + newBlock + content.substring(blockEnd);
+        try {
+            await fs.writeFile(filePath, newContent, 'utf-8');
+            updated.push(name);
+        }
+        catch {
+            // best-effort — never fail analyze over a context refresh
+        }
+    }
+    return { files: updated };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Project-local `.gitnexusrc` support for `gitnexus analyze` (#243).
+ *
+ * Lets a repository commit recurring `analyze` defaults — default branch for the
+ * generated regression example, AI-context / skills opt-outs, embedding knobs —
+ * so contributors don't re-pass the same flags on every run. Design rules:
+ *
+ *   - Config is repo-local (`.gitnexusrc` at the resolved repo root). It is NOT
+ *     read from `.gitnexus/` because that directory is index storage and is
+ *     commonly gitignored.
+ *   - JSON only. No YAML, no `package.json` field, no global `~/.gitnexus` file
+ *     in this pass.
+ *   - CLI flags always override config (see {@link mergeAnalyzeOptions}).
+ *   - Fail closed: unknown keys, wrong value types, conflicting aliases, and
+ *     invalid JSON all throw {@link GitNexusRcError} so a typo never silently
+ *     no-ops. Errors are actionable and surface before any expensive analysis.
+ *   - Config values never reach a shell. Strings are validated against control
+ *     and hidden/bidirectional characters so they cannot inject markdown,
+ *     JSON, or hidden controls into generated context files.
+ *
+ * Both a flat shape and a nested `analyze` block are accepted:
+ *
+ *     { "defaultBranch": "develop", "skipContextFiles": true }
+ *     { "analyze": { "defaultBranch": "develop", "skipSkills": true } }
+ *
+ * When both set the same option, the nested `analyze` block wins (deterministic,
+ * documented precedence). Conflicting *aliases at the same level* (e.g. both
+ * `defaultBranch` and `branch`) are rejected.
+ */
+import type { AnalyzeOptions } from './analyze.js';
+export declare const GITNEXUS_RC_FILENAME = ".gitnexusrc";
+/** Final fallback when no branch is configured or detectable. */
+export declare const DEFAULT_BRANCH_FALLBACK = "main";
+/**
+ * Thrown for any `.gitnexusrc` problem (missing-file is NOT an error — it
+ * returns `undefined`). The message is user-facing and names the file so the
+ * CLI can print it verbatim before starting the progress bar.
+ */
+export declare class GitNexusRcError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
+ * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
+ * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export declare function validateBranchName(value: string, source: string): string;
+/**
+ * Best-effort validation for an auto-detected branch (from git). Never throws —
+ * returns `undefined` for anything unusable so the resolver falls back to the
+ * next precedence tier.
+ */
+export declare function sanitizeDetectedBranch(value: string | null | undefined): string | undefined;
+/**
+ * Locate, read, parse, validate, and normalize `.gitnexusrc` at `repoRoot`.
+ *
+ * @returns the normalized config defaults, or `undefined` when no file exists
+ *          (the normal case). Throws {@link GitNexusRcError} on any problem.
+ */
+export declare function loadAnalyzeConfig(repoRoot: string): Partial<AnalyzeOptions> | undefined;
+/**
+ * Merge CLI options over `.gitnexusrc` defaults. CLI wins whenever it provides a
+ * value — including an explicit `false` (so an explicit CLI off-switch beats a
+ * config `true`). Config fills only the genuinely-unset (`undefined`) options.
+ *
+ * `stats` is special: Commander always materializes it (`true` by default,
+ * `false` only when `--no-stats` is passed), so plain `??` can't tell "default
+ * on" from "explicitly on". The rule is: a passed `--no-stats` (`stats: false`)
+ * always wins; otherwise the config value applies. There is intentionally no
+ * `--stats` counter-flag, so config can only turn stats off, not force it back
+ * on against a `--no-stats`.
+ *
+ * `defaultBranch` is NOT resolved here — see {@link resolveDefaultBranch}, which
+ * applies the CLI > config > auto-detect > "main" precedence chain.
+ */
+export declare function mergeAnalyzeOptions(cli: AnalyzeOptions, config: Partial<AnalyzeOptions> | undefined): AnalyzeOptions;
+/**
+ * Resolve the default branch threaded into generated context, applying the
+ * precedence chain:
+ *
+ *   CLI `--default-branch` > `.gitnexusrc` `defaultBranch`/`branch`
+ *     > auto-detected `origin/HEAD` > {@link DEFAULT_BRANCH_FALLBACK} ("main").
+ *
+ * User-supplied values (CLI, config) are validated strictly and throw on bad
+ * input. The auto-detected value is best-effort and silently ignored if
+ * unusable.
+ */
+export declare function resolveDefaultBranch(input: {
+    cliBranch?: string;
+    configBranch?: string;
+    detectedBranch?: string | null;
+}): string;

package/dist/cli/analyze-config.js

@@ -0,0 +1,364 @@
+/**
+ * Project-local `.gitnexusrc` support for `gitnexus analyze` (#243).
+ *
+ * Lets a repository commit recurring `analyze` defaults — default branch for the
+ * generated regression example, AI-context / skills opt-outs, embedding knobs —
+ * so contributors don't re-pass the same flags on every run. Design rules:
+ *
+ *   - Config is repo-local (`.gitnexusrc` at the resolved repo root). It is NOT
+ *     read from `.gitnexus/` because that directory is index storage and is
+ *     commonly gitignored.
+ *   - JSON only. No YAML, no `package.json` field, no global `~/.gitnexus` file
+ *     in this pass.
+ *   - CLI flags always override config (see {@link mergeAnalyzeOptions}).
+ *   - Fail closed: unknown keys, wrong value types, conflicting aliases, and
+ *     invalid JSON all throw {@link GitNexusRcError} so a typo never silently
+ *     no-ops. Errors are actionable and surface before any expensive analysis.
+ *   - Config values never reach a shell. Strings are validated against control
+ *     and hidden/bidirectional characters so they cannot inject markdown,
+ *     JSON, or hidden controls into generated context files.
+ *
+ * Both a flat shape and a nested `analyze` block are accepted:
+ *
+ *     { "defaultBranch": "develop", "skipContextFiles": true }
+ *     { "analyze": { "defaultBranch": "develop", "skipSkills": true } }
+ *
+ * When both set the same option, the nested `analyze` block wins (deterministic,
+ * documented precedence). Conflicting *aliases at the same level* (e.g. both
+ * `defaultBranch` and `branch`) are rejected.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export const GITNEXUS_RC_FILENAME = '.gitnexusrc';
+/** Final fallback when no branch is configured or detectable. */
+export const DEFAULT_BRANCH_FALLBACK = 'main';
+/** Git refs longer than this are almost certainly a mistake / injection attempt. */
+const BRANCH_MAX_LENGTH = 255;
+/**
+ * Thrown for any `.gitnexusrc` problem (missing-file is NOT an error — it
+ * returns `undefined`). The message is user-facing and names the file so the
+ * CLI can print it verbatim before starting the progress bar.
+ */
+export class GitNexusRcError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitNexusRcError';
+    }
+}
+/**
+ * Allowed `.gitnexusrc` keys and how each maps onto `AnalyzeOptions`.
+ *
+ * Aliases intentionally collapse onto a shared target:
+ *   - `branch` is the legacy alias for `defaultBranch` (issue-comment shape).
+ *   - `skipContextFiles` / `skipAiContext` are aliases for `skipAgentsMd` — they
+ *     suppress the AGENTS.md / CLAUDE.md block ONLY. They do not imply
+ *     `skipSkills`, and they are weaker than `indexOnly` (which skips all
+ *     file injection). This matches the existing CLI semantics exactly.
+ *   - `noStats` is the negation of `stats`.
+ */
+const KEY_SPECS = {
+    defaultBranch: { target: 'defaultBranch', kind: 'branch' },
+    branch: { target: 'defaultBranch', kind: 'branch' },
+    skipAgentsMd: { target: 'skipAgentsMd', kind: 'boolean' },
+    skipContextFiles: { target: 'skipAgentsMd', kind: 'boolean' },
+    skipAiContext: { target: 'skipAgentsMd', kind: 'boolean' },
+    skipSkills: { target: 'skipSkills', kind: 'boolean' },
+    indexOnly: { target: 'indexOnly', kind: 'boolean' },
+    stats: { target: 'stats', kind: 'boolean' },
+    noStats: { target: 'stats', kind: 'boolean-negate' },
+    embeddings: { target: 'embeddings', kind: 'embeddings' },
+    dropEmbeddings: { target: 'dropEmbeddings', kind: 'boolean' },
+    name: { target: 'name', kind: 'string' },
+    allowDuplicateName: { target: 'allowDuplicateName', kind: 'boolean' },
+    maxFileSize: { target: 'maxFileSize', kind: 'numeric-string' },
+    workerTimeout: { target: 'workerTimeout', kind: 'numeric-string' },
+    walCheckpointThreshold: { target: 'walCheckpointThreshold', kind: 'numeric-string' },
+    workers: { target: 'workers', kind: 'numeric-string' },
+    embeddingThreads: { target: 'embeddingThreads', kind: 'numeric-string' },
+    embeddingBatchSize: { target: 'embeddingBatchSize', kind: 'numeric-string' },
+    embeddingSubBatchSize: { target: 'embeddingSubBatchSize', kind: 'numeric-string' },
+    embeddingDevice: { target: 'embeddingDevice', kind: 'string' },
+};
+/** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
+const NESTED_KEY = 'analyze';
+const ALLOWED_KEYS_HINT = `Allowed keys: ${Object.keys(KEY_SPECS).join(', ')} (or a nested "${NESTED_KEY}" object).`;
+/**
+ * Reject control characters and hidden / bidirectional Unicode in a string
+ * value. These have no legitimate place in a branch name, registry name, or
+ * device string, and would otherwise let a committed config smuggle invisible
+ * controls into generated AGENTS.md / CLAUDE.md content.
+ */
+const isHiddenOrControl = (codePoint) => codePoint < 0x20 ||
+    codePoint === 0x7f ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) || // zero-width + LRM/RLM
+    (codePoint >= 0x202a && codePoint <= 0x202e) || // bidi embeddings/overrides
+    (codePoint >= 0x2060 && codePoint <= 0x2064) || // word-joiner + invisible math
+    (codePoint >= 0x2066 && codePoint <= 0x206f) || // bidi isolates + deprecated
+    codePoint === 0xfeff; // BOM / zero-width no-break space
+const assertNoHiddenChars = (value, source) => {
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && isHiddenOrControl(cp)) {
+            throw new GitNexusRcError(`${source}: value contains control or hidden/bidirectional characters, which are not allowed.`);
+        }
+    }
+};
+/**
+ * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
+ * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
+ * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+export function validateBranchName(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new GitNexusRcError(`${source}: branch name must not be empty.`);
+    }
+    if (trimmed.length > BRANCH_MAX_LENGTH) {
+        throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
+    }
+    assertNoHiddenChars(trimmed, source);
+    if (/\s/.test(trimmed)) {
+        throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
+    }
+    // git ref-name rules (subset): reject characters git itself forbids in refs.
+    if (/[~^:?*[\\]/.test(trimmed)) {
+        throw new GitNexusRcError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
+    }
+    if (trimmed.startsWith('-')) {
+        throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
+    }
+    if (trimmed.includes('..')) {
+        throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
+    }
+    // Git permits a backtick in a ref, but the branch is embedded inside a
+    // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
+    // example, where a backtick would close the span early and let the rest of
+    // the template render as instruction text. Reject it at this single
+    // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
+    // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
+    if (trimmed.includes('`')) {
+        throw new GitNexusRcError(`${source}: branch name must not contain a backtick (it would break the generated Markdown).`);
+    }
+    return trimmed;
+}
+/**
+ * Best-effort validation for an auto-detected branch (from git). Never throws —
+ * returns `undefined` for anything unusable so the resolver falls back to the
+ * next precedence tier.
+ */
+export function sanitizeDetectedBranch(value) {
+    if (!value)
+        return undefined;
+    try {
+        return validateBranchName(value, 'detected branch');
+    }
+    catch {
+        return undefined;
+    }
+}
+const normalizeValue = (kind, value, key) => {
+    const source = `${GITNEXUS_RC_FILENAME} "${key}"`;
+    switch (kind) {
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
+            }
+            return value;
+        case 'boolean-negate':
+            if (typeof value !== 'boolean') {
+                throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
+            }
+            return !value;
+        case 'branch':
+            if (typeof value !== 'string') {
+                throw new GitNexusRcError(`${source} must be a string branch name.`);
+            }
+            return validateBranchName(value, source);
+        case 'string': {
+            if (typeof value !== 'string') {
+                throw new GitNexusRcError(`${source} must be a string.`);
+            }
+            const trimmed = value.trim();
+            if (!trimmed) {
+                throw new GitNexusRcError(`${source} must not be empty.`);
+            }
+            assertNoHiddenChars(trimmed, source);
+            // `name` flows into the generated AGENTS.md/CLAUDE.md as `**${name}**` and
+            // inside `gitnexus://repo/${name}/…` code spans, so a Markdown-significant
+            // character would break those spans or inject emphasis/links/HTML into
+            // agent-instruction content (#1996 tri-review P1). `_` is intentionally
+            // allowed (legitimate in repo names; intraword `_` is not emphasis).
+            // embeddingDevice (the other `string`-kind option) only ever holds a
+            // fixed device token, so this guard never rejects a valid value there.
+            if (/[`*[\]<>]/.test(trimmed)) {
+                throw new GitNexusRcError(`${source} must not contain Markdown-significant characters (\` * [ ] < >).`);
+            }
+            return trimmed;
+        }
+        case 'numeric-string': {
+            // Mirror Commander's contract: these options reach the existing CLI
+            // validation as strings. Accept a JSON number or a string; normalize to a
+            // string and let the downstream per-flag validation enforce ranges so the
+            // error messages stay in one place.
+            if (typeof value === 'number') {
+                if (!Number.isFinite(value)) {
+                    throw new GitNexusRcError(`${source} must be a finite number.`);
+                }
+                return String(value);
+            }
+            if (typeof value === 'string') {
+                const trimmed = value.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} must not be empty.`);
+                }
+                return trimmed;
+            }
+            throw new GitNexusRcError(`${source} must be a number or numeric string.`);
+        }
+        case 'embeddings': {
+            // Mirror `--embeddings [limit]`: boolean toggles, a non-negative integer
+            // sets the node cap (normalized to a string, as Commander would supply).
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'number') {
+                if (!Number.isInteger(value) || value < 0) {
+                    throw new GitNexusRcError(`${source} must be true/false or a non-negative integer (node cap; 0 disables the cap).`);
+                }
+                return String(value);
+            }
+            throw new GitNexusRcError(`${source} must be a boolean or a non-negative integer (node cap; 0 disables the cap).`);
+        }
+        default:
+            // Exhaustive — kept for forward-compat if a new kind is added.
+            throw new GitNexusRcError(`${source}: unsupported config value kind.`);
+    }
+};
+/**
+ * Normalize one level (flat top-level or the nested `analyze` block) into a
+ * partial `AnalyzeOptions`. Rejects unknown keys and two aliases that configure
+ * the same option at the same level.
+ */
+const normalizeLevel = (obj, { allowNestedKey }) => {
+    const out = {};
+    const setBy = new Map();
+    for (const [key, value] of Object.entries(obj)) {
+        if (allowNestedKey && key === NESTED_KEY)
+            continue; // handled separately
+        // `Object.hasOwn`, not a truthiness check: a plain-object lookup like
+        // `KEY_SPECS["__proto__"]` returns an inherited member (Object.prototype,
+        // truthy) and would slip past `if (!spec)`, hitting the wrong error branch
+        // instead of the documented "Unknown key" message (#1996 tri-review P3).
+        if (!Object.hasOwn(KEY_SPECS, key)) {
+            throw new GitNexusRcError(`Unknown key "${key}" in ${GITNEXUS_RC_FILENAME}. ${ALLOWED_KEYS_HINT}`);
+        }
+        const spec = KEY_SPECS[key];
+        const prev = setBy.get(spec.target);
+        if (prev && prev !== key) {
+            throw new GitNexusRcError(`${GITNEXUS_RC_FILENAME}: "${prev}" and "${key}" both configure the same option; set only one.`);
+        }
+        setBy.set(spec.target, key);
+        out[spec.target] = normalizeValue(spec.kind, value, key);
+    }
+    return out;
+};
+/**
+ * Locate, read, parse, validate, and normalize `.gitnexusrc` at `repoRoot`.
+ *
+ * @returns the normalized config defaults, or `undefined` when no file exists
+ *          (the normal case). Throws {@link GitNexusRcError} on any problem.
+ */
+export function loadAnalyzeConfig(repoRoot) {
+    const filePath = path.join(repoRoot, GITNEXUS_RC_FILENAME);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return undefined;
+        throw new GitNexusRcError(`Could not read ${GITNEXUS_RC_FILENAME}: ${err.message}`);
+    }
+    // Strip a leading UTF-8 BOM: Node's 'utf-8' decode keeps it, and JSON.parse
+    // then fails with a confusing "Unexpected token" on an otherwise-valid file
+    // (#1996 tri-review). Only one leading BOM is stripped; in-string control
+    // rejection still applies to the parsed values.
+    if (raw.charCodeAt(0) === 0xfeff)
+        raw = raw.slice(1);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GitNexusRcError(`${GITNEXUS_RC_FILENAME} is not valid JSON: ${err.message}. ` +
+            `Expected a JSON object such as {"defaultBranch": "develop", "skipContextFiles": true}.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new GitNexusRcError(`${GITNEXUS_RC_FILENAME} must contain a JSON object.`);
+    }
+    const obj = parsed;
+    const flat = normalizeLevel(obj, { allowNestedKey: true });
+    let nested = {};
+    if (Object.prototype.hasOwnProperty.call(obj, NESTED_KEY)) {
+        const nestedRaw = obj[NESTED_KEY];
+        if (nestedRaw === null || typeof nestedRaw !== 'object' || Array.isArray(nestedRaw)) {
+            throw new GitNexusRcError(`${GITNEXUS_RC_FILENAME} "${NESTED_KEY}" must be a JSON object.`);
+        }
+        nested = normalizeLevel(nestedRaw, { allowNestedKey: false });
+    }
+    // Nested `analyze` block overrides flat top-level keys for the same option.
+    return { ...flat, ...nested };
+}
+/**
+ * Merge CLI options over `.gitnexusrc` defaults. CLI wins whenever it provides a
+ * value — including an explicit `false` (so an explicit CLI off-switch beats a
+ * config `true`). Config fills only the genuinely-unset (`undefined`) options.
+ *
+ * `stats` is special: Commander always materializes it (`true` by default,
+ * `false` only when `--no-stats` is passed), so plain `??` can't tell "default
+ * on" from "explicitly on". The rule is: a passed `--no-stats` (`stats: false`)
+ * always wins; otherwise the config value applies. There is intentionally no
+ * `--stats` counter-flag, so config can only turn stats off, not force it back
+ * on against a `--no-stats`.
+ *
+ * `defaultBranch` is NOT resolved here — see {@link resolveDefaultBranch}, which
+ * applies the CLI > config > auto-detect > "main" precedence chain.
+ */
+export function mergeAnalyzeOptions(cli, config) {
+    if (!config)
+        return cli;
+    const merged = { ...cli };
+    for (const key of Object.keys(config)) {
+        if (key === 'stats' || key === 'defaultBranch')
+            continue; // handled below / by resolver
+        if (merged[key] === undefined) {
+            merged[key] = config[key];
+        }
+    }
+    if (config.stats !== undefined && cli.stats !== false) {
+        merged.stats = config.stats;
+    }
+    return merged;
+}
+/**
+ * Resolve the default branch threaded into generated context, applying the
+ * precedence chain:
+ *
+ *   CLI `--default-branch` > `.gitnexusrc` `defaultBranch`/`branch`
+ *     > auto-detected `origin/HEAD` > {@link DEFAULT_BRANCH_FALLBACK} ("main").
+ *
+ * User-supplied values (CLI, config) are validated strictly and throw on bad
+ * input. The auto-detected value is best-effort and silently ignored if
+ * unusable.
+ */
+export function resolveDefaultBranch(input) {
+    if (input.cliBranch !== undefined) {
+        return validateBranchName(input.cliBranch, '--default-branch');
+    }
+    if (input.configBranch !== undefined) {
+        return validateBranchName(input.configBranch, `${GITNEXUS_RC_FILENAME} "defaultBranch"`);
+    }
+    const detected = sanitizeDetectedBranch(input.detectedBranch);
+    if (detected)
+        return detected;
+    return DEFAULT_BRANCH_FALLBACK;
+}

package/dist/cli/analyze.d.ts

@@ -42,6 +42,13 @@ export interface AnalyzeOptions {
     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;
     /** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
     indexOnly?: boolean;
     /** Index the folder even when no .git directory is present. */

package/dist/cli/analyze.js

@@ -14,7 +14,8 @@ import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
 import { isLbugCheckpointIoError, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
-import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
+import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import { warnMissingOptionalGrammars } from './optional-grammars.js';
@@ -454,14 +455,101 @@ export const analyzeCommand = async (inputPath, options) => {
         restoreAnalyzeEnv(envSnap);
     }
 };
-const analyzeCommandImpl = async (inputPath, options) => {
-    if (options?.verbose) {
+const analyzeCommandImpl = async (inputPath, cliOptions) => {
+    console.log('\n  GitNexus Analyzer\n');
+    // ── Resolve the target repo root ──────────────────────────────────
+    // Resolved FIRST because `.gitnexusrc` is read from the repo root (not the
+    // caller's cwd), and config can set defaults that the validation below
+    // consumes. `--skip-git` is a CLI-only flag (never a config key), so the raw
+    // CLI options are authoritative for repo-root resolution.
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else if (cliOptions?.skipGit) {
+        // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
+        repoPath = path.resolve(process.cwd());
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    const repoHasGit = hasGitDir(repoPath);
+    if (!repoHasGit && !cliOptions?.skipGit) {
+        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!repoHasGit) {
+        console.log('  Warning: no .git directory found — commit-tracking and incremental updates disabled.\n');
+    }
+    // Validate an explicit `--default-branch` up front so its errors are
+    // attributed to the flag (with a CLI-specific recovery hint) rather than to
+    // `.gitnexusrc`, which the user may not even have (#1996 tri-review).
+    if (cliOptions?.defaultBranch !== undefined) {
+        try {
+            validateBranchName(cliOptions.defaultBranch, '--default-branch');
+        }
+        catch (err) {
+            cliError(`  ${err instanceof Error ? err.message : String(err)}\n`, {
+                recoveryHint: 'default-branch-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // ── Load .gitnexusrc and merge: CLI flags override config (#243) ───
+    // Parse/validate before the progress bar so a malformed config produces an
+    // actionable error and exits before any expensive analysis starts.
+    let options;
+    let resolvedDefaultBranch;
+    try {
+        const fileConfig = loadAnalyzeConfig(repoPath);
+        options = mergeAnalyzeOptions(cliOptions ?? {}, fileConfig);
+        // Resolve the default branch threaded into generated context:
+        //   CLI --default-branch > .gitnexusrc defaultBranch/branch
+        //     > auto-detected origin/HEAD > "main".
+        // Only shell out to git when no branch was configured AND the generated
+        // context will actually use it, keeping the common path free of an extra
+        // git call. Detection is best-effort and never blocks analyze.
+        const cliBranch = cliOptions?.defaultBranch;
+        const configBranch = fileConfig?.defaultBranch;
+        const willGenerateContext = !options.indexOnly && !options.skipAgentsMd;
+        let detectedBranch = null;
+        if (cliBranch === undefined &&
+            configBranch === undefined &&
+            repoHasGit &&
+            !cliOptions?.skipGit &&
+            willGenerateContext) {
+            try {
+                detectedBranch = getDefaultBranch(repoPath);
+            }
+            catch {
+                detectedBranch = null;
+            }
+        }
+        resolvedDefaultBranch = resolveDefaultBranch({ cliBranch, configBranch, detectedBranch });
+    }
+    catch (err) {
+        const msg = err instanceof GitNexusRcError
+            ? err.message
+            : `Invalid .gitnexusrc: ${err instanceof Error ? err.message : String(err)}`;
+        cliError(`  ${msg}\n`, { recoveryHint: 'gitnexusrc-invalid' });
+        process.exitCode = 1;
+        return;
+    }
+    if (options.verbose) {
         process.env.GITNEXUS_VERBOSE = '1';
     }
-    if (options?.maxFileSize) {
+    if (options.maxFileSize) {
         process.env.GITNEXUS_MAX_FILE_SIZE = options.maxFileSize;
     }
-    if (options?.workerTimeout) {
+    if (options.workerTimeout) {
         const workerTimeoutSeconds = Number(options.workerTimeout);
         if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
             cliError('  --worker-timeout must be at least 1 second.\n');
@@ -470,7 +558,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
     }
-    if (options?.walCheckpointThreshold !== undefined) {
+    if (options.walCheckpointThreshold !== undefined) {
         const parsed = parseWalCheckpointThreshold(options.walCheckpointThreshold);
         if (parsed === undefined) {
             cliError('  --wal-checkpoint-threshold must be an integer >= -1.\n');
@@ -486,7 +574,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
     // values back-to-back and observe the value they passed, not whatever the
     // previous call leaked.
     let workerPoolSize;
-    if (options?.workers !== undefined) {
+    if (options.workers !== undefined) {
         const parsedWorkers = Number(options.workers);
         if (!Number.isInteger(parsedWorkers) || parsedWorkers < 0) {
             cliError('  --workers must be a non-negative integer. ' +
@@ -501,7 +589,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
     // sibling-validation pattern (exit before bar.start() — otherwise
     // process.exit() leaves the progress bar's hidden cursor uncleared).
     let embeddingsNodeLimit;
-    if (typeof options?.embeddings === 'string') {
+    if (typeof options.embeddings === 'string') {
         const parsed = Number(options.embeddings);
         if (!Number.isInteger(parsed) || parsed < 0) {
             cliError(`  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
@@ -511,7 +599,7 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         embeddingsNodeLimit = parsed;
     }
-    const embeddingsEnabled = !!options?.embeddings;
+    const embeddingsEnabled = !!options.embeddings;
     const setPositiveEnv = (optionName, envName, value) => {
         if (value === undefined)
             return true;
@@ -524,12 +612,12 @@ const analyzeCommandImpl = async (inputPath, options) => {
         process.env[envName] = String(parsed);
         return true;
     };
-    if (!setPositiveEnv('--embedding-threads', 'GITNEXUS_EMBEDDING_THREADS', options?.embeddingThreads) ||
-        !setPositiveEnv('--embedding-batch-size', 'GITNEXUS_EMBEDDING_BATCH_SIZE', options?.embeddingBatchSize) ||
-        !setPositiveEnv('--embedding-sub-batch-size', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', options?.embeddingSubBatchSize)) {
+    if (!setPositiveEnv('--embedding-threads', 'GITNEXUS_EMBEDDING_THREADS', options.embeddingThreads) ||
+        !setPositiveEnv('--embedding-batch-size', 'GITNEXUS_EMBEDDING_BATCH_SIZE', options.embeddingBatchSize) ||
+        !setPositiveEnv('--embedding-sub-batch-size', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', options.embeddingSubBatchSize)) {
         return;
     }
-    if (options?.embeddingDevice) {
+    if (options.embeddingDevice) {
         const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
         if (!allowed.has(options.embeddingDevice)) {
             cliError('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
@@ -538,48 +626,21 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
     }
-    if (options?.repairFts && options?.force) {
+    if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
         process.exitCode = 1;
         return;
     }
-    console.log('\n  GitNexus Analyzer\n');
     // `--index-only` is the stronger contract — it suppresses every form of file
     // injection, including community skill writes that `--skills` would normally
     // produce. Surface the override explicitly so users don't wonder why a
     // pipeline re-index ran but no skill files appeared. The pipeline still
-    // re-runs (see `force: options?.force || options?.skills` below); the warning
+    // re-runs (see `force: options.force || options.skills` below); the warning
     // is purely about the dropped post-index write step.
-    if (options?.indexOnly && options?.skills) {
+    if (options.indexOnly && options.skills) {
         console.log('  Note: --index-only overrides --skills; community skill files will not be written.\n');
     }
-    let repoPath;
-    if (inputPath) {
-        repoPath = path.resolve(inputPath);
-    }
-    else if (options?.skipGit) {
-        // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
-        repoPath = path.resolve(process.cwd());
-    }
-    else {
-        const gitRoot = getGitRoot(process.cwd());
-        if (!gitRoot) {
-            console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
-            process.exitCode = 1;
-            return;
-        }
-        repoPath = gitRoot;
-    }
-    const repoHasGit = hasGitDir(repoPath);
-    if (!repoHasGit && !options?.skipGit) {
-        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
-        process.exitCode = 1;
-        return;
-    }
-    if (!repoHasGit) {
-        console.log('  Warning: no .git directory found \u2014 commit-tracking and incremental updates disabled.\n');
-    }
     // If the target repo contains files an optional grammar would parse but
     // that grammar's native binding is absent, warn before analysis so users
     // learn why those files end up unparsed instead of silently getting a
@@ -698,34 +759,37 @@ const analyzeCommandImpl = async (inputPath, options) => {
     const t0 = Date.now();
     // ── Run shared analysis orchestrator ───────────────────────────────
     try {
-        const skipAll = options?.indexOnly;
-        const skipAgentsMd = skipAll || options?.skipAgentsMd;
-        const skipSkills = skipAll || options?.skipSkills;
+        const skipAll = options.indexOnly;
+        const skipAgentsMd = skipAll || options.skipAgentsMd;
+        const skipSkills = skipAll || options.skipSkills;
         const result = await runFullAnalysis(repoPath, {
             // Pipeline re-index — OR'd with --skills because skill generation
             // needs a fresh pipelineResult. Has no bearing on the registry
             // collision guard (see allowDuplicateName below).
-            force: options?.force || options?.skills,
-            repairFts: options?.repairFts,
+            force: options.force || options.skills,
+            repairFts: options.repairFts,
             embeddings: embeddingsEnabled,
             embeddingsNodeLimit,
-            dropEmbeddings: options?.dropEmbeddings,
-            verbose: options?.verbose,
-            skipGit: options?.skipGit,
+            dropEmbeddings: options.dropEmbeddings,
+            verbose: options.verbose,
+            skipGit: options.skipGit,
             skipAgentsMd,
             skipSkills,
+            // Resolved default branch (CLI > .gitnexusrc > auto-detect > "main")
+            // threaded into the generated regression-compare example (#243).
+            defaultBranch: resolvedDefaultBranch,
             // commander.js `.option('--no-stats', …)` registers the flag as
             // `options.stats` (boolean, default true; `false` when the user
-            // passed --no-stats). Reading `options?.noStats` here returns
+            // passed --no-stats). Reading `options.noStats` here returns
             // undefined every time, so the flag was a no-op on the markdown
             // rewrite path before this fix. See #1477.
-            noStats: options?.stats === false,
-            registryName: options?.name,
+            noStats: options.stats === false,
+            registryName: options.name,
             // Registry-collision bypass — its own CLI flag, intentionally NOT
             // overloading --force. A user who hits the collision guard should
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
-            allowDuplicateName: options?.allowDuplicateName,
+            allowDuplicateName: options.allowDuplicateName,
             // Worker pool size threaded from --workers, replacing the previous
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.
@@ -742,6 +806,20 @@ const analyzeCommandImpl = async (inputPath, options) => {
             // that half-finalized state, runFullAnalysis returns alreadyUpToDate
             // on the next invocation unless we check the registry here too.
             await assertAnalysisFinalized(repoPath);
+            // The fast path skips context regeneration, but a changed `.gitnexusrc`
+            // defaultBranch / `--default-branch` must still take effect. Surgically
+            // refresh just the `base_ref` line in AGENTS.md/CLAUDE.md in place,
+            // preserving the rest of the block (incl. --skills community rows). No-op
+            // when the value already matches, so a routine up-to-date run is silent
+            // (#1996 tri-review P2).
+            let baseRefRefreshed = [];
+            try {
+                const { refreshBaseRefLine } = await import('./ai-context.js');
+                baseRefRefreshed = (await refreshBaseRefLine(repoPath, resolvedDefaultBranch, { skipAgentsMd })).files;
+            }
+            catch {
+                /* best-effort — never fail the fast path over a context refresh */
+            }
             clearInterval(elapsedTimer);
             process.removeListener('SIGINT', sigintHandler);
             console.log = origLog;
@@ -751,6 +829,9 @@ const analyzeCommandImpl = async (inputPath, options) => {
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
+            if (baseRefRefreshed.length > 0) {
+                console.log(`  Updated base_ref to "${resolvedDefaultBranch}" in ${baseRefRefreshed.join(', ')}\n`);
+            }
             // Safe to return without process.exit(0) — the early-return path in
             // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
             return;
@@ -809,9 +890,13 @@ const analyzeCommandImpl = async (inputPath, options) => {
                     }, skillResult.skills, {
                         skipAgentsMd,
                         skipSkills,
+                        // Same resolved branch as the main run (#243) so the --skills
+                        // re-generation of AGENTS.md/CLAUDE.md does not revert base_ref
+                        // to "main".
+                        defaultBranch: resolvedDefaultBranch,
                         // Mirror runFullAnalysis `noStats` bridge (#1477) — same expression;
                         // exercised on the `--skills` path by analyze-no-stats-bridge.test.ts.
-                        noStats: options?.stats === false,
+                        noStats: options.stats === false,
                     });
                 }
             }

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/index.js

@@ -27,6 +27,8 @@ program
     .option('--skills', 'Generate repo-specific skill files from detected communities ' +
     '(no-op when --index-only is also set).')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
+    .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
+    'Falls back to .gitnexusrc, then auto-detected origin/HEAD, then "main".')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-skills', 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
     'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +

package/dist/core/run-analyze.d.ts

@@ -48,6 +48,13 @@ export interface AnalyzeOptions {
     noStats?: boolean;
     /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
     skipSkills?: boolean;
+    /**
+     * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
+     * regression-compare example uses the configured branch instead of a
+     * hardcoded "main" (#243). Resolved by the CLI; `undefined` here keeps the
+     * "main" fallback for non-CLI callers (e.g. the server analyze worker).
+     */
+    defaultBranch?: string;
     /**
      * User-provided alias for the registry `name` (#829). When set,
      * forwarded to `registerRepo` so the indexed repo is stored under

package/dist/core/run-analyze.js

@@ -779,6 +779,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 skipAgentsMd: options.skipAgentsMd,
                 skipSkills: options.skipSkills,
                 noStats: options.noStats,
+                defaultBranch: options.defaultBranch,
             });
         }
         catch {

package/dist/storage/git.d.ts

@@ -107,6 +107,17 @@ export declare const hasGitDir: (dirPath: string) => boolean;
  * `<rig>/refinery/rig/` layouts).
  */
 export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
+/**
+ * Best-effort detection of the repository's default branch (#243).
+ *
+ * Reads `git symbolic-ref --short refs/remotes/origin/HEAD`, which resolves to
+ * the short ref `origin/<branch>` that the local `origin/HEAD` points at, and
+ * strips the `origin/` prefix. This is a purely local lookup — it never makes a
+ * network call. Returns `null` when there is no git repo, no `origin` remote, no
+ * `origin/HEAD` (e.g. it was never set by clone, or the repo is detached), or
+ * git is unavailable, so callers can fall back to a configured/default branch.
+ */
+export declare const getDefaultBranch: (repoPath: string) => string | null;
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/git.js

@@ -265,6 +265,36 @@ export const getRemoteOriginUrl = (repoPath) => {
         return null;
     }
 };
+/**
+ * Best-effort detection of the repository's default branch (#243).
+ *
+ * Reads `git symbolic-ref --short refs/remotes/origin/HEAD`, which resolves to
+ * the short ref `origin/<branch>` that the local `origin/HEAD` points at, and
+ * strips the `origin/` prefix. This is a purely local lookup — it never makes a
+ * network call. Returns `null` when there is no git repo, no `origin` remote, no
+ * `origin/HEAD` (e.g. it was never set by clone, or the repo is detached), or
+ * git is unavailable, so callers can fall back to a configured/default branch.
+ */
+export const getDefaultBranch = (repoPath) => {
+    try {
+        const ref = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+            cwd: repoPath,
+            // Suppress stderr -- see getCurrentCommit comment and #1172. Without it,
+            // git prints "fatal: ref refs/remotes/origin/HEAD is not a symbolic ref"
+            // to the user's terminal on repos that never set origin/HEAD.
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        })
+            .toString()
+            .trim();
+        if (!ref)
+            return null;
+        return ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref;
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.130",
+  "version": "1.6.6-rc.131",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",