gitnexus 1.1.4 → 1.1.6

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

@@ -10,6 +10,7 @@ interface RepoStats {
     nodes?: number;
     edges?: number;
     communities?: number;
+    clusters?: number;
     processes?: number;
 }
 /**

package/dist/cli/ai-context.js

@@ -17,6 +17,7 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * Generate the full GitNexus context content (resources-first approach)
  */
 function generateGitNexusContent(projectName, stats) {
+    const clusterCount = stats.clusters || stats.communities || 0;
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
@@ -29,9 +30,11 @@ This project is indexed as **${projectName}** by GitNexus, providing AI agents w
 | Files | ${stats.files || 0} |
 | Symbols | ${stats.nodes || 0} |
 | Relationships | ${stats.edges || 0} |
-| Communities | ${stats.communities || 0} |
+| Clusters | ${clusterCount} |
 | Processes | ${stats.processes || 0} |
 
+> **Staleness:** If the index is out of date, run \`npx gitnexus analyze\` in the terminal to refresh. The \`gitnexus://repo/${projectName}/context\` resource will warn you when the index is stale.
+
 ## Quick Start
 
 \`\`\`
@@ -64,6 +67,8 @@ This project is indexed as **${projectName}** by GitNexus, providing AI agents w
 | \`impact\` | Blast radius analysis | Before making changes |
 | \`cypher\` | Raw graph queries | Complex analysis |
 
+> **Re-indexing:** To refresh a stale index, run \`npx gitnexus analyze\` in the terminal. Use \`--force\` only to rebuild from scratch. This is a CLI command, not an MCP tool.
+
 > **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
 
 ## Workflow Examples
@@ -71,17 +76,17 @@ This project is indexed as **${projectName}** by GitNexus, providing AI agents w
 ### Exploring the Codebase
 \`\`\`
 READ gitnexus://repos                            → Discover repos
-READ gitnexus://repo/${projectName}/context       → Stats and overview
-READ gitnexus://repo/${projectName}/clusters      → Find relevant cluster
-READ gitnexus://repo/${projectName}/cluster/Auth  → Explore Auth cluster
-gitnexus_explore({name: "validateUser", type: "symbol", repo: "${projectName}"})
+READ gitnexus://repo/${projectName}/context       → Stats and overview (check for staleness)
+READ gitnexus://repo/${projectName}/clusters      → Find relevant cluster by name
+READ gitnexus://repo/${projectName}/cluster/{name} → See members of that cluster
+gitnexus_explore({name: "<symbol_name>", type: "symbol", repo: "${projectName}"})
 \`\`\`
 
 ### Planning a Change
 \`\`\`
-gitnexus_impact({target: "UserService", direction: "upstream", repo: "${projectName}"})
-READ gitnexus://repo/${projectName}/processes     → Check affected flows
-gitnexus_explore({name: "LoginFlow", type: "process", repo: "${projectName}"})
+gitnexus_search({query: "<what you want to change>", repo: "${projectName}"})
+gitnexus_impact({target: "<symbol_name>", direction: "upstream", repo: "${projectName}"})
+READ gitnexus://repo/${projectName}/processes     → Check affected execution flows
 \`\`\`
 
 ## Graph Schema

package/dist/cli/analyze.js

@@ -70,6 +70,7 @@ export const analyzeCommand = async (inputPath, options) => {
         await createFTSIndex('Function', 'function_fts', ['name', 'content']);
         await createFTSIndex('Class', 'class_fts', ['name', 'content']);
         await createFTSIndex('Method', 'method_fts', ['name', 'content']);
+        await createFTSIndex('Interface', 'interface_fts', ['name', 'content']);
     }
     catch (e) {
         // FTS index creation may fail if tables are empty (no data for that type)
@@ -103,11 +104,23 @@ export const analyzeCommand = async (inputPath, options) => {
     await addToGitignore(repoPath);
     // Generate AI context files
     const projectName = path.basename(repoPath);
+    // Compute aggregated cluster count (grouped by heuristicLabel, >=5 symbols)
+    // This matches the aggregation logic in local-backend.ts for tool output consistency.
+    let aggregatedClusterCount = 0;
+    if (pipelineResult.communityResult?.communities) {
+        const groups = new Map();
+        for (const c of pipelineResult.communityResult.communities) {
+            const label = c.heuristicLabel || c.label || 'Unknown';
+            groups.set(label, (groups.get(label) || 0) + c.symbolCount);
+        }
+        aggregatedClusterCount = Array.from(groups.values()).filter(count => count >= 5).length;
+    }
     const aiContext = await generateAIContextFiles(repoPath, storagePath, projectName, {
         files: pipelineResult.fileContents.size,
         nodes: stats.nodes,
         edges: stats.edges,
         communities: pipelineResult.communityResult?.stats.totalCommunities,
+        clusters: aggregatedClusterCount,
         processes: pipelineResult.processResult?.stats.totalProcesses,
     });
     // Close database

package/dist/core/ingestion/process-processor.js

@@ -121,10 +121,16 @@ export const processProcesses = async (knowledgeGraph, memberships, onProgress,
         },
     };
 };
+/**
+ * Minimum edge confidence for process tracing.
+ * Filters out ambiguous fuzzy-global matches (0.3) that cause
+ * traces to jump across unrelated code areas.
+ */
+const MIN_TRACE_CONFIDENCE = 0.5;
 const buildCallsGraph = (graph) => {
     const adj = new Map();
     graph.relationships.forEach(rel => {
-        if (rel.type === 'CALLS') {
+        if (rel.type === 'CALLS' && rel.confidence >= MIN_TRACE_CONFIDENCE) {
             if (!adj.has(rel.sourceId)) {
                 adj.set(rel.sourceId, []);
             }
@@ -136,7 +142,7 @@ const buildCallsGraph = (graph) => {
 const buildReverseCallsGraph = (graph) => {
     const adj = new Map();
     graph.relationships.forEach(rel => {
-        if (rel.type === 'CALLS') {
+        if (rel.type === 'CALLS' && rel.confidence >= MIN_TRACE_CONFIDENCE) {
             if (!adj.has(rel.targetId)) {
                 adj.set(rel.targetId, []);
             }

package/dist/core/search/bm25-index.js

@@ -44,25 +44,27 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
  * @returns Ranked search results from FTS indexes
  */
 export const searchFTSFromKuzu = async (query, limit = 20, repoId) => {
-    let fileResults, functionResults, classResults, methodResults;
+    let fileResults, functionResults, classResults, methodResults, interfaceResults;
     if (repoId) {
         // Use MCP connection pool via dynamic import
         const { executeQuery } = await import('../../mcp/core/kuzu-adapter.js');
         const executor = (cypher) => executeQuery(repoId, cypher);
-        [fileResults, functionResults, classResults, methodResults] = await Promise.all([
+        [fileResults, functionResults, classResults, methodResults, interfaceResults] = await Promise.all([
             queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit),
             queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit),
             queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit),
             queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit),
+            queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit),
         ]);
     }
     else {
         // Use core kuzu adapter (CLI / pipeline context)
-        [fileResults, functionResults, classResults, methodResults] = await Promise.all([
+        [fileResults, functionResults, classResults, methodResults, interfaceResults] = await Promise.all([
             queryFTS('File', 'file_fts', query, limit, false).catch(() => []),
             queryFTS('Function', 'function_fts', query, limit, false).catch(() => []),
             queryFTS('Class', 'class_fts', query, limit, false).catch(() => []),
             queryFTS('Method', 'method_fts', query, limit, false).catch(() => []),
+            queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []),
         ]);
     }
     // Merge results by filePath, summing scores for same file
@@ -82,6 +84,7 @@ export const searchFTSFromKuzu = async (query, limit = 20, repoId) => {
     addResults(functionResults);
     addResults(classResults);
     addResults(methodResults);
+    addResults(interfaceResults);
     // Sort by score descending and add rank
     const sorted = Array.from(merged.values())
         .sort((a, b) => b.score - a.score)

package/dist/mcp/local/local-backend.d.ts

@@ -81,7 +81,6 @@ export declare class LocalBackend {
     private overview;
     private explore;
     private impact;
-    private analyze;
     disconnect(): Promise<void>;
 }
 export {};

package/dist/mcp/local/local-backend.js

@@ -8,9 +8,11 @@
 import path from 'path';
 import { initKuzu, executeQuery, closeKuzu, isKuzuReady } from '../core/kuzu-adapter.js';
 import { embedQuery, getEmbeddingDims, disposeEmbedder } from '../core/embedder.js';
-import { isGitRepo, getCurrentCommit } from '../../storage/git.js';
-import { getStoragePaths as getRepoStoragePaths, saveMeta as saveRepoMeta, loadMeta as loadRepoMeta, addToGitignore, listRegisteredRepos, registerRepo, } from '../../storage/repo-manager.js';
-import { generateAIContextFiles } from '../../cli/ai-context.js';
+// git utilities available if needed
+// import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
+import { listRegisteredRepos, } from '../../storage/repo-manager.js';
+// AI context generation is CLI-only (gitnexus analyze)
+// import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
  * Quick test-file detection for filtering impact results.
  * Matches common test file patterns across all supported languages.
@@ -123,7 +125,8 @@ export class LocalBackend {
     }
     // ─── Lazy KuzuDB Init ────────────────────────────────────────────
     async ensureInitialized(repoId) {
-        if (this.initializedRepos.has(repoId))
+        // Always check the actual pool — the idle timer may have evicted the connection
+        if (this.initializedRepos.has(repoId) && isKuzuReady(repoId))
             return;
         const handle = this.repos.get(repoId);
         if (!handle)
@@ -174,8 +177,6 @@ export class LocalBackend {
                 return this.explore(repo, params);
             case 'impact':
                 return this.impact(repo, params);
-            case 'analyze':
-                return this.analyze(repo, params);
             default:
                 throw new Error(`Unknown tool: ${method}`);
         }
@@ -192,11 +193,13 @@ export class LocalBackend {
             this.semanticSearch(repo, query, limit * 2),
         ]);
         // Merge and deduplicate results using reciprocal rank fusion
+        // Key by nodeId (symbol-level) so semantic precision is preserved.
+        // Fall back to filePath for File-level results that lack a nodeId.
         const scoreMap = new Map();
         // BM25 results
         for (let i = 0; i < bm25Results.length; i++) {
             const result = bm25Results[i];
-            const key = result.filePath;
+            const key = result.nodeId || result.filePath;
             const rrfScore = 1 / (60 + i);
             const existing = scoreMap.get(key);
             if (existing) {
@@ -210,7 +213,7 @@ export class LocalBackend {
         // Semantic results
         for (let i = 0; i < semanticResults.length; i++) {
             const result = semanticResults[i];
-            const key = result.filePath;
+            const key = result.nodeId || result.filePath;
             const rrfScore = 1 / (60 + i);
             const existing = scoreMap.get(key);
             if (existing) {
@@ -252,10 +255,12 @@ export class LocalBackend {
                 }
             }
             // Add relationships if depth is 'full' and we have a node ID
+            // Only include connections with actual name/path data (skip MEMBER_OF, STEP_IN_PROCESS noise)
             if (depth === 'full' && result.nodeId) {
                 try {
                     const relQuery = `
             MATCH (n {id: '${result.nodeId.replace(/'/g, "''")}'})-[r:CodeRelation]->(m)
+            WHERE r.type IN ['CALLS', 'IMPORTS', 'DEFINES', 'EXTENDS', 'IMPLEMENTS']
             RETURN r.type AS type, m.name AS targetName, m.filePath AS targetPath
             LIMIT 5
           `;
@@ -282,11 +287,11 @@ export class LocalBackend {
         const bm25Results = await searchFTSFromKuzu(query, limit, repo.id);
         const results = [];
         for (const bm25Result of bm25Results) {
-            const fileName = bm25Result.filePath.split('/').pop() || bm25Result.filePath;
+            const fullPath = bm25Result.filePath;
             try {
                 const symbolQuery = `
           MATCH (n) 
-          WHERE n.filePath CONTAINS '${fileName.replace(/'/g, "''")}'
+          WHERE n.filePath = '${fullPath.replace(/'/g, "''")}'
           RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
           LIMIT 3
         `;
@@ -305,6 +310,7 @@ export class LocalBackend {
                     }
                 }
                 else {
+                    const fileName = fullPath.split('/').pop() || fullPath;
                     results.push({
                         name: fileName,
                         type: 'File',
@@ -314,6 +320,7 @@ export class LocalBackend {
                 }
             }
             catch {
+                const fileName = fullPath.split('/').pop() || fullPath;
                 results.push({
                     name: fileName,
                     type: 'File',
@@ -485,15 +492,19 @@ export class LocalBackend {
         await this.ensureInitialized(repo.id);
         const { name, type } = params;
         if (type === 'symbol') {
-            const symbolQuery = `
-        MATCH (n)
-        WHERE n.name = '${name.replace(/'/g, "''")}'
-        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
-        LIMIT 1
-      `;
+            // If name contains a path separator or ':', treat it as a qualified lookup
+            const isQualified = name.includes('/') || name.includes(':');
+            const symbolQuery = isQualified
+                ? `MATCH (n) WHERE n.id = '${name.replace(/'/g, "''")}' OR (n.name = '${name.replace(/'/g, "''")}')
+           RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+           LIMIT 5`
+                : `MATCH (n) WHERE n.name = '${name.replace(/'/g, "''")}'
+           RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine
+           LIMIT 5`;
             const symbols = await executeQuery(repo.id, symbolQuery);
             if (symbols.length === 0)
                 return { error: `Symbol '${name}' not found` };
+            // Use the first match for detailed exploration
             const sym = symbols[0];
             const symId = sym.id || sym[0];
             const callersQuery = `
