@veewo/gitnexus 1.4.6-rc → 1.4.8-rc

package/README.md

@@ -18,13 +18,17 @@ AI coding tools don't understand your codebase structure. They edit a function w
 ## Quick Start
 
 ```bash
+# Optional: pin one version for the whole session (example RC)
+# export GITNEXUS_CLI_SPEC="@veewo/gitnexus@1.4.7-rc"
+GITNEXUS_CLI_SPEC="${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}"
+
 # Index your repo (run from repo root)
-npx -y @veewo/gitnexus@latest analyze
+npx -y "${GITNEXUS_CLI_SPEC}" analyze
 ```
 
 That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-To configure MCP for your editor, run `npx -y @veewo/gitnexus@latest setup` once — or set it up manually below.
+To configure MCP for your editor, run `npx -y "${GITNEXUS_CLI_SPEC}" setup --cli-spec "$GITNEXUS_CLI_SPEC"` once — or set it up manually below.
 
 `gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
 
@@ -52,7 +56,7 @@ If you prefer to configure manually instead of using `gitnexus setup`:
 ### Claude Code (full support — MCP + skills + hooks)
 
 ```bash
-claude mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
+claude mcp add gitnexus -- npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" mcp
 ```
 
 ### Cursor / Windsurf
@@ -137,10 +141,10 @@ Your AI agent gets these tools automatically:
 
 ```bash
 gitnexus setup                    # Configure MCP for your editors (one-time)
-npx -y @veewo/gitnexus@latest analyze [path]           # Index a repository (or update stale index)
-npx -y @veewo/gitnexus@latest analyze --force          # Force full re-index
-npx -y @veewo/gitnexus@latest analyze --embeddings     # Enable embedding generation (slower, better search)
-npx -y @veewo/gitnexus@latest analyze --verbose        # Log skipped files when parsers are unavailable
+npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze [path]           # Index a repository (or update stale index)
+npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze --force          # Force full re-index
+npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze --embeddings     # Enable embedding generation (slower, better search)
+npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze --verbose        # Log skipped files when parsers are unavailable
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus list                    # List all indexed repositories
@@ -153,7 +157,7 @@ gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-m
 
 ## Multi-Repo Support
 
-GitNexus supports indexing multiple repositories. Each `npx -y @veewo/gitnexus@latest analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
+GitNexus supports indexing multiple repositories. Each `npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
 
 ## Supported Languages
 
@@ -188,7 +192,7 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Impact Analysis** — Analyze blast radius before changes
 - **Refactoring** — Plan safe refactors using dependency mapping
 
-Installed automatically by both `npx -y @veewo/gitnexus@latest analyze` (per-repo) and `gitnexus setup` (global).
+Installed automatically by both `npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze` (per-repo) and `gitnexus setup` (global).
 
 ## Requirements
 

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

@@ -20,6 +20,7 @@ interface RepoStats {
  */
 export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats, options?: {
     skillScope?: SkillScope;
+    cliPackageSpec?: string;
 }, generatedSkills?: GeneratedSkillInfo[]): Promise<{
     files: string[];
 }>;

package/dist/cli/ai-context.js

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { buildNpxCommand, resolveCliSpec } from '../config/cli-spec.js';
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -24,13 +25,14 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * - Exact tool commands with parameters — vague directives get ignored
  * - Self-review checklist — forces model to verify its own work
  */
