gitnexus 1.1.8 → 1.1.9

package/dist/mcp/tools.js

@@ -15,7 +15,7 @@ WHEN TO USE: First step when multiple repos are indexed, or to discover availabl
 AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
 
 When multiple repos are indexed, you MUST specify the "repo" parameter
-on other tools (search, explore, impact, etc.) to target the correct one.`,
+on other tools (query, context, impact, etc.) to target the correct one.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -23,25 +23,28 @@ on other tools (search, explore, impact, etc.) to target the correct one.`,
         },
     },
     {
-        name: 'search',
-        description: `Hybrid search (keyword + semantic) across the codebase.
-Returns code nodes with cluster context and optional graph connections.
+        name: 'query',
+        description: `Query the code knowledge graph for execution flows related to a concept.
+Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
 
-WHEN TO USE: Finding code by concept, name, or keyword. Use alongside grep/IDE search for richer results.
-AFTER THIS: Use explore() on interesting results to see callers/callees and cluster membership.
+WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
+AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
 
-Complements grep/IDE search by adding:
-- Cluster context (which functional area each result belongs to)
-- Relationship data (callers/callees with depth=full)
-- Hybrid ranking (BM25 + semantic via Reciprocal Rank Fusion)
+Returns results grouped by process (execution flow):
+- processes: ranked execution flows with relevance priority
+- process_symbols: all symbols in those flows with file locations
+- definitions: standalone types/interfaces not in any process
 
-RETURNS: Array of {name, type, filePath, cluster?, connections[]?, fusedScore, searchSource}`,
+Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Natural language or keyword search query' },
-                limit: { type: 'number', description: 'Max results to return', default: 10 },
-                depth: { type: 'string', description: 'Result detail: "definitions" (symbols only) or "full" (with relationships)', enum: ['definitions', 'full'], default: 'definitions' },
+                task_context: { type: 'string', description: 'What you are working on (e.g., "adding OAuth support"). Helps ranking.' },
+                goal: { type: 'string', description: 'What you want to find (e.g., "existing auth validation logic"). Helps ranking.' },
+                limit: { type: 'number', description: 'Max processes to return (default: 5)', default: 5 },
+                max_symbols: { type: 'number', description: 'Max symbols per process (default: 10)', default: 10 },
+                include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
                 repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
             },
             required: ['query'],
@@ -52,26 +55,30 @@ RETURNS: Array of {name, type, filePath, cluster?, connections[]?, fusedScore, s
         description: `Execute Cypher query against the code knowledge graph.
 
 WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
-AFTER THIS: Use explore() on result symbols for deeper context.
+AFTER THIS: Use context() on result symbols for deeper context.
 
 SCHEMA:
-- Nodes: File, Folder, Function, Class, Interface, Method, Community, Process
-- Edges via CodeRelation.type: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, CONTAINS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
+- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
+- All edges via single CodeRelation table with 'type' property
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
+- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
 
 EXAMPLES:
 • Find callers of a function:
   MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
 
-• Find all functions in a community:
-  MATCH (f:Function)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community {label: "Auth"}) RETURN f.name
+• Find community members:
+  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
 
-• Find steps in a process:
-  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {label: "UserLogin"}) RETURN s.name, r.step ORDER BY r.step
+• Trace a process:
+  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
 
 TIPS:
-- All relationships use CodeRelation table with 'type' property
-- Community = functional cluster detected by Leiden algorithm
-- Process = execution flow trace from entry point to terminal`,
+- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
+- Community = auto-detected functional area (Leiden algorithm)
+- Process = execution flow trace from entry point to terminal
+- Use heuristicLabel (not label) for human-readable community/process names`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -82,72 +89,84 @@ TIPS:
         },
     },
     {
-        name: 'explore',
-        description: `Deep dive on a symbol, cluster, or process.
+        name: 'context',
+        description: `360-degree view of a single code symbol.
+Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
 
-WHEN TO USE: After search() to understand context, or to drill into a specific node.
-AFTER THIS (symbol): Use impact() if planning changes, or READ process resource to see execution flows.
-AFTER THIS (cluster): Use explore() on specific members, or READ processes resource.
-AFTER THIS (process): Use explore() on individual steps for detail.
+WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
+AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
 
-TYPE: symbol | cluster | process
-
-For SYMBOL: Shows cluster membership, process participation, callers/callees
-For CLUSTER: Shows members, cohesion score, processes touching it
-For PROCESS: Shows step-by-step trace, clusters traversed, entry/terminal points`,
+Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
         inputSchema: {
             type: 'object',
             properties: {
-                name: { type: 'string', description: 'Name of symbol, cluster, or process to explore' },
-                type: { type: 'string', description: 'Type: symbol, cluster, or process' },
+                name: { type: 'string', description: 'Symbol name (e.g., "validateUser", "AuthService")' },
+                uid: { type: 'string', description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)' },
+                file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
                 repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
             },
-            required: ['name', 'type'],
+            required: [],
         },
     },
     {
-        name: 'overview',
-        description: `Get codebase map showing all clusters and processes.
+        name: 'detect_changes',
+        description: `Analyze uncommitted git changes and find affected execution flows.
+Maps git diff hunks to indexed symbols, then traces which processes are impacted.
 
-WHEN TO USE: Understanding overall architecture. Prefer READ gitnexus://repo/{name}/clusters resource for a lighter-weight alternative.
-AFTER THIS: Drill into a specific cluster with explore({type: "cluster"}) or search() for specific code.
+WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
+AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
 
-Returns:
-- All communities (clusters) with member counts and cohesion scores
-- All processes with step counts and types (intra/cross-community)
-- High-level architectural view`,
+Returns: changed symbols, affected processes, and a risk summary.`,
         inputSchema: {
             type: 'object',
             properties: {
-                showProcesses: { type: 'boolean', description: 'Include process list', default: true },
-                showClusters: { type: 'boolean', description: 'Include cluster list', default: true },
-                limit: { type: 'number', description: 'Max items per category', default: 20 },
+                scope: { type: 'string', description: 'What to analyze: "unstaged" (default), "staged", "all", or "compare"', enum: ['unstaged', 'staged', 'all', 'compare'], default: 'unstaged' },
+                base_ref: { type: 'string', description: 'Branch/commit for "compare" scope (e.g., "main")' },
                 repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
             },
             required: [],
         },
     },
     {
-        name: 'impact',
-        description: `Analyze the impact of changing a code element.
-Returns all nodes affected by modifying the target, with distance, edge type, and confidence.
+        name: 'rename',
+        description: `Multi-file coordinated rename using the knowledge graph + text search.
+Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
 
-WHEN TO USE: Before making code changes, especially refactoring, renaming, or modifying shared code. Shows what would be affected.
-AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected flows. If risk > MEDIUM, warn the user.
+WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
+AFTER THIS: Run detect_changes() to verify no unexpected side effects.
 
-Output includes:
-- Affected processes (with step positions)
-- Affected clusters (direct/indirect)
-- Risk assessment (critical/high/medium/low)
-- Callers/dependents grouped by depth
+Each edit is tagged with confidence:
+- "graph": found via knowledge graph relationships (high confidence, safe to accept)
+- "text_search": found via regex text search (lower confidence, review carefully)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol_name: { type: 'string', description: 'Current symbol name to rename' },
+                symbol_uid: { type: 'string', description: 'Direct symbol UID from prior tool results (zero-ambiguity)' },
+                new_name: { type: 'string', description: 'The new name for the symbol' },
+                file_path: { type: 'string', description: 'File path to disambiguate common names' },
+                dry_run: { type: 'boolean', description: 'Preview edits without modifying files (default: true)', default: true },
+                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+            },
+            required: ['new_name'],
+        },
+    },
+    {
+        name: 'impact',
+        description: `Analyze the blast radius of changing a code symbol.
+Returns all symbols affected by modifying the target, grouped by depth with edge types and confidence.
 
-EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
-Confidence: 100% = certain, <80% = fuzzy match
+WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
+AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected execution flows.
 
 Depth groups:
 - d=1: WILL BREAK (direct callers/importers)
 - d=2: LIKELY AFFECTED (indirect)
-- d=3: MAY NEED TESTING (transitive)`,
+- d=3: MAY NEED TESTING (transitive)
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
+Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',
             properties: {

package/hooks/claude/gitnexus-hook.cjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * GitNexus Claude Code Hook
+ *
+ * PreToolUse handler — intercepts Grep/Glob/Bash searches
+ * and augments with graph context from the GitNexus index.
+ *
+ * NOTE: SessionStart hooks are broken on Windows (Claude Code bug).
+ * Session context is injected via CLAUDE.md / skills instead.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Read JSON input from stdin synchronously.
+ */
+function readInput() {
+  try {
+    const data = fs.readFileSync(0, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check if a directory (or ancestor) has a .gitnexus index.
+ */
+function findGitNexusIndex(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
+      return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * Extract search pattern from tool input.
+ */
+function extractPattern(toolName, toolInput) {
+  if (toolName === 'Grep') {
+    return toolInput.pattern || null;
+  }
+
+  if (toolName === 'Glob') {
+    const raw = toolInput.pattern || '';
+    const match = raw.match(/[*\/]([a-zA-Z][a-zA-Z0-9_-]{2,})/);
+    return match ? match[1] : null;
+  }
+
+  if (toolName === 'Bash') {
+    const cmd = toolInput.command || '';
+    if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
+
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false;
+    let skipNext = false;
+    const flagsWithValues = new Set(['-e', '-f', '-m', '-A', '-B', '-C', '-g', '--glob', '-t', '--type', '--include', '--exclude']);
+
+    for (const token of tokens) {
+      if (skipNext) { skipNext = false; continue; }
+      if (!foundCmd) {
+        if (/\brg$|\bgrep$/.test(token)) foundCmd = true;
+        continue;
+      }
+      if (token.startsWith('-')) {
+        if (flagsWithValues.has(token)) skipNext = true;
+        continue;
+      }
+      const cleaned = token.replace(/['"]/g, '');
+      return cleaned.length >= 3 ? cleaned : null;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+function main() {
+  try {
+    const input = readInput();
+    const hookEvent = input.hook_event_name || '';
+
+    if (hookEvent !== 'PreToolUse') return;
+
+    const cwd = input.cwd || process.cwd();
+    if (!findGitNexusIndex(cwd)) return;
+
+    const toolName = input.tool_name || '';
+    const toolInput = input.tool_input || {};
+
+    if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
+
+    const pattern = extractPattern(toolName, toolInput);
+    if (!pattern || pattern.length < 3) return;
+
+    // Resolve CLI path relative to this hook script (same package)
+    // hooks/claude/gitnexus-hook.cjs → dist/cli/index.js
+    const cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');
+
+    // augment CLI writes result to stderr (KuzuDB's native module captures
+    // stdout fd at OS level, making it unusable in subprocess contexts).
+    const { spawnSync } = require('child_process');
+    let result = '';
+    try {
+      const child = spawnSync(
+        process.execPath,
+        [cliPath, 'augment', pattern],
+        { encoding: 'utf-8', timeout: 8000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      result = child.stderr || '';
+    } catch { /* graceful failure */ }
+
+    if (result && result.trim()) {
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: result.trim()
+        }
+      }));
+    }
+  } catch (err) {
+    // Graceful failure — log to stderr for debugging
+    console.error('GitNexus hook error:', err.message);
+  }
+}
+
+main();

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

@@ -0,0 +1,78 @@
+#!/bin/bash
+# GitNexus PreToolUse hook for Claude Code
+# Intercepts Grep/Glob/Bash searches and augments with graph context.
+# Receives JSON on stdin with { tool_name, tool_input, cwd, ... }
+# Returns JSON with additionalContext for graph-enriched results.
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+
+# Extract search pattern based on tool type
+PATTERN=""
+
+case "$TOOL_NAME" in
+  Grep)
+    PATTERN=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
+    ;;
+  Glob)
+    # Glob patterns are file paths, not search terms — extract meaningful part
+    RAW=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
+    # Strip glob syntax to get the meaningful name (e.g., "**/*.ts" → skip, "auth*.ts" → "auth")
+    PATTERN=$(echo "$RAW" | sed -n 's/.*[*\/]\([a-zA-Z][a-zA-Z0-9_-]*\).*/\1/p')
+    ;;
+  Bash)
+    CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+    # Only augment grep/rg commands
+    if echo "$CMD" | grep -qE '\brg\b|\bgrep\b'; then
+      # Extract pattern from rg/grep
+      if echo "$CMD" | grep -qE '\brg\b'; then
+        PATTERN=$(echo "$CMD" | sed -n "s/.*\brg\s\+\(--[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+      elif echo "$CMD" | grep -qE '\bgrep\b'; then
+        PATTERN=$(echo "$CMD" | sed -n "s/.*\bgrep\s\+\(-[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+      fi
+    fi
+    ;;
+  *)
+    # Not a search tool — skip
+    exit 0
+    ;;
+esac
+
+# Skip if pattern too short or empty
+if [ -z "$PATTERN" ] || [ ${#PATTERN} -lt 3 ]; then
+  exit 0
+fi
+
+# Check if we're in a GitNexus-indexed repo
+dir="${CWD:-$PWD}"
+found=false
+for i in 1 2 3 4 5; do
+  if [ -d "$dir/.gitnexus" ]; then
+    found=true
+    break
+  fi
+  parent="$(dirname "$dir")"
+  [ "$parent" = "$dir" ] && break
+  dir="$parent"
+done
+
+if [ "$found" = false ]; then
+  exit 0
+fi
+
+# Run gitnexus augment — must be fast (<500ms target)
+RESULT=$(cd "$CWD" && npx -y gitnexus augment "$PATTERN" 2>/dev/null)
+
+if [ -n "$RESULT" ]; then
+  ESCAPED=$(echo "$RESULT" | jq -Rs .)
+  jq -n --argjson ctx "$ESCAPED" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext: $ctx
+    }
+  }'
+else
+  exit 0
+fi

package/hooks/claude/session-start.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# GitNexus SessionStart hook for Claude Code
+# Fires on session startup. Stdout is injected into Claude's context.
+# Checks if the current directory has a GitNexus index.
+
+dir="$PWD"
+found=false
+for i in 1 2 3 4 5; do
+  if [ -d "$dir/.gitnexus" ]; then
+    found=true
+    break
+  fi
+  parent="$(dirname "$dir")"
+  [ "$parent" = "$dir" ] && break
+  dir="$parent"
+done
+
+if [ "$found" = false ]; then
+  exit 0
+fi
+
+# Inject GitNexus context — this stdout goes directly into Claude's context
+cat << 'EOF'
+## GitNexus Code Intelligence
+
+This codebase is indexed by GitNexus, providing a knowledge graph with execution flows, relationships, and semantic search.
+
+**Available MCP Tools:**
+- `query` — Process-grouped code intelligence (execution flows related to a concept)
+- `context` — 360-degree symbol view (categorized refs, process participation)
+- `impact` — Blast radius analysis (what breaks if you change a symbol)
+- `detect_changes` — Git-diff impact analysis (what do your changes affect)
+- `rename` — Multi-file coordinated rename with confidence tags
+- `cypher` — Raw graph queries
+- `list_repos` — Discover indexed repos
+
+**Quick Start:** READ `gitnexus://repo/{name}/context` for codebase overview, then use `query` to find execution flows.
+
+**Resources:** `gitnexus://repo/{name}/context` (overview), `/processes` (execution flows), `/schema` (for Cypher)
+EOF
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "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",
@@ -31,6 +31,7 @@
   },
   "files": [
     "dist",
+    "hooks",
     "skills",
     "vendor"
   ],