@@ -514,7 +525,7 @@ export class LocalBackend {
         LIMIT 1
       `;
             const communities = await executeQuery(repo.id, communityQuery);
-            return {
+            const result = {
                 symbol: {
                     id: symId,
                     name: sym.name || sym[1],
@@ -530,6 +541,16 @@ export class LocalBackend {
                     heuristicLabel: communities[0].heuristicLabel || communities[0][1],
                 } : null,
             };
+            // If multiple symbols share the same name, show alternatives so the agent can disambiguate
+            if (symbols.length > 1) {
+                result.alternatives = symbols.slice(1).map((s) => ({
+                    id: s.id || s[0],
+                    type: s.type || s[2],
+                    filePath: s.filePath || s[3],
+                }));
+                result.hint = `Multiple symbols named '${name}' found. Showing details for ${result.symbol.filePath}. Use the full node ID to explore a specific alternative.`;
+            }
+            return result;
         }
         if (type === 'cluster') {
             const escaped = name.replace(/'/g, "''");
@@ -689,121 +710,6 @@ export class LocalBackend {
             byDepth: grouped,
         };
     }
-    async analyze(repo, params) {
-        let repoPath;
-        if (params.path) {
-            repoPath = path.resolve(params.path);
-        }
-        else {
-            repoPath = repo.repoPath;
-        }
-        if (!isGitRepo(repoPath)) {
-            return { error: 'Not a git repository' };
-        }
-        const { storagePath, kuzuPath } = getRepoStoragePaths(repoPath);
-        const currentCommit = getCurrentCommit(repoPath);
-        const existingMeta = await loadRepoMeta(storagePath);
-        if (existingMeta && !params.force && existingMeta.lastCommit === currentCommit) {
-            return { status: 'up_to_date', message: 'Repository already up to date.' };
-        }
-        // Close this repo's MCP connection before pipeline takes over
-        await closeKuzu(repo.id);
-        this.initializedRepos.delete(repo.id);
-        try {
-            const { runPipelineFromRepo } = await import('../../core/ingestion/pipeline.js');
-            const coreKuzu = await import('../../core/kuzu/kuzu-adapter.js');
-            console.error('GitNexus: Running indexing pipeline...');
-            const pipelineResult = await runPipelineFromRepo(repoPath, (progress) => {
-                if (progress.percent % 20 === 0) {
-                    console.error(`GitNexus: ${progress.phase} ${progress.percent}%`);
-                }
-            });
-            console.error('GitNexus: Loading graph into KuzuDB...');
-            await coreKuzu.initKuzu(kuzuPath);
-            await coreKuzu.loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath);
-            console.error('GitNexus: Creating FTS indexes...');
-            try {
-                await coreKuzu.createFTSIndex('File', 'file_fts', ['name', 'content']);
-                await coreKuzu.createFTSIndex('Function', 'function_fts', ['name', 'content']);
-                await coreKuzu.createFTSIndex('Class', 'class_fts', ['name', 'content']);
-                await coreKuzu.createFTSIndex('Method', 'method_fts', ['name', 'content']);
-            }
-            catch (e) {
-                console.error('GitNexus: Some FTS indexes may not have been created:', e.message);
-            }
-            if (!params.skipEmbeddings) {
-                try {
-                    console.error('GitNexus: Generating embeddings...');
-                    const { runEmbeddingPipeline } = await import('../../core/embeddings/embedding-pipeline.js');
-                    await runEmbeddingPipeline(coreKuzu.executeQuery, coreKuzu.executeWithReusedStatement, (progress) => {
-                        if (progress.percent % 25 === 0) {
-                            console.error(`GitNexus: Embeddings ${progress.percent}%`);
-                        }
-                    });
-                }
-                catch (e) {
-                    console.error('GitNexus: Embedding generation failed (non-fatal):', e.message);
-                }
-            }
-            const stats = await coreKuzu.getKuzuStats();
-            const newMeta = {
-                repoPath,
-                lastCommit: currentCommit,
-                indexedAt: new Date().toISOString(),
-                stats: {
-                    files: pipelineResult.fileContents.size,
-                    nodes: stats.nodes,
-                    edges: stats.edges,
-                    communities: pipelineResult.communityResult?.stats.totalCommunities,
-                    processes: pipelineResult.processResult?.stats.totalProcesses,
-                },
-            };
-            await saveRepoMeta(storagePath, newMeta);
-            await addToGitignore(repoPath);
-            // Register in global registry
-            await registerRepo(repoPath, newMeta);
-            const projectName = path.basename(repoPath);
-            await generateAIContextFiles(repoPath, storagePath, projectName, {
-                files: pipelineResult.fileContents.size,
-                nodes: stats.nodes,
-                edges: stats.edges,
-                communities: pipelineResult.communityResult?.stats.totalCommunities,
-                processes: pipelineResult.processResult?.stats.totalProcesses,
-            });
-            await coreKuzu.closeKuzu();
-            // Update in-memory state
-            const handle = {
-                id: repo.id,
-                name: projectName,
-                repoPath,
-                storagePath,
-                kuzuPath,
-                indexedAt: newMeta.indexedAt,
-                lastCommit: newMeta.lastCommit,
-                stats: newMeta.stats,
-            };
-            this.repos.set(repo.id, handle);
-            this.contextCache.set(repo.id, {
-                projectName,
-                stats: {
-                    fileCount: newMeta.stats.files || 0,
-                    functionCount: newMeta.stats.nodes || 0,
-                    communityCount: newMeta.stats.communities || 0,
-                    processCount: newMeta.stats.processes || 0,
-                },
-            });
-            console.error('GitNexus: Indexing complete!');
-            return {
-                status: 'success',
-                message: `Repository indexed successfully.`,
-                stats: newMeta.stats,
-            };
-        }
-        catch (e) {
-            console.error('GitNexus: Indexing failed:', e.message);
-            return { error: `Indexing failed: ${e.message}` };
-        }
-    }
     async disconnect() {
         await closeKuzu(); // close all connections
         await disposeEmbedder();

package/dist/mcp/resources.js

@@ -132,7 +132,6 @@ function getReposResource(backend) {
         if (repo.stats) {
             lines.push(`    files: ${repo.stats.files || 0}`);
             lines.push(`    symbols: ${repo.stats.nodes || 0}`);
-            lines.push(`    clusters: ${repo.stats.communities || 0}`);
             lines.push(`    processes: ${repo.stats.processes || 0}`);
         }
     }
@@ -158,6 +157,15 @@ async function getContextResource(backend, repoName) {
     const repoPath = repo.repoPath;
     const lastCommit = repo.lastCommit || 'HEAD';
     const staleness = repoPath ? checkStaleness(repoPath, lastCommit) : { isStale: false, commitsBehind: 0 };
+    // Get aggregated cluster count (matches what overview/clusters resource shows)
+    let clusterCount = context.stats.communityCount;
+    try {
+        const overview = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 100, repo: repoName });
+        if (overview.clusters) {
+            clusterCount = overview.clusters.length;
+        }
+    }
+    catch { /* fall back to raw count */ }
     const lines = [
         `project: ${context.projectName}`,
     ];
@@ -169,7 +177,7 @@ async function getContextResource(backend, repoName) {
     lines.push('stats:');
     lines.push(`  files: ${context.stats.fileCount}`);
     lines.push(`  symbols: ${context.stats.functionCount}`);
-    lines.push(`  clusters: ${context.stats.communityCount}`);
+    lines.push(`  clusters: ${clusterCount}`);
     lines.push(`  processes: ${context.stats.processCount}`);
     lines.push('');
     lines.push('tools_available:');
@@ -179,7 +187,8 @@ async function getContextResource(backend, repoName) {
     lines.push('  - impact: Blast radius analysis');
     lines.push('  - overview: List all clusters and processes');
     lines.push('  - cypher: Raw graph queries');
-    lines.push('  - analyze: Re-index to update stale data');
+    lines.push('');
+    lines.push('re_index: Run `npx gitnexus analyze` in terminal if data is stale');
     lines.push('');
     lines.push('resources_available:');
     lines.push('  - gitnexus://repos: All indexed repositories');

package/dist/mcp/tools.js

@@ -20,37 +20,6 @@ on other tools (search, explore, impact, etc.) to target the correct one.`,
             required: [],
         },
     },