-function generateGitNexusContent(projectName, stats, skillScope, generatedSkills) {
+function generateGitNexusContent(projectName, stats, skillScope, cliPackageSpec, generatedSkills) {
     const skillRoot = skillScope === 'global'
         ? '~/.agents/skills/gitnexus'
         : '.agents/skills/gitnexus';
     const generatedRows = (generatedSkills && generatedSkills.length > 0)
         ? `\n${generatedSkills.map((s) => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`).join('\n')}`
         : '';
+    const reindexCmd = buildNpxCommand(cliPackageSpec, 'analyze');
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
@@ -42,7 +44,7 @@ This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} s
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, ask user whether to rebuild index via \`npx -y @veewo/gitnexus@latest analyze\` first (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
+> If step 1 warns the index is stale, ask user whether to rebuild index via \`gitnexus analyze\` when local CLI exists; otherwise run \`${reindexCmd}\` (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
 
 ## Skills
 
@@ -173,7 +175,8 @@ Use GitNexus tools to accomplish this task.
  */
 export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, options, generatedSkills) {
     const skillScope = options?.skillScope === 'global' ? 'global' : 'project';
-    const content = generateGitNexusContent(projectName, stats, skillScope, generatedSkills);
+    const cliPackageSpec = options?.cliPackageSpec || resolveCliSpec().packageSpec;
+    const content = generateGitNexusContent(projectName, stats, skillScope, cliPackageSpec, generatedSkills);
     const createdFiles = [];
     // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Codex, Cline, etc.)
     const agentsPath = path.join(repoPath, 'AGENTS.md');

package/dist/cli/analyze.js

@@ -22,6 +22,7 @@ import { resolveEffectiveAnalyzeOptions } from './analyze-options.js';
 import { formatFallbackSummary, formatUnityDiagnosticsSummary } from './analyze-summary.js';
 import { resolveChildProcessExit } from './exit-code.js';
 import { toPipelineRuntimeSummary } from './analyze-runtime-summary.js';
+import { resolveCliSpec } from '../config/cli-spec.js';
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
 /** Re-exec the process with an 8GB heap if we're currently below that. */
@@ -98,6 +99,14 @@ export const analyzeCommand = async (inputPath, options) => {
     }
     const currentCommit = getCurrentCommit(repoPath);
     const existingMeta = await loadMeta(storagePath);
+    let hasLbugIndex = false;
+    try {
+        await fs.stat(lbugPath);
+        hasLbugIndex = true;
+    }
+    catch {
+        hasLbugIndex = false;
+    }
     let includeExtensions = [];
     let scopeRules = [];
     let repoAlias;
@@ -121,7 +130,10 @@ export const analyzeCommand = async (inputPath, options) => {
         process.exitCode = 1;
         return;
     }
-    if (existingMeta && !options?.force && existingMeta.lastCommit === currentCommit && !options?.skills) {
+    if (existingMeta && !hasLbugIndex && !options?.force) {
+        console.log('  Existing metadata found, but LadybugDB index file is missing — rebuilding index...\n');
+    }
+    if (existingMeta && hasLbugIndex && !options?.force && existingMeta.lastCommit === currentCommit && !options?.skills) {
         const hasScopePrefixInput = Array.isArray(options?.scopePrefix)
             ? options.scopePrefix.length > 0
             : Boolean(options?.scopePrefix);
@@ -368,6 +380,7 @@ export const analyzeCommand = async (inputPath, options) => {
         const skillResult = await generateSkillFiles(repoPath, projectName, pipelineForSkills);
         generatedSkills = skillResult.skills;
     }
+    const cliConfig = await loadCLIConfig();
     const aiContext = await generateAIContextFiles(repoPath, storagePath, projectName, {
         files: pipelineRuntime.totalFileCount,
         nodes: stats.nodes,
@@ -376,7 +389,8 @@ export const analyzeCommand = async (inputPath, options) => {
         clusters: aggregatedClusterCount,
         processes: pipelineRuntime.processResult?.stats.totalProcesses,
     }, {
-        skillScope: ((await loadCLIConfig()).setupScope === 'global') ? 'global' : 'project',
+        skillScope: (cliConfig.setupScope === 'global') ? 'global' : 'project',
+        cliPackageSpec: resolveCliSpec({ config: cliConfig }).packageSpec,
     }, generatedSkills);
     await closeLbug();
     // Note: we intentionally do NOT call disposeEmbedder() here.

package/dist/cli/index.js

@@ -17,6 +17,8 @@ program
     .description('One-time setup: configure MCP for a selected coding agent (claude/opencode/codex)')
     .option('--scope <scope>', 'Install target: global (default) or project')
     .option('--agent <agent>', 'Target coding agent: claude, opencode, or codex')
+    .option('--cli-version <version>', 'Pin npx GitNexus version/tag for generated MCP commands (e.g. 1.4.7-rc)')
+    .option('--cli-spec <spec>', 'Pin full npx package spec for generated MCP commands (e.g. @veewo/gitnexus@1.4.7-rc)')
     .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program
     .command('analyze [path]')

package/dist/cli/setup.d.ts

@@ -8,6 +8,8 @@
 interface SetupOptions {
     scope?: string;
     agent?: string;
+    cliVersion?: string;
+    cliSpec?: string;
 }
 export declare const setupCommand: (options?: SetupOptions) => Promise<void>;
 export {};

package/dist/cli/setup.js

@@ -6,7 +6,6 @@
  * in either global or project scope.
  */
 import fs from 'fs/promises';
-import { readFileSync } from 'node:fs';
 import path from 'path';
 import os from 'os';
 import { execFile } from 'node:child_process';
@@ -15,10 +14,10 @@ import { fileURLToPath } from 'url';
 import { getGlobalDir, loadCLIConfig, saveCLIConfig } from '../storage/repo-manager.js';
 import { getGitRoot } from '../storage/git.js';
 import { glob } from 'glob';
+import { buildNpxCommand, resolveCliSpec } from '../config/cli-spec.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
-const FALLBACK_MCP_PACKAGE = '@veewo/gitnexus@latest';
 const LEGACY_CURSOR_AGENT = 'cursor';
 function resolveSetupScope(rawScope) {
     if (!rawScope || rawScope.trim() === '')
@@ -48,43 +47,25 @@ async function installLegacyCursorSkills(result) {
         result.errors.push(`Cursor skills: ${err.message}`);
     }
 }
-/**
- * Resolve the package spec used by MCP commands.
- * Defaults to @veewo/gitnexus@latest when package metadata is unavailable.
- */
-function resolveMcpPackageSpec() {
-    try {
-        const packageJsonPath = path.join(__dirname, '..', '..', 'package.json');
-        const raw = readFileSync(packageJsonPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.name === 'string' && parsed.name.trim().length > 0) {
-            return `${parsed.name}@latest`;
-        }
-    }
-    catch {
-        // Fallback keeps behavior for unusual runtimes.
-    }
-    return FALLBACK_MCP_PACKAGE;
-}
-const MCP_PACKAGE_SPEC = resolveMcpPackageSpec();
+const DEFAULT_MCP_PACKAGE_SPEC = resolveCliSpec().packageSpec;
 /**
  * The MCP server entry for all editors.
  * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
  */
-function getMcpEntry() {
+function getMcpEntry(mcpPackageSpec) {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', MCP_PACKAGE_SPEC, 'mcp'],
+            args: ['/c', 'npx', '-y', mcpPackageSpec, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', MCP_PACKAGE_SPEC, 'mcp'],
+        args: ['-y', mcpPackageSpec, 'mcp'],
     };
 }
-function getOpenCodeMcpEntry() {
-    const entry = getMcpEntry();
+function getOpenCodeMcpEntry(mcpPackageSpec) {
+    const entry = getMcpEntry(mcpPackageSpec);
     return {
         type: 'local',
         command: [entry.command, ...entry.args],
@@ -94,28 +75,28 @@ function getOpenCodeMcpEntry() {
  * Merge gitnexus entry into an existing MCP config JSON object.
  * Returns the updated config.
  */
-function mergeMcpConfig(existing) {
+function mergeMcpConfig(existing, mcpPackageSpec) {
     if (!existing || typeof existing !== 'object') {
         existing = {};
     }
     if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
         existing.mcpServers = {};
     }
-    existing.mcpServers.gitnexus = getMcpEntry();
+    existing.mcpServers.gitnexus = getMcpEntry(mcpPackageSpec);
     return existing;
 }
 /**
  * Merge gitnexus entry into an OpenCode config JSON object.
  * Returns the updated config.
  */
-function mergeOpenCodeConfig(existing) {
+function mergeOpenCodeConfig(existing, mcpPackageSpec) {
     if (!existing || typeof existing !== 'object') {
         existing = {};
     }
     if (!existing.mcp || typeof existing.mcp !== 'object') {
         existing.mcp = {};
     }
-    existing.mcp.gitnexus = getOpenCodeMcpEntry();
+    existing.mcp.gitnexus = getOpenCodeMcpEntry(mcpPackageSpec);
     return existing;
 }
 /**
@@ -167,16 +148,16 @@ async function fileExists(filePath) {
 function toTomlString(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
-function buildCodexMcpTable() {
-    const entry = getMcpEntry();
+function buildCodexMcpTable(mcpPackageSpec) {
+    const entry = getMcpEntry(mcpPackageSpec);
     return [
         '[mcp_servers.gitnexus]',
         `command = ${toTomlString(entry.command)}`,
         `args = [${entry.args.map(toTomlString).join(', ')}]`,
     ].join('\n');
 }
-function mergeCodexConfig(existingRaw) {
-    const table = buildCodexMcpTable();
+function mergeCodexConfig(existingRaw, mcpPackageSpec) {
+    const table = buildCodexMcpTable(mcpPackageSpec);
     const normalized = existingRaw.replace(/\r\n/g, '\n');
     const tablePattern = /^\[mcp_servers\.gitnexus\][\s\S]*?(?=^\[[^\]]+\]|(?![\s\S]))/m;
     if (tablePattern.test(normalized)) {
@@ -198,7 +179,7 @@ async function resolveOpenCodeConfigPath(opencodeDir) {
     return preferredPath;
 }
 // ─── Editor-specific setup ─────────────────────────────────────────
-async function setupCursor(result) {
+async function setupCursor(result, mcpPackageSpec) {
     const cursorDir = path.join(os.homedir(), '.cursor');
     if (!(await dirExists(cursorDir))) {
         result.skipped.push('Cursor (not installed)');
@@ -207,7 +188,7 @@ async function setupCursor(result) {
     const mcpPath = path.join(cursorDir, 'mcp.json');
     try {
         const existing = await readJsonFile(mcpPath);
-        const updated = mergeMcpConfig(existing);
+        const updated = mergeMcpConfig(existing, mcpPackageSpec);
         await writeJsonFile(mcpPath, updated);
         result.configured.push('Cursor');
     }
@@ -215,7 +196,7 @@ async function setupCursor(result) {
         result.errors.push(`Cursor: ${err.message}`);
     }
 }
-async function setupClaudeCode(result) {
+async function setupClaudeCode(result, mcpPackageSpec) {
     const claudeDir = path.join(os.homedir(), '.claude');
     const hasClaude = await dirExists(claudeDir);
     if (!hasClaude) {
@@ -226,7 +207,7 @@ async function setupClaudeCode(result) {
     console.log('');
     console.log('  Claude Code detected. Run this command to add GitNexus MCP:');
     console.log('');
-    console.log(`    claude mcp add gitnexus -- npx -y ${MCP_PACKAGE_SPEC} mcp`);
+    console.log(`    claude mcp add gitnexus -- ${buildNpxCommand(mcpPackageSpec, 'mcp')}`);
     console.log('');
     result.configured.push('Claude Code (MCP manual step printed)');
 }
@@ -262,7 +243,7 @@ async function installProjectAgentSkills(repoRoot, result) {
  * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
  * Merges hook config without overwriting existing hooks.
  */
-async function installClaudeCodeHooks(result) {
+async function installClaudeCodeHooks(result, mcpPackageSpec) {
     const claudeDir = path.join(os.homedir(), '.claude');
     if (!(await dirExists(claudeDir)))
         return;
@@ -283,6 +264,7 @@ async function installClaudeCodeHooks(result) {
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
             content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
+            content = content.replace("const DEFAULT_NPX_SPEC = '@veewo/gitnexus@latest';", `const DEFAULT_NPX_SPEC = ${JSON.stringify(mcpPackageSpec)};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {
@@ -314,7 +296,7 @@ async function installClaudeCodeHooks(result) {
         result.errors.push(`Claude Code hooks: ${err.message}`);
     }
 }
