gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/cli/command-banner.js

@@ -0,0 +1,42 @@
+/**
+ * One-line identity printed before every CLI action:
+ * `GitNexus Analyzer (1.6.10)`. Goes to stderr so stdout stays
+ * pipe/JSON-safe (`gitnexus query … | jq`, `status --json`).
+ */
+import { packageVersion } from '../core/package-version.js';
+const SKIP_COMMAND_BANNER = new Set(['__update-check', 'help']);
+const SPECIAL_TITLES = {
+    analyze: 'Analyzer',
+    mcp: 'MCP',
+};
+export function installedCliVersion() {
+    return packageVersion();
+}
+export function commandDisplayName(name) {
+    return (SPECIAL_TITLES[name] ??
+        name
+            .split('-')
+            .filter(Boolean)
+            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+            .join(' '));
+}
+export function commandBannerTitle(command) {
+    const names = [];
+    for (let current = command; current?.parent; current = current.parent) {
+        names.unshift(current.name());
+    }
+    return names.map(commandDisplayName).join(' ');
+}
+export function formatCommandBanner(title, version = installedCliVersion()) {
+    if (!title)
+        return '';
+    return version ? `\n  GitNexus ${title} (${version})\n` : `\n  GitNexus ${title}\n`;
+}
+export function writeCommandBanner(command, deps = {}) {
+    if (SKIP_COMMAND_BANNER.has(command.name()))
+        return;
+    const text = formatCommandBanner(commandBannerTitle(command), deps.version ?? installedCliVersion());
+    if (!text)
+        return;
+    (deps.write ?? ((line) => process.stderr.write(line)))(text);
+}

package/dist/cli/detect-changes-format.js