-    {
-        name: 'analyze',
-        description: `Index or re-index a repository. Runs the full pipeline in-process.
-
-Creates .gitnexus/ in repo root with:
-- Knowledge graph (functions, classes, calls, imports)
-- Full-text search indexes
-- Community detection (Leiden)
-- Process tracing
-- Embeddings for semantic search
-
-Also registers the repo in the global registry so the MCP server can serve it.
-
-Run this when:
-- First time using GitNexus on a repo
-- After major code changes
-- When staleness warning appears in gitnexus://context
-- When 'not indexed' error appears
-
-Note: This may take 30-120 seconds for large repos.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                path: { type: 'string', description: 'Repo path (default: current directory)' },
-                force: { type: 'boolean', description: 'Re-index even if exists', default: false },
-                skipEmbeddings: { type: 'boolean', description: 'Skip embedding generation (faster)', default: false },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
-            },
-            required: [],
-        },
-    },
     {
         name: 'search',
         description: `Hybrid search (keyword + semantic) across the codebase.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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/debugging.md

@@ -8,7 +8,7 @@ description: Trace bugs through call chains using knowledge graph
 ## Quick Start
 ```
 0. READ gitnexus://repos                          → Discover indexed repos
-1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
+1. If "Index is stale" → run `npx gitnexus analyze` in terminal
 2. gitnexus_search({query: "...", repo: "my-app"})  → Find code related to error
 3. gitnexus_explore({name, type: "symbol", repo: "my-app"}) → Get callers and callees
 4. READ gitnexus://repo/my-app/process/{name}      → Trace execution flow

package/skills/exploring.md

@@ -8,7 +8,7 @@ description: Navigate unfamiliar code using GitNexus knowledge graph
 ## Quick Start
 ```
 0. READ gitnexus://repos            → Discover indexed repos (use repo param if multiple)
-1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
+1. If "Index is stale" → run `npx gitnexus analyze` in terminal
 2. READ gitnexus://repo/{name}/context        → Get codebase overview (~150 tokens)
 3. READ gitnexus://repo/{name}/clusters       → See all functional clusters
 4. READ gitnexus://repo/{name}/cluster/{name} → Deep dive on specific cluster

package/skills/impact-analysis.md

@@ -8,7 +8,7 @@ description: Analyze blast radius before making code changes
 ## Quick Start
 ```
 0. READ gitnexus://repos                                    → Discover indexed repos
-1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
+1. If "Index is stale" → run `npx gitnexus analyze` in terminal
 2. gitnexus_impact({target, direction: "upstream", repo: "my-app"}) → What depends on this
 3. READ gitnexus://repo/my-app/clusters                     → Check affected areas
 4. READ gitnexus://repo/my-app/processes                    → Affected execution flows

package/skills/refactoring.md

@@ -8,7 +8,7 @@ description: Plan safe refactors using blast radius and dependency mapping
 ## Quick Start
 ```
 0. READ gitnexus://repos                                    → Discover indexed repos
-1. If "Index is stale" → gitnexus_analyze({repo: "my-app"})
+1. If "Index is stale" → run `npx gitnexus analyze` in terminal
 2. gitnexus_impact({target, direction: "upstream", repo: "my-app"}) → Map all dependents
 3. READ gitnexus://repo/my-app/schema                       → Understand graph structure
 4. gitnexus_cypher({query: "...", repo: "my-app"})           → Find all references