-async function setupOpenCode(result) {
+async function setupOpenCode(result, mcpPackageSpec) {
     const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
     if (!(await dirExists(opencodeDir))) {
         result.skipped.push('OpenCode (not installed)');
@@ -323,7 +305,7 @@ async function setupOpenCode(result) {
     const configPath = await resolveOpenCodeConfigPath(opencodeDir);
     try {
         const existing = await readJsonFile(configPath);
-        const config = mergeOpenCodeConfig(existing);
+        const config = mergeOpenCodeConfig(existing, mcpPackageSpec);
         await writeJsonFile(configPath, config);
         result.configured.push(`OpenCode (${path.basename(configPath)})`);
     }
@@ -331,8 +313,8 @@ async function setupOpenCode(result) {
         result.errors.push(`OpenCode: ${err.message}`);
     }
 }
-async function setupCodex(result) {
-    const entry = getMcpEntry();
+async function setupCodex(result, mcpPackageSpec) {
+    const entry = getMcpEntry(mcpPackageSpec);
     try {
         await execFileAsync('codex', ['mcp', 'add', 'gitnexus', '--', entry.command, ...entry.args], { timeout: 15000 });
         result.configured.push('Codex');
@@ -345,11 +327,11 @@ async function setupCodex(result) {
         result.errors.push(`Codex: ${err.message}`);
     }
 }
-async function setupProjectMcp(repoRoot, result) {
+async function setupProjectMcp(repoRoot, result, mcpPackageSpec) {
     const mcpPath = path.join(repoRoot, '.mcp.json');
     try {
         const existing = await readJsonFile(mcpPath);
-        const updated = mergeMcpConfig(existing);
+        const updated = mergeMcpConfig(existing, mcpPackageSpec);
         await writeJsonFile(mcpPath, updated);
         result.configured.push(`Project MCP (${path.relative(repoRoot, mcpPath)})`);
     }
@@ -357,7 +339,7 @@ async function setupProjectMcp(repoRoot, result) {
         result.errors.push(`Project MCP: ${err.message}`);
     }
 }
-async function setupProjectCodex(repoRoot, result) {
+async function setupProjectCodex(repoRoot, result, mcpPackageSpec) {
     const codexConfigPath = path.join(repoRoot, '.codex', 'config.toml');
     try {
         let existingRaw = '';
@@ -368,7 +350,7 @@ async function setupProjectCodex(repoRoot, result) {
             if (err?.code !== 'ENOENT')
                 throw err;
         }
-        const merged = mergeCodexConfig(existingRaw);
+        const merged = mergeCodexConfig(existingRaw, mcpPackageSpec);
         await fs.mkdir(path.dirname(codexConfigPath), { recursive: true });
         await fs.writeFile(codexConfigPath, merged, 'utf-8');
         result.configured.push(`Project Codex MCP (${path.relative(repoRoot, codexConfigPath)})`);
@@ -377,11 +359,11 @@ async function setupProjectCodex(repoRoot, result) {
         result.errors.push(`Project Codex MCP: ${err.message}`);
     }
 }
-async function setupProjectOpenCode(repoRoot, result) {
+async function setupProjectOpenCode(repoRoot, result, mcpPackageSpec) {
     const opencodePath = path.join(repoRoot, 'opencode.json');
     try {
         const existing = await readJsonFile(opencodePath);
-        const merged = mergeOpenCodeConfig(existing);
+        const merged = mergeOpenCodeConfig(existing, mcpPackageSpec);
         await writeJsonFile(opencodePath, merged);
         result.configured.push(`Project OpenCode MCP (${path.relative(repoRoot, opencodePath)})`);
     }
@@ -389,11 +371,28 @@ async function setupProjectOpenCode(repoRoot, result) {
         result.errors.push(`Project OpenCode MCP: ${err.message}`);
     }
 }
-async function saveSetupScope(scope, result) {
+function extractVersionFromPackageSpec(packageSpec) {
+    const trimmed = packageSpec.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith('@')) {
+        const at = trimmed.indexOf('@', 1);
+        return at > 0 ? trimmed.slice(at + 1) : undefined;
+    }
+    const at = trimmed.lastIndexOf('@');
+    return at > 0 ? trimmed.slice(at + 1) : undefined;
+}
+async function saveSetupConfig(scope, packageSpec, result) {
     try {
         const existing = await loadCLIConfig();
-        await saveCLIConfig({ ...existing, setupScope: scope });
+        await saveCLIConfig({
+            ...existing,
+            setupScope: scope,
+            cliPackageSpec: packageSpec,
+            cliVersion: extractVersionFromPackageSpec(packageSpec),
+        });
         result.configured.push(`Default setup scope (${scope})`);
+        result.configured.push(`CLI package spec (${packageSpec})`);
     }
     catch (err) {
         result.errors.push(`Persist setup scope: ${err.message}`);
@@ -477,6 +476,11 @@ export const setupCommand = async (options = {}) => {
     console.log('  GitNexus Setup');
     console.log('  ==============');
     console.log('');
+    if (options.cliSpec && options.cliVersion) {
+        console.log('  Use either --cli-spec or --cli-version, not both.\n');
+        process.exitCode = 1;
+        return;
+    }
     let scope;
     let agent;
     const legacyCursorMode = !options.agent || options.agent.trim() === '';
@@ -492,6 +496,13 @@ export const setupCommand = async (options = {}) => {
     // Ensure global directory exists
     const globalDir = getGlobalDir();
     await fs.mkdir(globalDir, { recursive: true });
+    const existingConfig = await loadCLIConfig();
+    const resolvedCliSpec = resolveCliSpec({
+        explicitSpec: options.cliSpec,
+        explicitVersion: options.cliVersion,
+        config: existingConfig,
+    });
+    const mcpPackageSpec = resolvedCliSpec.packageSpec || DEFAULT_MCP_PACKAGE_SPEC;
     const result = {
         configured: [],
         skipped: [],
@@ -499,27 +510,27 @@ export const setupCommand = async (options = {}) => {
     };
     if (scope === 'global') {
         if (legacyCursorMode) {
-            await setupCursor(result);
+            await setupCursor(result, mcpPackageSpec);
             await installLegacyCursorSkills(result);
-            await saveSetupScope(scope, result);
+            await saveSetupConfig(scope, mcpPackageSpec, result);
             agent = LEGACY_CURSOR_AGENT;
         }
         else {
             // Configure only the selected agent MCP
             if (agent === 'claude') {
-                await setupClaudeCode(result);
+                await setupClaudeCode(result, mcpPackageSpec);
                 // Claude-only hooks should only be installed when Claude is selected.
-                await installClaudeCodeHooks(result);
+                await installClaudeCodeHooks(result, mcpPackageSpec);
             }
             else if (agent === 'opencode') {
-                await setupOpenCode(result);
+                await setupOpenCode(result, mcpPackageSpec);
             }
             else if (agent === 'codex') {
-                await setupCodex(result);
+                await setupCodex(result, mcpPackageSpec);
             }
             // Install shared global skills once
             await installGlobalAgentSkills(result);
-            await saveSetupScope(scope, result);
+            await saveSetupConfig(scope, mcpPackageSpec, result);
         }
     }
     else {
@@ -530,16 +541,16 @@ export const setupCommand = async (options = {}) => {
             return;
         }
         if (agent === 'claude') {
-            await setupProjectMcp(repoRoot, result);
+            await setupProjectMcp(repoRoot, result, mcpPackageSpec);
         }
         else if (agent === 'codex') {
-            await setupProjectCodex(repoRoot, result);
+            await setupProjectCodex(repoRoot, result, mcpPackageSpec);
         }
         else if (agent === 'opencode') {
-            await setupProjectOpenCode(repoRoot, result);
+            await setupProjectOpenCode(repoRoot, result, mcpPackageSpec);
         }
         await installProjectAgentSkills(repoRoot, result);
-        await saveSetupScope(scope, result);
+        await saveSetupConfig(scope, mcpPackageSpec, result);
     }
     // Print results
     if (result.configured.length > 0) {
@@ -566,6 +577,7 @@ export const setupCommand = async (options = {}) => {
     console.log('  Summary:');
     console.log(`    Scope: ${scope}`);
     console.log(`    Agent: ${legacyCursorMode ? LEGACY_CURSOR_AGENT : agent}`);
+    console.log(`    CLI package spec: ${mcpPackageSpec}`);
     console.log(`    MCP configured for: ${result.configured.filter(c => !c.includes('skills')).join(', ') || 'none'}`);
     console.log(`    Skills installed to: ${result.configured.filter(c => c.includes('skills')).length > 0 ? result.configured.filter(c => c.includes('skills')).join(', ') : 'none'}`);
     console.log('');

package/dist/cli/setup.test.js

@@ -61,6 +61,26 @@ test('setup rejects invalid --agent', async () => {
         await fs.rm(fakeHome, { recursive: true, force: true });
     }
 });
+test('setup rejects using --cli-spec and --cli-version together', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        try {
+            await runSetup(['--agent', 'opencode', '--cli-spec', '@veewo/gitnexus@1.4.7-rc', '--cli-version', '1.4.7-rc'], {
+                ...process.env,
+                HOME: fakeHome,
+                USERPROFILE: fakeHome,
+            });
+            assert.fail('expected setup with conflicting CLI options to fail');
+        }
+        catch (err) {
+            assert.equal(typeof err?.stdout, 'string');
+            assert.match(err.stdout, /Use either --cli-spec or --cli-version/);
+        }
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
 test('setup installs global skills under ~/.agents/skills/gitnexus', async () => {
     const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
     try {
@@ -148,6 +168,30 @@ test('setup configures OpenCode MCP in ~/.config/opencode/opencode.json', async
         await fs.rm(fakeHome, { recursive: true, force: true });
     }
 });
+test('setup --cli-version pins MCP package spec and persists it in config', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    try {
+        const opencodeDir = path.join(fakeHome, '.config', 'opencode');
+        await fs.mkdir(opencodeDir, { recursive: true });
+        await runSetup(['--agent', 'opencode', '--cli-version', '1.4.7-rc'], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        });
+        const opencodeConfigPath = path.join(opencodeDir, 'opencode.json');
+        const opencodeRaw = await fs.readFile(opencodeConfigPath, 'utf-8');
+        const opencodeConfig = JSON.parse(opencodeRaw);
+        const configPath = path.join(fakeHome, '.gitnexus', 'config.json');
+        const savedConfigRaw = await fs.readFile(configPath, 'utf-8');
+        const savedConfig = JSON.parse(savedConfigRaw);
+        assert.deepEqual(opencodeConfig.mcp?.gitnexus?.command, ['npx', '-y', '@veewo/gitnexus@1.4.7-rc', 'mcp']);
+        assert.equal(savedConfig.cliPackageSpec, '@veewo/gitnexus@1.4.7-rc');
+        assert.equal(savedConfig.cliVersion, '1.4.7-rc');
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});
 test('setup keeps using legacy ~/.config/opencode/config.json when it already exists', async () => {
     const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
     try {

package/dist/cli/status.js

@@ -3,7 +3,7 @@
  *
  * Shows the indexing status of the current repository.
  */
-import { findRepo, getStoragePaths, hasKuzuIndex } from '../storage/repo-manager.js';
+import { findRepo, getStoragePaths, hasKuzuIndex, hasLbugIndex } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 export const statusCommand = async () => {
     const cwd = process.cwd();
@@ -28,6 +28,13 @@ export const statusCommand = async () => {
     }
     const currentCommit = getCurrentCommit(repo.repoPath);
     const isUpToDate = currentCommit === repo.meta.lastCommit;
+    const lbugReady = await hasLbugIndex(repo.storagePath);
+    if (!lbugReady) {
+        console.log(`Repository: ${repo.repoPath}`);
+        console.log('Status: ⚠️ index metadata exists but LadybugDB is missing');
+        console.log('Run: gitnexus analyze --force');
+        return;
+    }
     console.log(`Repository: ${repo.repoPath}`);
     console.log(`Indexed: ${new Date(repo.meta.indexedAt).toLocaleString()}`);
     console.log(`Indexed commit: ${repo.meta.lastCommit?.slice(0, 7)}`);

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

@@ -0,0 +1,29 @@
+export declare const DEFAULT_GITNEXUS_PACKAGE_NAME = "@veewo/gitnexus";
+export declare const DEFAULT_GITNEXUS_DIST_TAG = "latest";
+export declare const CLI_SPEC_ENV_KEY = "GITNEXUS_CLI_SPEC";
+export declare const CLI_VERSION_ENV_KEY = "GITNEXUS_CLI_VERSION";
+type CliSpecSource = 'explicit-spec' | 'explicit-version' | 'env-spec' | 'env-version' | 'config-spec' | 'config-version' | 'default';
+export interface CliSpecConfigLike {
+    cliPackageSpec?: string;
+    cliVersion?: string;
+}
+export interface ResolveCliSpecInput {
+    packageName?: string;
+    explicitSpec?: string;
+    explicitVersion?: string;
+    config?: CliSpecConfigLike;
+    env?: NodeJS.ProcessEnv;
+    defaultDistTag?: string;
+}
+export interface ResolvedCliSpec {
+    packageName: string;
+    packageSpec: string;
+    source: CliSpecSource;
+}
+/**
+ * Resolve package name from package.json with fallback for unusual runtimes.
+ */
+export declare function resolveGitNexusPackageName(): string;
+export declare function resolveCliSpec(input?: ResolveCliSpecInput): ResolvedCliSpec;
+export declare function buildNpxCommand(packageSpec: string, subcommand: string): string;
+export {};

package/dist/config/cli-spec.js

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const DEFAULT_GITNEXUS_PACKAGE_NAME = '@veewo/gitnexus';
+export const DEFAULT_GITNEXUS_DIST_TAG = 'latest';
+export const CLI_SPEC_ENV_KEY = 'GITNEXUS_CLI_SPEC';
+export const CLI_VERSION_ENV_KEY = 'GITNEXUS_CLI_VERSION';
+let cachedPackageName = null;
+/**
+ * Resolve package name from package.json with fallback for unusual runtimes.
+ */
+export function resolveGitNexusPackageName() {
+    if (cachedPackageName)
+        return cachedPackageName;
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
+        const raw = readFileSync(packageJsonPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const trimmed = typeof parsed.name === 'string' ? parsed.name.trim() : '';
+        cachedPackageName = trimmed || DEFAULT_GITNEXUS_PACKAGE_NAME;
+    }
+    catch {
+        cachedPackageName = DEFAULT_GITNEXUS_PACKAGE_NAME;
+    }
+    return cachedPackageName;
+}
+function hasPinnedVersion(packageSpec) {
+    const trimmed = packageSpec.trim();
+    if (!trimmed)
+        return false;
+    if (trimmed.startsWith('@')) {
+        return trimmed.indexOf('@', 1) !== -1;
+    }
+    return trimmed.includes('@');
+}
+function looksLikePackageSpec(token) {
+    if (!token)
+        return false;
+    if (token.startsWith('@'))
+        return true;
+    if (token.includes('/'))
+        return true;
+    return token.includes('@');
+}
+function normalizePackageSpec(packageName, raw, defaultDistTag) {
+    const token = raw.trim();
+    if (!token)
+        return `${packageName}@${defaultDistTag}`;
+    if (looksLikePackageSpec(token)) {
+        return hasPinnedVersion(token) ? token : `${token}@${defaultDistTag}`;
+    }
+    return `${packageName}@${token}`;
+}
+export function resolveCliSpec(input = {}) {
+    const packageName = (input.packageName || resolveGitNexusPackageName()).trim() || DEFAULT_GITNEXUS_PACKAGE_NAME;
+    const env = input.env || process.env;
+    const config = input.config || {};
+    const defaultDistTag = (input.defaultDistTag || DEFAULT_GITNEXUS_DIST_TAG).trim() || DEFAULT_GITNEXUS_DIST_TAG;
+    const candidates = [
+        { value: input.explicitSpec, source: 'explicit-spec' },
+        { value: input.explicitVersion, source: 'explicit-version' },
+        { value: env[CLI_SPEC_ENV_KEY], source: 'env-spec' },
+        { value: env[CLI_VERSION_ENV_KEY], source: 'env-version' },
+        { value: config.cliPackageSpec, source: 'config-spec' },
+        { value: config.cliVersion, source: 'config-version' },
+    ];
+    for (const candidate of candidates) {
+        const trimmed = (candidate.value || '').trim();
+        if (!trimmed)
+            continue;
+        return {
+            packageName,
+            packageSpec: normalizePackageSpec(packageName, trimmed, defaultDistTag),
+            source: candidate.source,
+        };
+    }
+    return {
+        packageName,
+        packageSpec: `${packageName}@${defaultDistTag}`,
+        source: 'default',
+    };
+}
+export function buildNpxCommand(packageSpec, subcommand) {
+    return `npx -y ${packageSpec} ${subcommand}`.trim();
+}

package/dist/mcp/resources.js

@@ -5,6 +5,8 @@
  * All resources use repo-scoped URIs: gitnexus://repo/{name}/context
  */
 import { checkStaleness } from './staleness.js';
+import { loadCLIConfig } from '../storage/repo-manager.js';
+import { buildNpxCommand, resolveCliSpec } from '../config/cli-spec.js';
 /**
  * Static resources — includes per-repo resources and the global repos list
  */
@@ -121,6 +123,11 @@ export async function readResource(uri, backend) {
             throw new Error(`Unknown resource: ${uri}`);
     }
 }
+async function resolveAnalyzeNpxCommand() {
+    const config = await loadCLIConfig();
+    const packageSpec = resolveCliSpec({ config }).packageSpec;
+    return buildNpxCommand(packageSpec, 'analyze');
+}
 // ─── Resource Implementations ─────────────────────────────────────────
 /**
  * Repos resource — list all indexed repositories
@@ -186,7 +193,8 @@ async function getContextResource(backend, repoName) {
     lines.push('  - cypher: Raw graph queries');
     lines.push('  - list_repos: Discover all indexed repositories');
     lines.push('');
-    lines.push('re_index: If data is stale, ask user whether to run `npx -y @veewo/gitnexus@latest analyze` (reuses previous analyze scope/options unless `--no-reuse-options` is passed). If user declines, clearly state retrieval may not reflect current code. For build/analyze/test commands, use 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently switch to glob/grep fallback.');
+    const analyzeCmd = await resolveAnalyzeNpxCommand();
+    lines.push(`re_index: If data is stale, ask user whether to run \`gitnexus analyze\` when local CLI exists; otherwise run \`${analyzeCmd}\` (reuses previous analyze scope/options unless \`--no-reuse-options\` is passed). If user declines, clearly state retrieval may not reflect current code. For build/analyze/test commands, use 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently switch to glob/grep fallback.`);
     lines.push('');
     lines.push('resources_available:');
     lines.push('  - gitnexus://repos: All indexed repositories');
@@ -371,8 +379,9 @@ async function getProcessDetailResource(name, backend, repoName) {
  */
 async function getSetupResource(backend) {
     const repos = await backend.listRepos();
+    const analyzeCmd = await resolveAnalyzeNpxCommand();
     if (repos.length === 0) {
-        return '# GitNexus\n\nNo repositories indexed. Run: `npx -y @veewo/gitnexus@latest analyze` in a repository.';
+        return `# GitNexus\n\nNo repositories indexed. Run: \`gitnexus analyze\` when local CLI exists; otherwise \`${analyzeCmd}\` in a repository.`;
     }
     const sections = [];
     for (const repo of repos) {

package/dist/storage/repo-manager.d.ts

@@ -64,6 +64,10 @@ export declare const getStoragePaths: (repoPath: string) => {
  * Non-destructive — safe to call from status commands.
  */
 export declare const hasKuzuIndex: (storagePath: string) => Promise<boolean>;
+/**
+ * Check whether a LadybugDB index exists in the given storage path.
+ */
+export declare const hasLbugIndex: (storagePath: string) => Promise<boolean>;
 /**
  * Clean up stale KuzuDB files after migration to LadybugDB.
  *
@@ -135,6 +139,8 @@ export interface CLIConfig {
     model?: string;
     baseUrl?: string;
     setupScope?: 'global' | 'project';
+    cliPackageSpec?: string;
+    cliVersion?: string;
 }
 /**
  * Get the path to the global CLI config file

package/dist/storage/repo-manager.js

@@ -52,6 +52,18 @@ export const hasKuzuIndex = async (storagePath) => {
         return false;
     }
 };
+/**
+ * Check whether a LadybugDB index exists in the given storage path.
+ */
+export const hasLbugIndex = async (storagePath) => {
+    try {
+        await fs.stat(path.join(storagePath, 'lbug'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Clean up stale KuzuDB files after migration to LadybugDB.
  *
@@ -279,6 +291,7 @@ export const listRegisteredRepos = async (opts) => {
     for (const entry of entries) {
         try {
             await fs.access(path.join(entry.storagePath, 'meta.json'));
+            await fs.access(path.join(entry.storagePath, 'lbug'));
             valid.push(entry);
         }
         catch {

package/hooks/claude/gitnexus-hook.cjs

@@ -13,7 +13,41 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const { spawnSync } = require('child_process');
+const DEFAULT_NPX_SPEC = '@veewo/gitnexus@latest';
+const DEFAULT_PACKAGE_NAME = '@veewo/gitnexus';
+
+function normalizeNpxSpec(raw) {
+  const value = (raw || '').trim();
+  if (!value) return DEFAULT_NPX_SPEC;
+  if (value.startsWith('@') || value.includes('/') || value.includes('@')) {
+    if (value.startsWith('@') && value.indexOf('@', 1) === -1) return `${value}@latest`;
+    if (!value.startsWith('@') && !value.includes('/') && !value.includes('@')) return `${DEFAULT_PACKAGE_NAME}@${value}`;
+    if (!value.startsWith('@') && value.includes('@')) return value;
+    if (!value.includes('@')) return `${value}@latest`;
+    return value;
+  }
+  return `${DEFAULT_PACKAGE_NAME}@${value}`;
+}
+
+function resolveNpxSpec() {
+  if (process.env.GITNEXUS_CLI_SPEC) return normalizeNpxSpec(process.env.GITNEXUS_CLI_SPEC);
+  if (process.env.GITNEXUS_CLI_VERSION) return normalizeNpxSpec(process.env.GITNEXUS_CLI_VERSION);
+
+  try {
+    const raw = fs.readFileSync(path.join(os.homedir(), '.gitnexus', 'config.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.cliPackageSpec === 'string' && parsed.cliPackageSpec.trim()) {
+      return normalizeNpxSpec(parsed.cliPackageSpec);
+    }
+    if (typeof parsed.cliVersion === 'string' && parsed.cliVersion.trim()) {
+      return normalizeNpxSpec(parsed.cliVersion);
+    }
+  } catch {}
+
+  return DEFAULT_NPX_SPEC;
+}
 
 /**
  * Read JSON input from stdin synchronously.
@@ -107,7 +141,7 @@ function resolveCliPath() {
  * Spawn a gitnexus CLI command synchronously.
  * Returns the stderr output (KuzuDB captures stdout at OS level).
  */
-function runGitNexusCli(cliPath, args, cwd, timeout) {
+function runGitNexusCli(cliPath, args, cwd, timeout, npxSpec) {
   const isWin = process.platform === 'win32';
   if (cliPath) {
     return spawnSync(
@@ -119,7 +153,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
   // On Windows, invoke npx.cmd directly (no shell needed)
   return spawnSync(
     isWin ? 'npx.cmd' : 'npx',
-    ['-y', 'gitnexus', ...args],
+    ['-y', npxSpec, ...args],
     { encoding: 'utf-8', timeout: timeout + 5000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
   );
 }
@@ -141,9 +175,10 @@ function handlePreToolUse(input) {
   if (!pattern || pattern.length < 3) return;
 
   const cliPath = resolveCliPath();
+  const npxSpec = resolveNpxSpec();
   let result = '';
   try {
-    const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
+    const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000, npxSpec);
     if (!child.error && child.status === 0) {
       result = child.stderr || '';
     }
@@ -166,7 +201,7 @@ function sendHookResponse(hookEventName, message) {
 /**
  * PostToolUse handler — detect index staleness after git mutations.
  *
- * Instead of spawning a full `npx -y @veewo/gitnexus@latest analyze` synchronously (which blocks
+ * Instead of spawning a full analyze command synchronously (which blocks
  * the agent for up to 120s and risks KuzuDB corruption on timeout), we do a
  * lightweight staleness check: compare `git rev-parse HEAD` against the
  * lastCommit stored in `.gitnexus/meta.json`. If they differ, notify the
@@ -210,10 +245,13 @@ function handlePostToolUse(input) {
   // If HEAD matches last indexed commit, no reindex needed
   if (currentHead && currentHead === lastCommit) return;
 
-  const analyzeCmd = `npx -y @veewo/gitnexus@latest analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const npxSpec = resolveNpxSpec();
+  const analyzeArgs = `analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  const analyzeCmd = `gitnexus ${analyzeArgs}`;
+  const fallbackCmd = `npx -y ${npxSpec} ${analyzeArgs}`;
   sendHookResponse('PostToolUse',
     `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
-    `Run \`${analyzeCmd}\` to update the knowledge graph.`
+    `Run \`${analyzeCmd}\` (or \`${fallbackCmd}\`) to update the knowledge graph.`
   );
 }
 

package/hooks/claude/pre-tool-use.sh

@@ -64,7 +64,11 @@ fi
 
 # Run gitnexus augment — must be fast (<500ms target)
 # augment writes to stderr (KuzuDB captures stdout at OS level), so capture stderr and discard stdout
-RESULT=$(cd "$CWD" && npx -y @veewo/gitnexus@latest augment "$PATTERN" 2>&1 1>/dev/null)
+GITNEXUS_CLI_SPEC="${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}"
+if [ -n "$GITNEXUS_CLI_VERSION" ]; then
+  GITNEXUS_CLI_SPEC="@veewo/gitnexus@$GITNEXUS_CLI_VERSION"
+fi
+RESULT=$(cd "$CWD" && npx -y "$GITNEXUS_CLI_SPEC" augment "$PATTERN" 2>&1 1>/dev/null)
 
 if [ -n "$RESULT" ]; then
   ESCAPED=$(echo "$RESULT" | jq -Rs .)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.4.6-rc",
+  "version": "1.4.8-rc",
   "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",

package/skills/gitnexus-cli.md

@@ -5,14 +5,25 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/
 
 # GitNexus CLI Commands
 
-All commands work via `npx` — no global install required.
+Use one command alias in the session so every CLI/MCP call stays on one version line.
+
+```bash
+# If user prompt specifies a version (example: 1.4.7-rc), set it once:
+# export GITNEXUS_CLI_SPEC="@veewo/gitnexus@1.4.7-rc"
+GITNEXUS_CLI_SPEC="${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}"
+if command -v gitnexus >/dev/null 2>&1; then
+  GN="gitnexus"
+else
+  GN="npx -y ${GITNEXUS_CLI_SPEC}"
+fi
+```
 
 ## Commands
 
 ### analyze — Build or refresh the index
 
 ```bash
-npx -y @veewo/gitnexus@latest analyze
+$GN analyze
 ```
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
@@ -27,7 +38,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 ### status — Check index freshness
 
 ```bash
-npx -y @veewo/gitnexus@latest status
+$GN status
 ```
 
 Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
@@ -35,7 +46,7 @@ Shows whether the current repo has a GitNexus index, when it was last updated, a
 ### clean — Delete the index
 
 ```bash
-npx -y @veewo/gitnexus@latest clean
+$GN clean
 ```
 
 Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
@@ -48,7 +59,7 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
 ### wiki — Generate documentation from the graph
 
 ```bash
-npx -y @veewo/gitnexus@latest wiki
+$GN wiki
 ```
 
 Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
@@ -65,7 +76,7 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 ### list — Show all indexed repos
 
 ```bash
-npx -y @veewo/gitnexus@latest list
+$GN list
 ```
 
 Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
@@ -75,11 +86,11 @@ Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_
 For Unity resource retrieval:
 
 ```bash
-npx -y @veewo/gitnexus@latest context DoorObj --repo neonnew-core --file Assets/NEON/Code/Game/Doors/DoorObj.cs --unity-resources on --unity-hydration compact
+$GN context DoorObj --repo neonnew-core --file Assets/NEON/Code/Game/Doors/DoorObj.cs --unity-resources on --unity-hydration compact
 ```
 
 ```bash
-npx -y @veewo/gitnexus@latest query "DoorObj binding" --repo neonnew-core --unity-resources on --unity-hydration compact
+$GN query "DoorObj binding" --repo neonnew-core --unity-resources on --unity-hydration compact
 ```
 
 Rules:

package/skills/gitnexus-debugging.md

@@ -23,7 +23,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 5. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-> If "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
 
 ## Checklist
 

package/skills/gitnexus-exploring.md

@@ -24,7 +24,7 @@ description: "Use when the user asks how code works, wants to understand archite
 6. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
 
-> If step 2 says "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal.
+> If step 2 says "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
 
 ## Checklist
 

package/skills/gitnexus-guide.md

@@ -15,7 +15,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, run `npx -y @veewo/gitnexus@latest analyze` in the terminal first.
+> If step 1 warns the index is stale, run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
 
 ## Skills
 

package/skills/gitnexus-impact-analysis.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to know what will break if they change som
 4. Assess risk and report to user
 ```
 
-> If "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
 
 ## Checklist
 

package/skills/gitnexus-pr-review.md

@@ -26,7 +26,7 @@ description: "Use when the user wants to review a pull request, understand what
 6. Summarize findings with risk assessment
 ```
 
-> If "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal before reviewing.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze` before reviewing.
 
 ## Checklist
 

package/skills/gitnexus-refactoring.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 5. Plan update order: interfaces → implementations → callers → tests
 ```
 
-> If "Index is stale" → run `npx -y @veewo/gitnexus@latest analyze` in terminal.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
 
 ## Checklists