@@ -20,6 +20,27 @@ export function formatDetectChangesResult(result) {
     if (payload.truncated)
         notes.push(t(payload.partial ? 'tool.detectChanges.truncatedDegraded' : 'tool.detectChanges.truncated'));
     if ((summary.changed_count ?? 0) === 0) {
+        // Parse-fail payloads set `partial` and an honest `message` (#2915/#3131).
+        // Production *clean* trees also set English `message: 'No changes detected.'`
+        // — that must go through `t('tool.detectChanges.noChanges')` or zh-CN never
+        // fires. Only pass the backend string through on a degraded/parse-fail run.
+        if (payload.partial &&
+            typeof summary.message === 'string' &&
+            summary.message.trim().length > 0) {
+            return [...notes, summary.message.trim()].join('\n');
+        }
+        // Confirmed no-overlap: files parsed, mapping succeeded, zero symbols.
+        // `queryDegraded` is `partial: true` with the same counts and no message —
+        // do not call that a confirmed mapping (#3131 honesty).
+        if (!payload.partial && (summary.changed_files ?? 0) > 0) {
+            return [
+                ...notes,
+                t('tool.detectChanges.noOverlappingSymbols', { files: summary.changed_files }),
+            ].join('\n');
+        }
+        if (payload.partial) {
+            return notes.join('\n');
+        }
         return [...notes, t('tool.detectChanges.noChanges')].join('\n');
     }
     const lines = [];

package/dist/cli/doctor.d.ts

@@ -1,5 +1,6 @@
 import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 import { type NativeCheckResult } from '../core/lbug/native-check.js';
+import { type ValidatedUpdateCache } from '../core/update-cache.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -59,4 +60,10 @@ export declare function poolSizeDoctorLine(pool: number, envRaw: string | undefi
  * stderr right below said the opposite. Render what the check actually found.
  */
 export declare function nativeStatusLine(check: NativeCheckResult): string;
+export declare function cachedUpdateDoctorLine(options: {
+    installedVersion: string;
+    eligible: boolean;
+    env: NodeJS.ProcessEnv;
+    readCache: () => ValidatedUpdateCache | null;
+}): string | null;
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -8,7 +8,10 @@ import { checkLbugNative, probeFtsExtensionLoad, probeVectorExtensionLoad, } fro
 import { getEffectiveBufferPoolSize, getOsPageSize, isPageSizeAwareLadybug, } from '../core/lbug/lbug-config.js';
 import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
+import { updateEligibleInstallSync } from '../core/install-context.js';
+import { readValidatedUpdateCacheSync } from '../core/update-cache.js';
 import { t } from './i18n/index.js';
+import { cachedUpdateNoticeLine } from './update-notice.js';
 function isCombiningMark(codePoint) {
     return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
         (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
@@ -160,6 +163,9 @@ function nativeStatusText(check) {
             return '✗ lbugjs.node missing';
     }
 }
+export function cachedUpdateDoctorLine(options) {
+    return cachedUpdateNoticeLine(options);
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -169,6 +175,14 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.os', 10)}${fingerprint.platform}/${fingerprint.arch}`);
     console.log(`  ${label('doctor.labels.node', 10)}${fingerprint.node}`);
     console.log(`  ${label('doctor.labels.gitnexus', 10)}${fingerprint.gitnexus}`);
+    const updateLine = cachedUpdateDoctorLine({
+        installedVersion: fingerprint.gitnexus,
+        eligible: updateEligibleInstallSync(),
+        env: process.env,
+        readCache: () => readValidatedUpdateCacheSync(),
+    });
+    if (updateLine)
+        console.log(`  ${updateLine}`);
     console.log(`  ${label('doctor.labels.ladybugdb', 10)}${fingerprint.ladybugdb ?? 'unknown'}`);
     // OS page size next to the LadybugDB version because the two interact:
     // @ladybugdb/core < 0.18.0 assumed 4 KiB pages in its buffer manager and

package/dist/cli/group.js

@@ -172,8 +172,9 @@ export function registerGroupCommands(program) {
         .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 { syncGroup, formatGroupSyncAmbiguousError } = await import('../core/group/sync.js');
         const { GroupSyncLockError } = await import('../core/group/group-lock.js');
+        const { RegistryAmbiguousTargetError } = await import('../storage/repo-manager.js');
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
         const config = await loadGroupConfig(groupDir);
         console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
@@ -186,6 +187,11 @@ export function registerGroupCommands(program) {
             });
         }
         catch (err) {
+            if (err instanceof RegistryAmbiguousTargetError) {
+                logger.error(`⚠️ Did not sync group "${name}": ${formatGroupSyncAmbiguousError(err)}`);
+                process.exitCode = 1;
+                return;
+            }
             // 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

package/dist/cli/help-i18n.js

@@ -10,6 +10,8 @@ const COMMAND_DESCRIPTION_KEYS = {
     '': 'help.description.root',
     setup: 'help.command.setup.description',
     uninstall: 'help.command.uninstall.description',
+    watch: 'help.command.watch.description',
+    'auto-sync': 'help.command.autoSync.description',
     analyze: 'help.command.analyze.description',
     index: 'help.command.index.description',
     serve: 'help.command.serve.description',
@@ -17,6 +19,7 @@ const COMMAND_DESCRIPTION_KEYS = {
     list: 'help.command.list.description',
     status: 'help.command.status.description',
     doctor: 'help.command.doctor.description',
+    update: 'help.command.update.description',
     embeddings: 'help.command.embeddings.description',
     'embeddings install': 'help.command.embeddings.install.description',
     clean: 'help.command.clean.description',
@@ -47,6 +50,7 @@ const OPTION_DESCRIPTION_KEYS = {
     '|-V, --version': 'help.option.version',
     'setup|-c, --coding-agent <agents>': 'help.option.setup.codingAgent',
     'analyze|-f, --force': 'help.option.analyze.force',
+    'analyze|--no-parse-cache': 'help.option.analyze.noParseCache',
     'analyze|--repair-fts': 'help.option.analyze.repairFts',
     'analyze|--embeddings [limit]': 'help.option.analyze.embeddings',
     'analyze|--drop-embeddings': 'help.option.analyze.dropEmbeddings',

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

@@ -7,6 +7,13 @@ export declare const en: {
     readonly 'common.storage': "Storage";
     readonly 'common.deleted': "Deleted: {{target}}";
     readonly 'common.error': "Error: {{message}}";
+    readonly 'update.available': "GitNexus {{latestVersion}} is available (you are running {{installedVersion}}).";
+    readonly 'update.current': "GitNexus {{installedVersion}} is current or newer than the latest stable version.";
+    readonly 'update.installing': "Installing with {{command}}…";
+    readonly 'update.installed': "Installed gitnexus@{{version}}. Restart long-running mcp/serve processes.";
+    readonly 'update.installFailed': "npm install failed. You can retry: {{command}}";
+    readonly 'update.installError': "Could not run npm: {{message}}";
+    readonly 'update.checkFailed': "Could not check for updates (offline, private registry, or the check failed open).";
     readonly 'list.title': "Indexed Repositories ({{count}})";
     readonly 'list.indexed': "Indexed";
     readonly 'list.commit': "Commit";
@@ -66,6 +73,7 @@ export declare const en: {
     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.noOverlappingSymbols': "Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.";
     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.";
@@ -124,6 +132,11 @@ export declare const en: {
     readonly 'help.option.version': "output the version number";
     readonly 'help.command.setup.description': "One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex";
     readonly 'help.command.uninstall.description': "Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors";
+    readonly 'help.command.autoSync.description': "Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml";
+    readonly 'help.autoSync.details': "\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.";
+    readonly 'help.command.watch.description': "Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes";
+    readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
+    readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
@@ -131,6 +144,7 @@ export declare const en: {
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+    readonly 'help.command.update.description': "Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).";
     readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
     readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
     readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
@@ -157,12 +171,13 @@ export declare const en: {
     readonly 'help.command.group.query.description': "Search execution flows across all repos in a group";
     readonly 'help.command.group.contracts.description': "Inspect Contract Registry";
     readonly 'help.option.setup.codingAgent': "Configure only these coding agents (comma-separated or repeatable)";
-    readonly 'help.option.analyze.force': "Force full re-index even if up to date";
+    readonly 'help.option.analyze.force': "Force graph and FTS rebuild; unchanged parser output may be reused";
+    readonly 'help.option.analyze.noParseCache': "Re-parse every source file instead of replaying cached parser output";
     readonly 'help.option.analyze.repairFts': "Repair/rebuild search FTS indexes without full re-analysis";
     readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
     readonly 'help.option.analyze.dropEmbeddings': "Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.";
     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.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.";
     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.";
@@ -187,7 +202,7 @@ export declare const en: {
     readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
     readonly 'help.option.mcp.http': "Serve MCP over HTTP instead of stdio (for remote clients)";
     readonly 'help.option.mcp.host': "HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.";
-    readonly 'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
+    readonly 'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var, which also enables MCP Bearer auth on gitnexus serve's /api/mcp route. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
     readonly 'help.option.force.confirmation': "Skip confirmation prompt";
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";

package/dist/cli/i18n/en.js

@@ -7,6 +7,13 @@ export const en = {
     'common.storage': 'Storage',
     'common.deleted': 'Deleted: {{target}}',
     'common.error': 'Error: {{message}}',
+    'update.available': 'GitNexus {{latestVersion}} is available (you are running {{installedVersion}}).',
+    'update.current': 'GitNexus {{installedVersion}} is current or newer than the latest stable version.',
+    'update.installing': 'Installing with {{command}}…',
+    'update.installed': 'Installed gitnexus@{{version}}. Restart long-running mcp/serve processes.',
+    'update.installFailed': 'npm install failed. You can retry: {{command}}',
+    'update.installError': 'Could not run npm: {{message}}',
+    'update.checkFailed': 'Could not check for updates (offline, private registry, or the check failed open).',
     'list.title': 'Indexed Repositories ({{count}})',
     'list.indexed': 'Indexed',
     'list.commit': 'Commit',
@@ -66,6 +73,7 @@ export const en = {
     '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.noOverlappingSymbols': 'Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.',
     '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,
@@ -126,6 +134,11 @@ export const en = {
     'help.option.version': 'output the version number',
     'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex',
     'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors',
+    'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml',
+    'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.',
+    'help.command.watch.description': 'Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes',
+    'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
+    'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'help.command.analyze.description': 'Index a repository (full analysis)',
     'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)',
     'help.command.serve.description': 'Start local HTTP server for web UI connection',
@@ -133,6 +146,7 @@ export const en = {
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
+    'help.command.update.description': 'Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).',
     'help.command.embeddings.description': 'Manage the on-demand local embedding runtime',
     'help.command.embeddings.install.description': 'Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.',
     'help.command.clean.description': 'Delete GitNexus index for current repo',
@@ -159,12 +173,13 @@ export const en = {
     'help.command.group.query.description': 'Search execution flows across all repos in a group',
     'help.command.group.contracts.description': 'Inspect Contract Registry',
     'help.option.setup.codingAgent': 'Configure only these coding agents (comma-separated or repeatable)',
-    'help.option.analyze.force': 'Force full re-index even if up to date',
+    'help.option.analyze.force': 'Force graph and FTS rebuild; unchanged parser output may be reused',
+    'help.option.analyze.noParseCache': 'Re-parse every source file instead of replaying cached parser output',
     'help.option.analyze.repairFts': 'Repair/rebuild search FTS indexes without full re-analysis',
     'help.option.analyze.embeddings': 'Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.',
     'help.option.analyze.dropEmbeddings': 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.',
     '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.skipAgentsMd': 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.',
     '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.',
@@ -189,7 +204,7 @@ export const en = {
     'help.option.serve.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)',
     'help.option.mcp.http': 'Serve MCP over HTTP instead of stdio (for remote clients)',
     'help.option.mcp.host': 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.',
-    'help.option.mcp.authToken': 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.',
+    'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var, which also enables MCP Bearer auth on gitnexus serve's /api/mcp route. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.",
     'help.option.force.confirmation': 'Skip confirmation prompt',
     'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',

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

@@ -8,6 +8,13 @@ export declare const cliResources: {
         readonly 'common.storage': "Storage";
         readonly 'common.deleted': "Deleted: {{target}}";
         readonly 'common.error': "Error: {{message}}";
+        readonly 'update.available': "GitNexus {{latestVersion}} is available (you are running {{installedVersion}}).";
+        readonly 'update.current': "GitNexus {{installedVersion}} is current or newer than the latest stable version.";
+        readonly 'update.installing': "Installing with {{command}}…";
+        readonly 'update.installed': "Installed gitnexus@{{version}}. Restart long-running mcp/serve processes.";
+        readonly 'update.installFailed': "npm install failed. You can retry: {{command}}";
+        readonly 'update.installError': "Could not run npm: {{message}}";
+        readonly 'update.checkFailed': "Could not check for updates (offline, private registry, or the check failed open).";
         readonly 'list.title': "Indexed Repositories ({{count}})";
         readonly 'list.indexed': "Indexed";
         readonly 'list.commit': "Commit";
@@ -67,6 +74,7 @@ export declare const cliResources: {
         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.noOverlappingSymbols': "Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.";
         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.";
@@ -125,6 +133,11 @@ export declare const cliResources: {
         readonly 'help.option.version': "output the version number";
         readonly 'help.command.setup.description': "One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex";
         readonly 'help.command.uninstall.description': "Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors";
+        readonly 'help.command.autoSync.description': "Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml";
+        readonly 'help.autoSync.details': "\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.";
+        readonly 'help.command.watch.description': "Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes";
+        readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
+        readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
         readonly 'help.command.analyze.description': "Index a repository (full analysis)";
         readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
         readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
@@ -132,6 +145,7 @@ export declare const cliResources: {
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+        readonly 'help.command.update.description': "Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).";
         readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
         readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
         readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
@@ -158,12 +172,13 @@ export declare const cliResources: {
         readonly 'help.command.group.query.description': "Search execution flows across all repos in a group";
         readonly 'help.command.group.contracts.description': "Inspect Contract Registry";
         readonly 'help.option.setup.codingAgent': "Configure only these coding agents (comma-separated or repeatable)";
-        readonly 'help.option.analyze.force': "Force full re-index even if up to date";
+        readonly 'help.option.analyze.force': "Force graph and FTS rebuild; unchanged parser output may be reused";
+        readonly 'help.option.analyze.noParseCache': "Re-parse every source file instead of replaying cached parser output";
         readonly 'help.option.analyze.repairFts': "Repair/rebuild search FTS indexes without full re-analysis";
         readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
         readonly 'help.option.analyze.dropEmbeddings': "Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.";
         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.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.";
         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.";
@@ -188,7 +203,7 @@ export declare const cliResources: {
         readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
         readonly 'help.option.mcp.http': "Serve MCP over HTTP instead of stdio (for remote clients)";
         readonly 'help.option.mcp.host': "HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.";
-        readonly 'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
+        readonly 'help.option.mcp.authToken': "Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var, which also enables MCP Bearer auth on gitnexus serve's /api/mcp route. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
         readonly 'help.option.force.confirmation': "Skip confirmation prompt";
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
@@ -272,6 +287,13 @@ export declare const cliResources: {
         'common.storage': string;
         'common.deleted': string;
         'common.error': string;
+        'update.available': string;
+        'update.current': string;
+        'update.installing': string;
+        'update.installed': string;
+        'update.installFailed': string;
+        'update.installError': string;
+        'update.checkFailed': string;
         'list.title': string;
         'list.indexed': string;
         'list.commit': string;
@@ -331,6 +353,7 @@ export declare const cliResources: {
         'tool.usage.cypher': string;
         'tool.warn.unknownKind': string;
         'tool.detectChanges.noChanges': string;
+        'tool.detectChanges.noOverlappingSymbols': string;
         'tool.detectChanges.partial': string;
         'tool.detectChanges.truncated': string;
         'tool.detectChanges.truncatedDegraded': string;
@@ -389,6 +412,11 @@ export declare const cliResources: {
         'help.option.version': string;
         'help.command.setup.description': string;
         'help.command.uninstall.description': string;
+        'help.command.autoSync.description': string;
+        'help.autoSync.details': string;
+        'help.command.watch.description': string;
+        'help.watch.details': string;
+        'error.watch.ambiguous': string;
         'help.command.analyze.description': string;
         'help.command.index.description': string;
         'help.command.serve.description': string;
@@ -396,6 +424,7 @@ export declare const cliResources: {
         'help.command.list.description': string;
         'help.command.status.description': string;
         'help.command.doctor.description': string;
+        'help.command.update.description': string;
         'help.command.embeddings.description': string;
         'help.command.embeddings.install.description': string;
         'help.command.clean.description': string;
@@ -423,6 +452,7 @@ export declare const cliResources: {
         'help.command.group.contracts.description': string;
         'help.option.setup.codingAgent': string;
         'help.option.analyze.force': string;
+        'help.option.analyze.noParseCache': string;
         'help.option.analyze.repairFts': string;
         'help.option.analyze.embeddings': string;
         'help.option.analyze.dropEmbeddings': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -7,6 +7,13 @@ export declare const zhCN: {
     'common.storage': string;
     'common.deleted': string;
     'common.error': string;
+    'update.available': string;
+    'update.current': string;
+    'update.installing': string;
+    'update.installed': string;
+    'update.installFailed': string;
+    'update.installError': string;
+    'update.checkFailed': string;
     'list.title': string;
     'list.indexed': string;
     'list.commit': string;
@@ -66,6 +73,7 @@ export declare const zhCN: {
     'tool.usage.cypher': string;
     'tool.warn.unknownKind': string;
     'tool.detectChanges.noChanges': string;
+    'tool.detectChanges.noOverlappingSymbols': string;
     'tool.detectChanges.partial': string;
     'tool.detectChanges.truncated': string;
     'tool.detectChanges.truncatedDegraded': string;
@@ -124,6 +132,11 @@ export declare const zhCN: {
     'help.option.version': string;
     'help.command.setup.description': string;
     'help.command.uninstall.description': string;
+    'help.command.autoSync.description': string;
+    'help.autoSync.details': string;
+    'help.command.watch.description': string;
+    'help.watch.details': string;
+    'error.watch.ambiguous': string;
     'help.command.analyze.description': string;
     'help.command.index.description': string;
     'help.command.serve.description': string;
@@ -131,6 +144,7 @@ export declare const zhCN: {
     'help.command.list.description': string;
     'help.command.status.description': string;
     'help.command.doctor.description': string;
+    'help.command.update.description': string;
     'help.command.embeddings.description': string;
     'help.command.embeddings.install.description': string;
     'help.command.clean.description': string;
@@ -158,6 +172,7 @@ export declare const zhCN: {
     'help.command.group.contracts.description': string;
     'help.option.setup.codingAgent': string;
     'help.option.analyze.force': string;
+    'help.option.analyze.noParseCache': string;
     'help.option.analyze.repairFts': string;
     'help.option.analyze.embeddings': string;
     'help.option.analyze.dropEmbeddings': string;

package/dist/cli/i18n/zh-CN.js

@@ -7,6 +7,13 @@ export const zhCN = {
     'common.storage': '存储',
     'common.deleted': '已删除：{{target}}',
     'common.error': '错误：{{message}}',
+    'update.available': 'GitNexus {{latestVersion}} 已发布（当前运行 {{installedVersion}}）。',
+    'update.current': 'GitNexus {{installedVersion}} 已是最新稳定版或不低于该版本。',
+    'update.installing': '正在执行 {{command}}…',
+    'update.installed': '已安装 gitnexus@{{version}}。请重启仍在运行的 mcp/serve 进程。',
+    'update.installFailed': 'npm 安装失败。可重试：{{command}}',
+    'update.installError': '无法运行 npm：{{message}}',
+    'update.checkFailed': '无法检查更新（离线、私有仓库，或检查失败）。',
     'list.title': '已索引仓库（{{count}}）',
     'list.indexed': '索引时间',
     'list.commit': '提交',
@@ -66,6 +73,7 @@ export const zhCN = {
     'tool.usage.cypher': '用法：gitnexus cypher <Cypher 查询>',
     'tool.warn.unknownKind': "--kind '{{kind}}' 不是已知的符号类型（如 Function、Class、Method），不会用于缩小结果范围。",
     'tool.detectChanges.noChanges': '未检测到变更。',
+    'tool.detectChanges.noOverlappingSymbols': 'diff 触及 {{files}} 个文件，但没有索引符号与这些 hunk 重叠 — 并非干净工作区。',
     'tool.detectChanges.partial': '结果不完整：图查询失败，可能遗漏已变更符号。请勿将其视为通过的提交前检查。',
     'tool.detectChanges.truncated': '列表已截断：已变更符号列表被截断，未列出全部变更符号。计数与风险等级仍涵盖全部符号。',
     'tool.detectChanges.truncatedDegraded': '列表已截断：已变更符号列表被截断。本次运行同时不完整，因此计数为下限而非总数。',
@@ -124,6 +132,11 @@ export const zhCN = {
     'help.option.version': '输出版本号',
     'help.command.setup.description': '一次性设置：为 Cursor、Claude Code、Antigravity、OpenCode、CodeBuddy、Qoder、Codex 配置 MCP',
     'help.command.uninstall.description': '撤销 `setup`：从所有检测到的编辑器中移除 GitNexus 的 MCP 配置、技能和钩子',
+    'help.command.autoSync.description': '控制基于 GITNEXUS_HOME/watch_config.yml 的定时 clone/pull 和分析',
+    'help.autoSync.details': '\n操作：init、start（默认）、restart、stop、status、reset\n配置：GITNEXUS_HOME/watch_config.yml\n运行时文件：GITNEXUS_HOME/watch/watch.pid、watch.mutex、watch.owner.json、watch.status.json、auto-sync-state.json\n恢复：已验证 owner 退出的 mutex 会自动回收；无效或旧版 mutex 会安全拒绝，确认没有 watch 进程运行后再手动删除。\n写入：GITNEXUS_HOME/watch/project_commit_info.txt\n远程地址：仅允许 github.com、gitlab.com 和 gitee.com 上的 SSH 地址。\n启动后立即运行一次，之后按 sync_interval_minutes 重复。',
+    'help.command.watch.description': '含义不明确：本地文件请用 `analyze --watch`，定时远程同步请用 `auto-sync`',
+    'help.watch.details': '\n`gitnexus watch` 不会启动监视器。\n  本地工作区增量索引：gitnexus analyze --watch\n  定时远程 clone/pull 并分析：gitnexus auto-sync start\n',
+    'error.watch.ambiguous': '`gitnexus watch` 含义不明确。\n  本地工作区增量索引：gitnexus analyze --watch\n  定时远程 clone/pull 并分析：gitnexus auto-sync start\n',
     'help.command.analyze.description': '索引仓库（完整分析）',
     'help.command.index.description': '将现有 .gitnexus/ 文件夹注册到全局注册表（无需重新分析）',
     'help.command.serve.description': '启动供 Web UI 连接的本地 HTTP 服务器',
@@ -131,6 +144,7 @@ export const zhCN = {
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
+    'help.command.update.description': '通过 npm 全局安装最新发布的 GitNexus（`npm i -g gitnexus@<x.y.z>`）。',
     'help.command.embeddings.description': '管理按需安装的本地嵌入运行时',
     'help.command.embeddings.install.description': '按需安装本地嵌入组件（@huggingface/transformers + onnxruntime-node）。修复 npm 跳过可选包的安装（例如在 HTTP 代理后，#2370）。仅从你配置的 npm registry 下载 — 镜像和代理均生效。',
     'help.command.clean.description': '删除当前仓库的 GitNexus 索引',
@@ -157,12 +171,13 @@ export const zhCN = {
     'help.command.group.query.description': '跨仓库组所有仓库搜索执行流程',
     'help.command.group.contracts.description': '查看 Contract Registry',
     'help.option.setup.codingAgent': '仅配置这些编码代理（逗号分隔或重复传入）',
-    'help.option.analyze.force': '即使已是最新也强制完整重建索引',
+    'help.option.analyze.force': '强制重建图和 FTS；未更改的解析器输出可能被复用',
+    'help.option.analyze.noParseCache': '重新解析每个源文件，不重放缓存的解析器输出',
     'help.option.analyze.repairFts': '修复/重建搜索 FTS 索引，不执行完整重新分析',
     'help.option.analyze.embeddings': '启用语义搜索的嵌入生成（默认关闭）。可选 [limit] 覆盖 50,000 节点安全上限；传 0 可完全禁用上限。',
     'help.option.analyze.dropEmbeddings': '重建时删除现有嵌入。默认情况下，未传 `--embeddings` 的 `analyze` 会保留索引中已有嵌入。',
     'help.option.analyze.skills': '根据检测到的社区生成仓库专属 skill 文件（同时设置 --index-only 时无效）。',
-    'help.option.analyze.skipAgentsMd': '跳过更新 AGENTS.md 和 CLAUDE.md 中的 gitnexus 区块',
+    'help.option.analyze.skipAgentsMd': '跳过更新 AGENTS.md 和 CLAUDE.md 中的 gitnexus 区块。不会跳过 .claude/skills 或 .agents/skills 下的标准 skill；如需跳过那些请使用 --skip-skills。--skills 生成的社区 skill 不受影响。',
     'help.option.analyze.noStats': '从 AGENTS.md 和 CLAUDE.md 中省略易变的文件/符号计数',
     'help.option.analyze.selfCommit': '在 analyze 后自动提交 AGENTS.md/CLAUDE.md 的变更（默认关闭，需显式开启）。仅限这两个文件（绝不使用 `git add -A`）；若两者均不存在、均未变更，或仓库未配置 git 身份，则不执行任何操作。',
     'help.option.analyze.skipSkills': '跳过直接安装在 .claude/skills/ 和 .agents/skills/ 下的标准 GitNexus skill 文件。不抑制 --skills 生成的社区 skill（位于 .claude/skills/gitnexus-area-*）。使用 --index-only 可跳过所有 AI 上下文文件注入。',
@@ -187,7 +202,7 @@ export const zhCN = {
     'help.option.serve.host': '绑定地址（默认：127.0.0.1；远程访问可用 0.0.0.0）',
     'help.option.mcp.http': '使用 HTTP 代替 stdio 提供 MCP 服务（适合远程客户端）',
     'help.option.mcp.host': 'HTTP 绑定地址（仅与 --http 搭配使用）。默认：127.0.0.1（回环）。使用 0.0.0.0 向所有接口开放。',
-    'help.option.mcp.authToken': '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置。非回环绑定（--host 0.0.0.0/::）时必填，否则拒绝启动。',
+    'help.option.mcp.authToken': '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置，该变量同时为 gitnexus serve 的 /api/mcp 路由启用 MCP Bearer 认证。非回环绑定（--host 0.0.0.0/::）时必填，否则拒绝启动。',
     'help.option.force.confirmation': '跳过确认提示',
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',