@@ -42,6 +43,7 @@
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "cli-progress": "^3.12.0",
     "commander": "^12.0.0",
     "cors": "^2.8.5",
     "express": "^4.19.2",
@@ -52,7 +54,6 @@
     "kuzu": "^0.11.3",
     "lru-cache": "^11.0.0",
     "mnemonist": "^0.39.0",
-    "ora": "^8.0.0",
     "pandemonium": "^2.4.0",
     "tree-sitter": "^0.21.0",
     "tree-sitter-c": "^0.21.0",
@@ -68,6 +69,7 @@
     "uuid": "^13.0.0"
   },
   "devDependencies": {
+    "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
     "@types/node": "^20.0.0",

package/skills/debugging.md

@@ -15,8 +15,8 @@ description: Trace bugs through call chains using knowledge graph
 ## Workflow
 
 ```
-1. gitnexus_search({query: "<error or symptom>"})            → Find related code
-2. gitnexus_explore({name: "<suspect>", type: "symbol"})     → See callers/callees
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
 4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
@@ -27,9 +27,9 @@ description: Trace bugs through call chains using knowledge graph
 
 ```
 - [ ] Understand the symptom (error message, unexpected behavior)
-- [ ] gitnexus_search for error text or related code
-- [ ] Identify the suspect function
-- [ ] gitnexus_explore to see callers and callees
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
 - [ ] Trace execution flow via process resource if applicable
 - [ ] gitnexus_cypher for custom call chain traces if needed
 - [ ] Read source files to confirm root cause
@@ -39,26 +39,27 @@ description: Trace bugs through call chains using knowledge graph
 
 | Symptom | GitNexus Approach |
 |---------|-------------------|
-| Error message | `gitnexus_search` for error text → `explore` throw sites |
-| Wrong return value | `explore` the function → trace callees for data flow |
-| Intermittent failure | `explore` → look for external calls, async deps |
-| Performance issue | `explore` → find symbols with many callers (hot paths) |
-| Recent regression | `gitnexus_impact` on recently changed symbols |
+| Error message | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value | `context` on the function → trace callees for data flow |
+| Intermittent failure | `context` → look for external calls, async deps |
+| Performance issue | `context` → find symbols with many callers (hot paths) |
+| Recent regression | `detect_changes` to see what your changes affect |
 
 ## Tools
 
-**gitnexus_search** — find code related to error:
+**gitnexus_query** — find code related to error:
 ```
-gitnexus_search({query: "payment validation error", depth: "full"})
-→ validatePayment, handlePaymentError, PaymentException
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
 ```
 
-**gitnexus_explore** — full context for a suspect:
+**gitnexus_context** — full context for a suspect:
 ```
-gitnexus_explore({name: "validatePayment", type: "symbol"})
-→ Callers: processCheckout, webhookHandler
-→ Callees: verifyCard, fetchRates (external API!)
-→ Cluster: Payment
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
 ```
 
 **gitnexus_cypher** — custom call chain traces:
@@ -70,11 +71,12 @@ RETURN [n IN nodes(path) | n.name] AS chain
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. gitnexus_search({query: "payment error handling"})
-   → validatePayment, handlePaymentError, PaymentException
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
 
-2. gitnexus_explore({name: "validatePayment", type: "symbol"})
-   → Callees: verifyCard, fetchRates (external API!)
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
 
 3. READ gitnexus://repo/my-app/process/CheckoutFlow
    → Step 3: validatePayment → calls fetchRates (external)