gitnexushub 0.4.5 → 0.7.0

package/hooks/gitnexus-enterprise-hook.cjs

@@ -311,11 +311,103 @@ function httpGetJson(urlStr, headers) {
 }
 
 /**
- * Emit the Claude Code / Cursor / OpenCode hookSpecificOutput envelope.
- * The editor will prepend `message` to the tool's output before handing
- * control back to the model.
+ * Map raw `hook_event_name` strings (as written by each editor) onto
+ * the Claude Code-canonical PascalCase form the rest of this script
+ * uses. Returns null if the event isn't one we handle.
+ *
+ *   Claude Code / OpenCode → "PreToolUse"   / "PostToolUse"   (PascalCase)
+ *   Cursor 2.4+            → "preToolUse"   / "postToolUse"   (camelCase, see cursor.com/docs/hooks)
+ *   Kiro IDE               → "pre-tool-use" / "post-tool-use" (kebab-case, see kiro.dev/docs/hooks/types)
+ *
+ * Three different conventions; one script. Without this normalisation
+ * Cursor and Kiro hooks fire but the script bails on the event check
+ * and emits nothing — which is exactly the bug v0.6.0 shipped with.
+ */
+function normaliseEvent(rawEvent) {
+  if (rawEvent === 'PreToolUse' || rawEvent === 'pre-tool-use' || rawEvent === 'preToolUse') {
+    return 'PreToolUse';
+  }
+  if (
+    rawEvent === 'PostToolUse' ||
+    rawEvent === 'post-tool-use' ||
+    rawEvent === 'postToolUse'
+  ) {
+    return 'PostToolUse';
+  }
+  return null;
+}
+
+/**
+ * Read an explicit agent override from argv. Each hook installer
+ * appends `--agent=<id>` to the spawn command so `/api/activity/*`
+ * captures can split rows by editor (claude-code vs cursor vs
+ * opencode vs kiro). The stdin payload alone can't distinguish
+ * Cursor from Claude Code from OpenCode — they all emit
+ * `hook_event_name: PreToolUse` — so the agent identity has to be
+ * baked in at install time.
+ *
+ * Returns null when the flag isn't present; callers fall back to
+ * stdin-based detection.
+ */
+function parseAgentArg() {
+  for (const arg of process.argv.slice(2)) {
+    const m = arg.match(/^--agent=(.+)$/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/**
+ * Detect which editor invoked us, used to tag /api/activity captures
+ * with the right `agentName`. Priority:
+ *   1. `--agent=<id>` argv flag (set by the hook installer at
+ *      install time — the only reliable way to distinguish editors
+ *      that share the PascalCase MCP convention)
+ *   2. kebab-case `pre-tool-use` / `post-tool-use` event → `kiro`
+ *      (Kiro is the only editor emitting kebab-case)
+ *   3. fallback → `claude-code` (matches the historical hardcoded
+ *      value, so older installs without the argv flag keep working)
+ */
+function detectAgent(rawEvent) {
+  const explicit = parseAgentArg();
+  if (explicit) return explicit;
+  if (rawEvent === 'pre-tool-use' || rawEvent === 'post-tool-use') return 'kiro';
+  if (rawEvent === 'preToolUse' || rawEvent === 'postToolUse') return 'cursor';
+  return 'claude-code';
+}
+
+/**
+ * Normalise the editor-specific tool name onto the Claude Code-
+ * canonical PascalCase shape the rest of this script uses. Cursor
+ * calls the shell tool `Shell` (cursor.com/docs/hooks postToolUse
+ * example), Claude Code / Kiro / OpenCode call it `Bash`. Other
+ * tool names match across editors so far.
+ */
+function normaliseToolName(raw) {
+  if (raw === 'Shell') return 'Bash';
+  return raw || '';
+}
+
+/**
+ * Emit the response in the format the source editor expects. Three
+ * envelopes today, one script:
+ *
+ *   Claude Code / OpenCode → `hookSpecificOutput` envelope
+ *     ({ hookSpecificOutput: { hookEventName, additionalContext } })
+ *   Cursor 2.4+            → `additional_context` (snake_case top-level)
+ *     ({ additional_context: "..." })  see cursor.com/docs/hooks
+ *   Kiro IDE               → plain stdout (kiro.dev/docs/hooks/actions
+ *     "the stdout output of the command is added to the agent's context")
  */
-function sendResponse(event, message) {
+function sendResponse(event, agentName, message) {
+  if (agentName === 'kiro') {
+    process.stdout.write(message + '\n');
+    return;
+  }
+  if (agentName === 'cursor') {
+    process.stdout.write(JSON.stringify({ additional_context: message }) + '\n');
+    return;
+  }
   process.stdout.write(
     JSON.stringify({
       hookSpecificOutput: { hookEventName: event, additionalContext: message },
@@ -323,8 +415,8 @@ function sendResponse(event, message) {
   );
 }
 
-async function handlePreToolUse(input, config, entry) {
-  const toolName = input.tool_name || '';
+async function handlePreToolUse(input, config, entry, agentName) {
+  const toolName = normaliseToolName(input.tool_name);
   if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
 
   const pattern = extractPattern(toolName, input.tool_input || {});
@@ -339,7 +431,7 @@ async function handlePreToolUse(input, config, entry) {
 
   const text = String(res.body.text).trim();
   if (!text) return;
-  sendResponse('PreToolUse', text);
+  sendResponse('PreToolUse', agentName, text);
 }
 
 /**
@@ -368,8 +460,54 @@ function writeMetaCache(repoId, meta) {
   }
 }
 
-async function handlePostToolUse(input, config, entry) {
-  if (input.tool_name !== 'Bash') return;
+/**
+ * Edit-closure capture. After Edit/Write/MultiEdit succeeds in the agent,
+ * fire a fire-and-forget POST telling the hub which file was edited. The
+ * hub correlates against recent MCP result_symbols to record whether
+ * GitNexus drove this edit (the strongest possible quality signal).
+ *
+ * Best-effort: never blocks the editor, never re-tries, swallows errors.
+ */
+async function handleEditObservation(input, config, entry, agentName) {
+  const tool = normaliseToolName(input.tool_name);
+  if (tool !== 'Edit' && tool !== 'Write' && tool !== 'MultiEdit') return;
+
+  // Only fire when the edit succeeded. Some editors omit exit info; treat
+  // missing as success so we don't drop legitimate edits.
+  const out = input.tool_output;
+  if (out && out.exit_code !== undefined && out.exit_code !== 0) return;
+  if (out && out.error) return;
+
+  const filePath = (input.tool_input && input.tool_input.file_path) || '';
+  if (!filePath || typeof filePath !== 'string') return;
+
+  // Best-effort line extraction. Edit tool input often carries a `line`
+  // hint; MultiEdit usually doesn't.
+  const line = Number.isInteger(input.tool_input && input.tool_input.line)
+    ? Number(input.tool_input.line)
+    : null;
+
+  await httpPostJson(`${config.hubUrl}/api/activity/edit-observed`, authHeaders(config), {
+    sessionId: input.session_id || null,
+    repoId: entry.hubRepoId,
+    filePath,
+    line,
+    tool,
+    agentName,
+  });
+}
+
+async function handlePostToolUse(input, config, entry, agentName) {
+  const toolName = normaliseToolName(input.tool_name);
+
+  // Fan out: edit observations are independent of the git-staleness check.
+  // Both run on PostToolUse; we don't want one to block the other.
+  if (toolName === 'Edit' || toolName === 'Write' || toolName === 'MultiEdit') {
+    await handleEditObservation(input, config, entry, agentName);
+    return;
+  }
+
+  if (toolName !== 'Bash') return;
   const cmd = (input.tool_input && input.tool_input.command) || '';
   if (!/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(cmd)) return;
 
@@ -407,20 +545,114 @@ async function handlePostToolUse(input, config, entry) {
   const shortOld = meta.last_commit ? String(meta.last_commit).slice(0, 7) : 'none';
   sendResponse(
     'PostToolUse',
+    agentName,
     `GitNexus index is stale (last indexed: ${shortOld}). Run \`gnx sync\` to update.`,
   );
 }
 
+// ─── Soft-nudge upgrade flow ──────────────────────────────────────────────
+//
+// Hook version is read from the bundled package.json. Once per local day
+// we hit /api/activity/hook-version and compare. If the published latest
+// is ahead of ours, we print a single stderr line — never blocks editing.
+// State is held in ~/.gitnexus/hook-version-check.json so we don't spam
+// the hub on every PreToolUse.
+
+const VERSION_CHECK_FILE = path.join(os.homedir(), '.gitnexus', 'hook-version-check.json');
+const VERSION_CHECK_TTL_MS = 24 * 60 * 60 * 1000; // once per day
+
+function readPackageVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+function readVersionCheckState() {
+  try {
+    const stat = fs.statSync(VERSION_CHECK_FILE);
+    if (Date.now() - stat.mtimeMs > VERSION_CHECK_TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(VERSION_CHECK_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeVersionCheckState(state) {
+  try {
+    fs.mkdirSync(path.dirname(VERSION_CHECK_FILE), { recursive: true });
+    fs.writeFileSync(VERSION_CHECK_FILE, JSON.stringify(state));
+  } catch {
+    /* ignore — best effort */
+  }
+}
+
+/**
+ * Compare two semver strings (major.minor.patch only — pre-releases ignored).
+ * Returns -1 if a < b, 0 if equal, 1 if a > b. Defensive against malformed.
+ */
+function compareSemver(a, b) {
+  const pa = String(a || '0.0.0')
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '0.0.0')
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+async function maybeNudgeUpgrade(config) {
+  const local = readPackageVersion();
+  if (!local) return;
+
+  const cached = readVersionCheckState();
+  if (cached && compareSemver(local, cached.latestVersion) >= 0) return;
+
+  const res = await httpGetJson(`${config.hubUrl}/api/activity/hook-version`, authHeaders(config));
+  if (!res || res.status !== 200 || !res.body) return;
+
+  const latest = res.body.latestVersion;
+  if (!latest) return;
+
+  writeVersionCheckState({ latestVersion: latest, checkedAt: Date.now() });
+
+  if (compareSemver(local, latest) < 0) {
+    const note = res.body.notes ? ` — ${res.body.notes}` : '';
+    process.stderr.write(
+      `[gitnexus] connect hook ${local} → update available (${latest})${note}. ` +
+        `Run: npm update -g gitnexushub\n`,
+    );
+  }
+}
+
 async function main() {
   if (process.env.GITNEXUS_NO_AUGMENT === '1') return;
 
   const input = readInput();
-  const event = input.hook_event_name;
-  if (event !== 'PreToolUse' && event !== 'PostToolUse') return;
+  const rawEvent = input.hook_event_name;
+  const event = normaliseEvent(rawEvent);
+  if (!event) return;
+
+  const agentName = detectAgent(rawEvent);
 
   const config = readConfig();
   if (!config || !config.hubToken || !config.hubUrl) return;
 
+  // Once-per-day soft-nudge if we're behind. Best-effort, won't block.
+  // Skipped entirely on PostToolUse so the editor's response path stays
+  // hot — PreToolUse fires more often, so the check still happens daily.
+  if (event === 'PreToolUse') {
+    maybeNudgeUpgrade(config).catch(() => {});
+  }
+
   const entries = readRegistry();
   const cwd = input.cwd || process.cwd();
   const entry = resolveCwdToRepo(cwd, entries);
@@ -428,9 +660,9 @@ async function main() {
 
   try {
     if (event === 'PreToolUse') {
-      await handlePreToolUse(input, config, entry);
+      await handlePreToolUse(input, config, entry, agentName);
     } else {
-      await handlePostToolUse(input, config, entry);
+      await handlePostToolUse(input, config, entry, agentName);
     }
   } catch (err) {
     if (process.env.GITNEXUS_DEBUG) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexushub",
-  "version": "0.4.5",
+  "version": "0.7.0",
   "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-debugging.md

@@ -1,89 +1,89 @@
----
-name: gitnexus-debugging
-description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
----
-
-# Debugging with GitNexus
-
-## When to Use
-
-- "Why is this function failing?"
-- "Trace where this error comes from"
-- "Who calls this method?"
-- "This endpoint returns 500"
-- Investigating bugs, errors, or unexpected behavior
-
-## Workflow
-
-```
-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
-```
-
-> If "Index is stale" → trigger re-indexing from the Hub dashboard.
-
-## Checklist
-
-```
-- [ ] Understand the symptom (error message, unexpected behavior)
-- [ ] 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
-```
-
-## Debugging Patterns
-
-| Symptom              | GitNexus Approach                                          |
-| -------------------- | ---------------------------------------------------------- |
-| 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    | `impact` on changed functions → check what callers broke   |
-
-## Tools
-
-**gitnexus_query** — find code related to error:
-
-```
-gitnexus_query({query: "payment validation error"})
-→ Processes: CheckoutFlow, ErrorHandling
-→ Symbols: validatePayment, handlePaymentError, PaymentException
-```
-
-**gitnexus_context** — full context for a suspect:
-
-```
-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:
-
-```cypher
-MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
-RETURN [n IN nodes(path) | n.name] AS chain
-```
-
-## Example: "Payment endpoint returns 500 intermittently"
-
-```
-1. gitnexus_query({query: "payment error handling"})
-   → Processes: CheckoutFlow, ErrorHandling
-   → Symbols: validatePayment, handlePaymentError
-
-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)
-
-4. Root cause: fetchRates calls external API without proper timeout
-```
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+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
+```
+
+> If "Index is stale" → trigger re-indexing from the Hub dashboard.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] 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
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| 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    | `impact` on changed functions → check what callers broke   |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+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:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+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)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

package/skills/gitnexus-exploring.md

@@ -1,78 +1,78 @@
----
-name: gitnexus-exploring
-description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
----
-
-# Exploring Codebases with GitNexus
-
-## When to Use
-
-- "How does authentication work?"
-- "What's the project structure?"
-- "Show me the main components"
-- "Where is the database logic?"
-- Understanding code you haven't seen before
-
-## Workflow
-
-```
-1. READ gitnexus://repos                          → Discover indexed repos
-2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
-4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
-5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
-```
-
-> If step 2 says "Index is stale" → trigger re-indexing from the Hub dashboard.
-
-## Checklist
-
-```
-- [ ] READ gitnexus://repo/{name}/context
-- [ ] gitnexus_query for the concept you want to understand
-- [ ] Review returned processes (execution flows)
-- [ ] gitnexus_context on key symbols for callers/callees
-- [ ] READ process resource for full execution traces
-- [ ] Read source files for implementation details
-```
-
-## Resources
-
-| Resource                                | What you get                                            |
-| --------------------------------------- | ------------------------------------------------------- |
-| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
-| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
-| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
-| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
-
-## Tools
-
-**gitnexus_query** — find execution flows related to a concept:
-
-```
-gitnexus_query({query: "payment processing"})
-→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
-→ Symbols grouped by flow with file locations
-```
-
-**gitnexus_context** — 360-degree view of a symbol:
-
-```
-gitnexus_context({name: "validateUser"})
-→ Incoming calls: loginHandler, apiMiddleware
-→ Outgoing calls: checkToken, getUserById
-→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
-```
-
-## Example: "How does payment processing work?"
-
-```
-1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. gitnexus_query({query: "payment processing"})
-   → CheckoutFlow: processPayment → validateCard → chargeStripe
-   → RefundFlow: initiateRefund → calculateRefund → processRefund
-3. gitnexus_context({name: "processPayment"})
-   → Incoming: checkoutHandler, webhookHandler
-   → Outgoing: validateCard, chargeStripe, saveTransaction
-4. Read src/payments/processor.ts for implementation details
-```
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → trigger re-indexing from the Hub dashboard.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```