gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
+import { type NativeCheckResult } from '../core/lbug/native-check.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -47,4 +48,15 @@ export declare function pageSizeDoctorLines(pageSize: number | undefined, ladybu
  * value is absolute, so a "×N" note would misdescribe both.
  */
 export declare function poolSizeDoctorLine(pool: number, envRaw: string | undefined): string;
+/**
+ * The `native` status line. Literal label like the page-size and pool-size lines
+ * above (no i18n key).
+ *
+ * A failed check is not automatically a MISSING binary, and saying so is the
+ * same misdiagnosis #2672 fixed one layer down: on a host whose glibc is too
+ * old, `lbugjs.node` is present and merely unloadable, so "missing" sent users
+ * to reinstall a file that was already there — while the detail written to
+ * stderr right below said the opposite. Render what the check actually found.
+ */
+export declare function nativeStatusLine(check: NativeCheckResult): string;
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -130,6 +130,36 @@ export function poolSizeDoctorLine(pool, envRaw) {
     const envNote = envRaw !== undefined && envRaw.trim().length > 0 ? ' (env override)' : '';
     return `  ${padDisplayEnd('pool size', 10)}${value}${envNote}`;
 }
+/**
+ * The `native` status line. Literal label like the page-size and pool-size lines
+ * above (no i18n key).
+ *
+ * A failed check is not automatically a MISSING binary, and saying so is the
+ * same misdiagnosis #2672 fixed one layer down: on a host whose glibc is too
+ * old, `lbugjs.node` is present and merely unloadable, so "missing" sent users
+ * to reinstall a file that was already there — while the detail written to
+ * stderr right below said the opposite. Render what the check actually found.
+ */
+export function nativeStatusLine(check) {
+    return `  ${padDisplayEnd('native', 10)}${nativeStatusText(check)}`;
+}
+function nativeStatusText(check) {
+    if (check.ok)
+        return '✓ lbugjs.node loaded';
+    switch (check.kind) {
+        case 'package_missing':
+            return '✗ @ladybugdb/core not installed';
+        case 'load_failed':
+            return '✗ lbugjs.node present but failed to load';
+        case 'binary_unwritable':
+            // The prebuilt exists; only the copy into node_modules was refused. Saying
+            // "missing" here would contradict the detail printed underneath (#2672).
+            return '✗ lbugjs.node not installed (node_modules not writable)';
+        default:
+            // 'binary_missing', and any future kind: the conservative claim.
+            return '✗ lbugjs.node missing';
+    }
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -151,11 +181,8 @@ export const doctorCommand = async () => {
     // the page size line above (no i18n key).
     console.log(poolSizeDoctorLine(getEffectiveBufferPoolSize(), process.env.GITNEXUS_LBUG_BUFFER_POOL_SIZE));
     const nativeCheck = checkLbugNative();
-    if (nativeCheck.ok) {
-        console.log(`  ${padDisplayEnd('native', 10)}✓ lbugjs.node loaded`);
-    }
-    else {
-        console.log(`  ${padDisplayEnd('native', 10)}✗ lbugjs.node missing`);
+    console.log(nativeStatusLine(nativeCheck));
+    if (!nativeCheck.ok) {
         process.stderr.write(`\n${nativeCheck.message?.replace(/^/gm, '  ')}\n\n`);
     }
     console.log(`  ${label('doctor.labels.onnx', 10)}${fingerprint.onnxruntime ?? 'unknown'}`);

package/dist/cli/editor-targets.js

@@ -47,6 +47,12 @@ export function getEditorTargets(home = os.homedir()) {
             id: 'opencode',
             label: 'OpenCode',
             file: path.join(home, '.config', 'opencode', 'opencode.json'),
+            // OpenCode merges config.json -> opencode.json -> opencode.jsonc; setup
+            // writes an existing readable config to avoid creating a shadow file.
+            legacyFiles: [
+                path.join(home, '.config', 'opencode', 'opencode.jsonc'),
+                path.join(home, '.config', 'opencode', 'config.json'),
+            ],
             // OpenCode nests servers under `mcp`, not `mcpServers`.
             keyPath: ['mcp', 'gitnexus'],
         },

package/dist/cli/eval-server.js

@@ -40,6 +40,7 @@ import { LocalBackend, } from '../mcp/local/local-backend.js';
 import { logger } from '../core/logger.js';
 import { cliInfo, cliWarn, cliError } from './cli-message.js';
 import { formatDetectChangesResult } from './detect-changes-format.js';
+import { formatSymbolLine } from './format-symbol.js';
 export { formatDetectChangesResult } from './detect-changes-format.js';
 /**
  * Validate the --host value. Accepts IPv4, IPv6, or "localhost".
@@ -165,7 +166,7 @@ export function formatQueryResult(result) {
     if (defs.length > 0) {
         lines.push(`Standalone definitions:`);
         for (const d of defs.slice(0, 8)) {
-            lines.push(`  ${d.type || 'Symbol'} ${d.name} → ${d.filePath || '?'}`);
+            lines.push(formatSymbolLine(d.type, d.name, d.filePath));
         }
         if (defs.length > 8)
             lines.push(`  ... and ${defs.length - 8} more`);

package/dist/cli/format-symbol.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Symbol listing line — the one rendering of `Type name → path` shared by every
+ * formatter that lists symbols. Kept in its own tool-neutral module so a new
+ * consumer does not have to import it from another tool's formatter.
+ */
+/**
+ * One indented `Type name → path` listing line for a symbol. Shared by the
+ * `detect_changes` CLI formatter and the eval-server `query` formatter so the
+ * two renderings cannot drift apart.
+ *
+ * `||`, not `??`: a node whose label came back as an EMPTY STRING (several node
+ * types do — see enrichCandidateLabels) still needs the placeholder, and `??`
+ * would print the empty string instead.
+ */
+export declare function formatSymbolLine(type: string | undefined, name: string | undefined, filePath: string | undefined): string;

package/dist/cli/format-symbol.js

@@ -0,0 +1,17 @@
+/**
+ * Symbol listing line — the one rendering of `Type name → path` shared by every
+ * formatter that lists symbols. Kept in its own tool-neutral module so a new
+ * consumer does not have to import it from another tool's formatter.
+ */
+/**
+ * One indented `Type name → path` listing line for a symbol. Shared by the
+ * `detect_changes` CLI formatter and the eval-server `query` formatter so the
+ * two renderings cannot drift apart.
+ *
+ * `||`, not `??`: a node whose label came back as an EMPTY STRING (several node
+ * types do — see enrichCandidateLabels) still needs the placeholder, and `??`
+ * would print the empty string instead.
+ */
+export function formatSymbolLine(type, name, filePath) {
+    return `  ${type || 'Symbol'} ${name || '?'} → ${filePath || '?'}`;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Metadata for one repo-specific skill file generated from a detected
+ * community.
+ *
+ * Produced by `skill-gen`'s `generateSkillFiles` and consumed by `ai-context`
+ * when it lists the generated skills in AGENTS.md / CLAUDE.md. It lives in this
+ * leaf module rather than in either of those so the consumer does not have to
+ * import the producer for a type — `ai-context` already supplies the
+ * `.agents/` mirror check that `skill-gen` calls, and the two directions
+ * together made an import cycle.
+ */
+export interface GeneratedSkillInfo {
+    name: string;
+    label: string;
+    symbolCount: number;
+    fileCount: number;
+}

package/dist/cli/generated-skill.js

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

package/dist/cli/group.js

@@ -100,7 +100,24 @@ export function registerGroupCommands(program) {
             console.log('  Repo index / contracts staleness:');
             for (const [repoPath, row] of Object.entries(st.repos || {})) {
                 if (row.missing) {
-                    console.log(`  ${repoPath.padEnd(25)} MISSING   (not in registry or unreadable)`);
+                    // Two different facts with two different remedies: a repo the
+                    // registry never heard of is fixed by indexing it, while an entry
+                    // the resolver choked on is fixed by repairing the registry.
+                    // Printing "no entry in the registry" for the second one states a
+                    // cause that was never measured, and points at the wrong repair.
+                    if (row.unresolvable) {
+                        // The reason can be multi-line — an ambiguous registry names
+                        // every colliding clone. Fold it onto this row's line rather
+                        // than truncating it: those paths are what the operator acts on,
+                        // and a table row that swallows half its own explanation is the
+                        // failure this label exists to stop.
+                        const why = (row.unresolvableReason ?? 'the registry entry could not be resolved')
+                            .replace(/\s+/g, ' ')
+                            .trim();
+                        console.log(`  ${repoPath.padEnd(25)} UNRESOLVABLE (${why})`);
+                        continue;
+                    }
+                    console.log(`  ${repoPath.padEnd(25)} MISSING   (no entry in the registry)`);
                     continue;
                 }
                 const idx = row.indexStale
@@ -109,9 +126,38 @@ export function registerGroupCommands(program) {
                 const ctr = row.contractsStale ? ' CONTRACTS_STALE' : '';
                 console.log(`  ${repoPath.padEnd(25)} ${idx}${ctr}`);
             }
+            // `undefined` and `[]` are different answers here: a registry written
+            // before this was tracked has no opinion, while an empty array is a
+            // measurement. Printing nothing for both would let an unmeasured sync
+            // read as evidence that every index opened cleanly.
+            //
+            // `undefined` covers two ways of not knowing — the field is absent, or
+            // it held something that was not a list of repo paths and `getStatus`
+            // declined to guess. Naming only the first would make a corrupt
+            // registry read as a merely old one, which is the same shape of wrong
+            // answer this command exists to stop giving.
+            const unreadable = st.unreadableRepos;
+            if (unreadable === undefined) {
+                console.log(`\n  Last sync unreadable repos: not recorded` +
+                    `\n     (the registry predates this field, or its value could not be read)` +
+                    `\n     Re-run \`gitnexus group sync\` to record it.`);
+            }
+            else if (unreadable.length > 0) {
+                console.log(`\n  Last sync unreadable repos: ${unreadable.join(', ')}`);
+            }
             if ((st.missingRepos || []).length > 0) {
                 console.log(`\n  Last sync missing repos: ${st.missingRepos.join(', ')}`);
             }
+            // Only the populated case prints. Absent means a registry that predates
+            // the field, and empty is the ordinary clean sync — neither is worth a
+            // line, whereas a narrowed registry changes how every later answer
+            // should be read.
+            const skippedStages = st.suppressedMatchStages ?? [];
+            if (skippedStages.length > 0) {
+                console.log(`\n  Last sync skipped matching stages: ${skippedStages.join(', ')}` +
+                    `\n     Cross-links those stages would have found are absent by request.` +
+                    `\n     Re-run \`gitnexus group sync\` without --exact-only for the complete set.`);
+            }
         }
         finally {
             await backend.dispose().catch(() => { });
@@ -120,34 +166,121 @@ export function registerGroupCommands(program) {
     group
         .command('sync <name>')
         .description('Sync Contract Registry — extract contracts and build cross-links')
-        .option('--skip-embeddings', 'Exact + BM25 only (no embedding fallback)')
-        .option('--exact-only', 'Exact match only')
-        .option('--allow-stale', 'Skip stale index warnings')
-        .option('--verbose', 'Show each cross-link detail')
+        .option('--exact-only', 'Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)')
+        .option('--verbose', 'Show additional sync diagnostics')
         .option('--json', 'JSON output')
         .action(async (name, opts) => {
         const { getGroupDir, getDefaultGitnexusDir } = await import('../core/group/storage.js');
         const { loadGroupConfig } = await import('../core/group/config-parser.js');
         const { syncGroup } = await import('../core/group/sync.js');
+        const { GroupSyncLockError } = await import('../core/group/group-lock.js');
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
         const config = await loadGroupConfig(groupDir);
         console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
-        const result = await syncGroup(config, {
-            groupDir,
-            allowStale: Boolean(opts.allowStale),
-            verbose: Boolean(opts.verbose),
-            skipEmbeddings: Boolean(opts.skipEmbeddings),
-            exactOnly: Boolean(opts.exactOnly),
-        });
+        let result;
+        try {
+            result = await syncGroup(config, {
+                groupDir,
+                verbose: Boolean(opts.verbose),
+                exactOnly: Boolean(opts.exactOnly),
+            });
+        }
+        catch (err) {
+            // A sync that could not take the group's lock did NOT run and wrote
+            // nothing (R9 fails closed). That is an operator-actionable outcome, not
+            // a crash, so report it as a failed command rather than letting it
+            // surface as an unhandled rejection with a stack trace — commander's
+            // async actions have no error handler, so an uncaught throw here would
+            // print exactly that.
+            if (!(err instanceof GroupSyncLockError))
+                throw err;
+            logger.error(`⚠️ Did not sync group "${name}": ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.log(`\nMatching cascade:`);
-            const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
-            console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
-            console.log(`  unmatched: ${result.unmatched.length} contracts`);
-            console.log(`\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`);
+            // Repos we could not read are the most likely explanation for a small
+            // or empty contract count, so they are reported before the counts —
+            // otherwise a run that read nothing looks exactly like a clean run.
+            if (result.unreadableRepos.length > 0) {
+                // No "re-run with GITNEXUS_LOG_LEVEL=warn" hint: the default level is
+                // `info`, and pino emits `warn` (40) at `info` (30), so the reason was
+                // already printed by this same run — raising the level to `warn` would
+                // only suppress the surrounding `info` output.
+                console.log(`\n  ⚠️ Could not extract contracts from: ${result.unreadableRepos.join(', ')}` +
+                    `\n     None of their contracts are included in this sync (the warning above says why),` +
+                    `\n     or check \`gitnexus doctor\` in the affected repo.`);
+            }
+            if (result.missingRepos.length > 0) {
+                console.log(`\n  ⚠️ Not found in the registry: ${result.missingRepos.join(', ')}` +
+                    `\n     Index them with \`gitnexus analyze\`, or remove them from group.yaml.`);
+            }
+            // Every stage that produced a link, not just `exact`. This used to print
+            // `Matching cascade:` and then count `exact` alone, while the `Wrote
+            // contracts.json (…)` line below reports `result.crossLinks.length` —
+            // which also includes `manifest` and `wildcard` links. For any group with
+            // those, the two numbers disagreed with nothing on screen explaining why.
+            // Summing the stages here makes them reconcile by construction.
+            console.log(`\nMatching:`);
+            // Exhaustive by construction, same idiom as OUTCOME_LINE below: adding a
+            // MatchType fails the build here instead of silently going uncounted and
+            // reopening the very mismatch this replaced. Every stage prints even at
+            // zero — a stage that is absent reads as "did not apply", not "found none".
+            const STAGE_COUNTS = {
+                exact: 0,
+                manifest: 0,
+                wildcard: 0,
+            };
+            for (const link of result.crossLinks)
+                STAGE_COUNTS[link.matchType] += 1;
+            // A stage the sync was told to skip is reported as skipped, not as a
+            // zero count. The two are different facts — "ran, matched nothing" and
+            // "never ran" — and printing both as `0` is the same conflation this
+            // block replaced. Driven by what the sync did (`suppressedMatchStages`)
+            // rather than by what the caller asked for, so it stays correct on the
+            // outcomes where the run ended without writing a registry.
+            for (const stage of Object.keys(STAGE_COUNTS)) {
+                const count = STAGE_COUNTS[stage];
+                const label = `${stage}:`.padEnd(10);
+                if (result.suppressedMatchStages.includes(stage)) {
+                    console.log(`  ${label} skipped (--exact-only)`);
+                    continue;
+                }
+                const confidence = stage === 'exact' ? ' (confidence 1.0)' : '';
+                console.log(`  ${label} ${count} cross-links${confidence}`);
+            }
+            console.log(`  ${'unmatched:'.padEnd(10)} ${result.unmatched.length} contracts`);
+            // Driven by what actually happened to the file. This line used to be
+            // unconditional, so a run that deliberately preserved the previous
+            // registry still announced `Wrote contracts.json (0 contracts, 0
+            // cross-links)` — a confident false statement about persisted state, on
+            // the exact path this command exists to make legible.
+            // Exhaustive by construction: a `Record` keyed on the union means a
+            // new outcome fails the build here instead of printing nothing, which
+            // is what previously pushed a distinct state into `preserved` and made
+            // this summary false on one of the two branches it then covered.
+            const OUTCOME_LINE = {
+                written: `\nWrote contracts.json (${result.contracts.length} contracts, ` +
+                    `${result.crossLinks.length} cross-links)`,
+                preserved: `\nKept the previous contracts.json — no repo in this group could be read.` +
+                    `\n  Its contracts and cross-links are unchanged; only the unreadable/missing` +
+                    `\n  repo lists were refreshed to describe THIS run. Fix the repos above and re-run.`,
+                superseded: `\nDid NOT touch contracts.json — no repo in this group could be read, and another` +
+                    `\n  sync replaced the file while this one waited for the group lock. That sync's` +
+                    `\n  result stands and this run's repo lists were NOT recorded: they describe a` +
+                    `\n  group state older than what is on disk. Fix the repos above and re-run.`,
+                'no-prior-registry': `\nDid NOT write contracts.json — no repo in this group could be read,` +
+                    `\n  and there is no previous contracts.json to fall back on. Fix the repos` +
+                    `\n  above and re-run.`,
+                // Nothing to say: the caller asked for no write.
+                'not-attempted': null,
+            };
+            const line = OUTCOME_LINE[result.registryOutcome];
+            if (line)
+                console.log(line);
         }
     });
     group
@@ -213,9 +346,49 @@ export function registerGroupCommands(program) {
             else {
                 const summary = raw?.summary;
                 const risk = raw?.risk;
-                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}`);
+                // A truncated fan-out under-reports risk (mergeRisk only grows with
+                // traversed crossings), and the default human output used to print a
+                // bare `risk=` indistinguishable from a complete run — the JSON
+                // already carried `truncated`, but nobody reading the terminal saw it.
+                const riskFloor = raw?.riskEpistemic === 'lower-bound' ? '+' : '';
+                const boundaryOnly = raw?.cross?.filter((entry) => entry.fanout_status === 'not_attempted').length ?? 0;
+                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}${riskFloor}`);
                 if (summary) {
-                    console.log(`  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}`);
+                    const boundaryNote = boundaryOnly > 0 ? ` (${boundaryOnly} boundary-only)` : '';
+                    console.log(`  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}${boundaryNote}`);
+                }
+                if (riskFloor) {
+                    // `truncated` has two independent causes that point at different
+                    // subsystems, so the note must name the one that actually fired:
+                    // dropped crossings, or a local walk that never finished (most
+                    // often the impact chunk cap, which any symbol with more than a
+                    // thousand locally-impacted nodes hits on every run). `dropped` is
+                    // deduped to distinct repos before it reaches here, so it counts
+                    // repos — reporting it as crossings understates a fan-out cap the
+                    // same way #2787's totals did.
+                    const dropped = raw?.truncatedRepos ?? [];
+                    const reason = raw?.truncationReason;
+                    // Keyed on the REASON, not on which incidental fact happens to be
+                    // non-empty. `truncatedRepos` is populated for a structural gap too
+                    // — the bridge's incomplete repos are unioned into it even when ZERO
+                    // crossings were attempted — so branching on its length first
+                    // reported "fan-out stopped early" for a run where nothing stopped
+                    // early, and omitted the only remedy that works. Same false-cause
+                    // shape the contract listing was just re-gated for, one command over.
+                    const floorReason = () => {
+                        if (reason === 'suppressed-stage') {
+                            return 'the last sync skipped a matching stage (--exact-only); re-run `gitnexus group sync` without it for the complete graph';
+                        }
+                        if (reason === 'incomplete-sync') {
+                            return dropped.length > 0
+                                ? `the last sync could not account for ${dropped.join(', ')}; their contracts are absent from every query against this bridge — re-run \`gitnexus group sync\``
+                                : 'the last sync could not say which repos it read — re-run `gitnexus group sync`';
+                        }
+                        return dropped.length > 0
+                            ? `fan-out stopped early; crossings to ${dropped.length} repo(s) not traversed: ${dropped.join(', ')}`
+                            : 'the local impact walk did not complete (every bridge crossing was traversed)';
+                    };
+                    console.log(`  risk is a LOWER BOUND — ${floorReason()}`);
                 }
             }
         }
@@ -285,9 +458,15 @@ export function registerGroupCommands(program) {
                 process.exitCode = 1;
                 return;
             }
-            const { contracts, crossLinks } = raw;
+            const { contracts, crossLinks, truncated, unreadableRepos, missingRepos, suppressedMatchStages, truncationReason, } = raw;
             if (opts.json) {
-                console.log(JSON.stringify({ contracts, crossLinks }, null, 2));
+                // The whole payload, not a re-serialized subset. Destructuring the two
+                // fields this command happens to print and rebuilding an object from
+                // them dropped everything else the service returned — which is how the
+                // completeness fields were invisible here while the MCP tool carried
+                // them. Printing `raw` means a field added to the service reaches
+                // `--json` without a matching edit in this file.
+                console.log(JSON.stringify(raw, null, 2));
             }
             else {
                 console.log(`Contracts (${contracts.length}):`);
@@ -298,6 +477,35 @@ export function registerGroupCommands(program) {
                 for (const l of crossLinks) {
                     console.log(`  ${l.from.repo} -> ${l.to.repo}  [${l.matchType}, conf=${l.confidence}]  ${l.contractId}`);
                 }
+                // Separate from `truncated` below, and deliberately so: that one means
+                // the sync could not read something and the remedy is to fix the repo.
+                // This one means the sync was ASKED to skip a stage, and the remedy is
+                // to re-run without the flag. A listing narrowed on purpose is still
+                // narrowed, and without this the human view showed nothing at all.
+                if (suppressedMatchStages && suppressedMatchStages.length > 0) {
+                    console.log(`\n⚠️ This listing is a lower bound: the last sync skipped ${suppressedMatchStages.join(', ')} matching` +
+                        `\n   (--exact-only), so cross-links that stage would have found are absent.` +
+                        `\n   Re-run \`gitnexus group sync\` without --exact-only for the complete set.`);
+                }
+                // Gated on the REASON, not just the flag. A suppressed stage sets
+                // `truncated` with both repo lists empty, which sent this block down
+                // its else-branch and printed "the last sync did not record which
+                // repos it could read" — a false statement, with the wrong remedy,
+                // about a sync that recorded them fine. The suppressed-stage warning
+                // above already said the true thing. When a repo gap co-occurs the
+                // reason is 'incomplete-sync' (the repo side takes precedence in
+                // `crossRepoCompleteness`), so this block still runs for it.
+                if (truncated && truncationReason !== 'suppressed-stage') {
+                    // Counts above are a floor, not a census. Name the repos when the
+                    // registry recorded them, and say so plainly when it did not — a
+                    // listing that cannot say what it is missing is still incomplete.
+                    const absent = [...(unreadableRepos ?? []), ...(missingRepos ?? [])];
+                    console.log(absent.length > 0
+                        ? `\n⚠️ This listing is incomplete: the last sync could not account for ${absent.join(', ')}.` +
+                            `\n   Contracts from those repos are absent, so the counts above are a lower bound.`
+                        : `\n⚠️ This listing is incomplete: the last sync did not record which repos it could` +
+                            `\n   read, so the counts above are a lower bound. Re-run group sync.`);
+                }
             }
         }
         finally {

package/dist/cli/help-i18n.js

@@ -53,6 +53,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--skills': 'help.option.analyze.skills',
     'analyze|--skip-agents-md': 'help.option.analyze.skipAgentsMd',
     'analyze|--no-stats': 'help.option.analyze.noStats',
+    'analyze|--self-commit': 'help.option.analyze.selfCommit',
     'analyze|--skip-skills': 'help.option.analyze.skipSkills',
     'analyze|--index-only': 'help.option.analyze.indexOnly',
     'analyze|--skip-git': 'help.option.skipGit',
@@ -150,9 +151,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'embeddings install|--cuda': 'help.option.embeddings.install.cuda',
     'embeddings install|--force': 'help.option.embeddings.install.force',
     'group create|--force': 'help.option.group.create.force',
-    'group sync|--skip-embeddings': 'help.option.group.sync.skipEmbeddings',
     'group sync|--exact-only': 'help.option.group.sync.exactOnly',
-    'group sync|--allow-stale': 'help.option.group.sync.allowStale',
     'group sync|--verbose': 'help.option.group.sync.verbose',
     'group sync|--json': 'help.option.json',
     'group impact|--target <symbol>': 'help.option.group.impact.target',

package/dist/cli/i18n/en.d.ts

@@ -54,10 +54,13 @@ export declare const en: {
     readonly 'tool.usage.query': "Usage: gitnexus query [search_query]  or  gitnexus query --query <text>";
     readonly 'tool.usage.context': "Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]";
     readonly 'tool.usage.impact': "Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]";
-    readonly 'tool.usage.trace': "Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]";
+    readonly 'tool.usage.trace': "Usage: gitnexus trace <from> <to> [-f|--file <path>] [--from-file <path>] [--to-file <path>] [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]";
     readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
     readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
     readonly 'tool.detectChanges.noChanges': "No changes detected.";
+    readonly 'tool.detectChanges.partial': "PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.";
+    readonly 'tool.detectChanges.truncated': "LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.";
+    readonly 'tool.detectChanges.truncatedDegraded': "LISTING CAPPED: the changed-symbol list was capped. The run also degraded, so the counts are a lower bound, not a total.";
     readonly 'tool.detectChanges.changesSummary': "Changes: {{files}} files, {{symbols}} symbols";
     readonly 'tool.detectChanges.affectedProcesses': "Affected processes: {{count}}";
     readonly 'tool.detectChanges.riskLevel': "Risk level: {{risk}}";
@@ -153,6 +156,7 @@ export declare const en: {
     readonly 'help.option.analyze.skills': "Generate repo-specific skill files from detected communities (no-op when --index-only is also set).";
     readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md";
     readonly 'help.option.analyze.noStats': "Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md";
+    readonly 'help.option.analyze.selfCommit': "Auto-commit AGENTS.md/CLAUDE.md changes after analyze (opt-in, off by default). Scoped to only those two files (never `git add -A`); no-ops if neither exists, neither changed, or the repo has no git identity configured.";
     readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files directly under .claude/skills/ and .agents/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.";
     readonly 'help.option.analyze.indexOnly': "Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)";
     readonly 'help.option.skipGit': "Treat the provided path/cwd as the index root and skip parent git-root discovery";
@@ -180,13 +184,13 @@ export declare const en: {
     readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
     readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
-    readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
-    readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";
+    readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)";
+    readonly 'help.option.wiki.model': "LLM model or deployment name (default: MiniMax-M3)";
     readonly 'help.option.wiki.baseUrl': "LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1";
     readonly 'help.option.wiki.apiKey': "LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)";
     readonly 'help.option.wiki.apiVersion': "Azure api-version query param, e.g. 2024-10-21 (legacy Azure API only)";
-    readonly 'help.option.wiki.reasoningModel': "Mark deployment as reasoning model (o1/o3/o4-mini) — strips temperature, uses max_completion_tokens";
-    readonly 'help.option.wiki.noReasoningModel': "Disable reasoning model mode (overrides saved config)";
+    readonly 'help.option.wiki.reasoningModel': "Enable reasoning mode; MiniMax-M3 uses adaptive thinking";
+    readonly 'help.option.wiki.noReasoningModel': "Disable reasoning mode; MiniMax-M3 disables thinking";
     readonly 'help.option.wiki.concurrency': "Parallel LLM calls (default: 3)";
     readonly 'help.option.wiki.timeout': "LLM request timeout in seconds (default: disabled)";
     readonly 'help.option.wiki.retries': "Max LLM retry attempts per request (default: 3)";
@@ -229,10 +233,8 @@ export declare const en: {
     readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
     readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
     readonly 'help.option.group.create.force': "Overwrite existing group";
-    readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
-    readonly 'help.option.group.sync.exactOnly': "Exact match only";
-    readonly 'help.option.group.sync.allowStale': "Skip stale index warnings";
-    readonly 'help.option.group.sync.verbose': "Show each cross-link detail";
+    readonly 'help.option.group.sync.exactOnly': "Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)";
+    readonly 'help.option.group.sync.verbose': "Show additional sync diagnostics";
     readonly 'help.option.status.json': "Emit machine-readable index and analyzer provenance";
     readonly 'help.option.json': "JSON output";
     readonly 'help.option.group.impact.target': "Symbol or file name to analyze";

package/dist/cli/i18n/en.js

@@ -54,10 +54,15 @@ export const en = {
     'tool.usage.query': 'Usage: gitnexus query [search_query]  or  gitnexus query --query <text>',
     'tool.usage.context': 'Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]',
     'tool.usage.impact': 'Usage: gitnexus impact <symbol_name> [--uid <uid>] [--file <path>] [--kind <kind>] [--direction upstream|downstream]',
-    'tool.usage.trace': 'Usage: gitnexus trace <from> <to> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
+    'tool.usage.trace': 'Usage: gitnexus trace <from> <to> [-f|--file <path>] [--from-file <path>] [--to-file <path>] [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
     'tool.usage.cypher': 'Usage: gitnexus cypher <cypher_query>',
     'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
     'tool.detectChanges.noChanges': 'No changes detected.',
+    'tool.detectChanges.partial': 'PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.',
+    'tool.detectChanges.truncated': 'LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.',
+    // The reassurance above is only true on its own. When the run also degraded,
+    // `changed_count` was summed from the batches that SUCCEEDED, so it is a floor.
+    'tool.detectChanges.truncatedDegraded': 'LISTING CAPPED: the changed-symbol list was capped. The run also degraded, so the counts are a lower bound, not a total.',
     'tool.detectChanges.changesSummary': 'Changes: {{files}} files, {{symbols}} symbols',
     'tool.detectChanges.affectedProcesses': 'Affected processes: {{count}}',
     'tool.detectChanges.riskLevel': 'Risk level: {{risk}}',
@@ -153,6 +158,7 @@ export const en = {
     'help.option.analyze.skills': 'Generate repo-specific skill files from detected communities (no-op when --index-only is also set).',
     'help.option.analyze.skipAgentsMd': 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md',
     'help.option.analyze.noStats': 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md',
+    'help.option.analyze.selfCommit': 'Auto-commit AGENTS.md/CLAUDE.md changes after analyze (opt-in, off by default). Scoped to only those two files (never `git add -A`); no-ops if neither exists, neither changed, or the repo has no git identity configured.',
     'help.option.analyze.skipSkills': 'Skip installing standard GitNexus skill files directly under .claude/skills/ and .agents/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.',
     'help.option.analyze.indexOnly': 'Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)',
     'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery',
@@ -180,13 +186,13 @@ export const en = {
     'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
     'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
-    'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)',
-    'help.option.wiki.model': 'LLM model or Azure deployment name (default: minimax/minimax-m2.5)',
+    'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)',
+    'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)',
     'help.option.wiki.baseUrl': 'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1',
     'help.option.wiki.apiKey': 'LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)',
     'help.option.wiki.apiVersion': 'Azure api-version query param, e.g. 2024-10-21 (legacy Azure API only)',
-    'help.option.wiki.reasoningModel': 'Mark deployment as reasoning model (o1/o3/o4-mini) — strips temperature, uses max_completion_tokens',
-    'help.option.wiki.noReasoningModel': 'Disable reasoning model mode (overrides saved config)',
+    'help.option.wiki.reasoningModel': 'Enable reasoning mode; MiniMax-M3 uses adaptive thinking',
+    'help.option.wiki.noReasoningModel': 'Disable reasoning mode; MiniMax-M3 disables thinking',
     'help.option.wiki.concurrency': 'Parallel LLM calls (default: 3)',
     'help.option.wiki.timeout': 'LLM request timeout in seconds (default: disabled)',
     'help.option.wiki.retries': 'Max LLM retry attempts per request (default: 3)',
@@ -229,10 +235,8 @@ export const en = {
     'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)",
     'help.option.embeddings.install.force': 'Install into the runtime prefix even when the stack already resolves',
     'help.option.group.create.force': 'Overwrite existing group',
-    'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
-    'help.option.group.sync.exactOnly': 'Exact match only',
-    'help.option.group.sync.allowStale': 'Skip stale index warnings',
-    'help.option.group.sync.verbose': 'Show each cross-link detail',
+    'help.option.group.sync.exactOnly': 'Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)',
+    'help.option.group.sync.verbose': 'Show additional sync diagnostics',
     'help.option.status.json': 'Emit machine-readable index and analyzer provenance',
     'help.option.json': 'JSON output',
     'help.option.group.impact.target': 'Symbol or file name to analyze',