Merge remote-tracking branch 'origin/main' into pr-170-merge

claude-code-action fetches branches by name from origin, which fails
for fork PRs since the branch only exists on the fork remote. Work
around by detecting fork PRs and temporarily pushing the branch to
origin before the action runs, then cleaning up afterwards.

Also changed trigger from automatic (every push) to on-demand only
(label "claude-review" or comment "@claude" / "/review").

.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "gitnexus-marketplace",
+  "owner": {
+    "name": "GitNexus",
+    "email": "nico@gitnexus.dev"
+  },
+  "metadata": {
+    "description": "Code intelligence powered by a knowledge graph — execution flows, blast radius, and semantic search",
+    "homepage": "https://github.com/nicosxt/gitnexus"
+  },
+  "plugins": [
+    {
+      "name": "gitnexus",
+      "version": "1.3.3",
+      "source": "./gitnexus-claude-plugin",
+      "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
+    }
+  ]
+}

.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus 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.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus 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.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus 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.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

.claude/skills/gitnexus/gitnexus-debugging/SKILL.md

@@ -0,0 +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" → run `npx gitnexus analyze` in terminal.
+
+## 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    | `detect_changes` to see what your changes affect           |
+
+## 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
+```

.claude/skills/gitnexus/gitnexus-exploring/SKILL.md

@@ -0,0 +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" → run `npx gitnexus analyze` in terminal.
+
+## 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
+```

.claude/skills/gitnexus/gitnexus-guide/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+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 gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```

.claude/skills/gitnexus/gitnexus-pr-review/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: gitnexus-pr-review
+description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
+---
+
+# PR Review with GitNexus
+
+## When to Use
+
+- "Review this PR"
+- "What does PR #42 change?"
+- "Is this safe to merge?"
+- "What's the blast radius of this PR?"
+- "Are there missing tests for this PR?"
+- Reviewing someone else's code changes before merge
+
+## Workflow
+
+```
+1. gh pr diff <number>                                    → Get the raw diff
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+3. For each changed symbol:
+   gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
+4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
+5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+6. Summarize findings with risk assessment
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.
+
+## Checklist
+
+```
+- [ ] Fetch PR diff (gh pr diff or git diff base...head)
+- [ ] gitnexus_detect_changes to map changes to affected execution flows
+- [ ] gitnexus_impact on each non-trivial changed symbol
+- [ ] Review d=1 items (WILL BREAK) — are callers updated?
+- [ ] gitnexus_context on key changed symbols to understand full picture
+- [ ] Check if affected processes have test coverage
+- [ ] Assess overall risk level
+- [ ] Write review summary with findings
+```
+
+## Review Dimensions
+
+| Dimension | How GitNexus Helps |
+| --- | --- |
+| **Correctness** | `context` shows callers — are they all compatible with the change? |
+| **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
+| **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
+| **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
+| **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
+
+## Risk Assessment
+
+| Signal | Risk |
+| --- | --- |
+| Changes touch <3 symbols, 0-1 processes | LOW |
+| Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
+| Changes touch >10 symbols or many processes | HIGH |
+| Changes touch auth, payments, or data integrity code | CRITICAL |
+| d=1 callers exist outside the PR diff | Potential breakage — flag it |
+
+## Tools
+
+**gitnexus_detect_changes** — map PR diff to affected execution flows:
+
+```
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+
+→ Changed: 8 symbols in 4 files
+→ Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Risk: MEDIUM
+```
+
+**gitnexus_impact** — blast radius per changed symbol:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream"})
+
+→ d=1 (WILL BREAK):
+  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
+  - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_impact with tests** — check test coverage:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
+
+→ Tests that cover this symbol:
+  - validatePayment.test.ts [direct]
+  - checkout.integration.test.ts [via processCheckout]
+```
+
+**gitnexus_context** — understand a changed symbol's role:
+
+```
+gitnexus_context({name: "validatePayment"})
+
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates
+→ Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)
+```
+
+## Example: "Review PR #42"
+
+```
+1. gh pr diff 42 > /tmp/pr42.diff
+   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
+
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   → Changed symbols: validatePayment, PaymentInput, formatAmount
+   → Affected processes: CheckoutFlow, RefundFlow
+   → Risk: MEDIUM
+
+3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
+   → d=1: processCheckout, webhookHandler (WILL BREAK)
+   → webhookHandler is NOT in the PR diff — potential breakage!
+
+4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
+   → d=1: validatePayment (in PR), createPayment (NOT in PR)
+   → createPayment uses the old PaymentInput shape — breaking change!
+
+5. gitnexus_context({name: "formatAmount"})
+   → Called by 12 functions — but change is backwards-compatible (added optional param)
+
+6. Review summary:
+   - MEDIUM risk — 3 changed symbols affect 2 execution flows
+   - BUG: webhookHandler calls validatePayment but isn't updated for new signature
+   - BUG: createPayment depends on PaymentInput type which changed
+   - OK: formatAmount change is backwards-compatible
+   - Tests: checkout.test.ts covers processCheckout path, but no webhook test
+```
+
+## Review Output Format
+
+Structure your review as:
+
+```markdown
+## PR Review: <title>
+
+**Risk: LOW / MEDIUM / HIGH / CRITICAL**
+
+### Changes Summary
+- <N> symbols changed across <M> files
+- <P> execution flows affected
+
+### Findings
+1. **[severity]** Description of finding
+   - Evidence from GitNexus tools
+   - Affected callers/flows
+
+### Missing Coverage
+- Callers not updated in PR: ...
+- Untested flows: ...
+
+### Recommendation
+APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+```

.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

.cursorrules

@@ -0,0 +1,5 @@
+# AI Agent Rules
+
+Follow .gitnexus/RULES.md for all project context and coding guidelines.
+
+This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices.

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: abhigyanpatwari

.github/actions/setup-gitnexus/action.yml

@@ -0,0 +1,28 @@
+name: Setup GitNexus
+description: Setup Node.js 20, install dependencies, and optionally build
+
+inputs:
+  build:
+    description: Whether to run npm run build after install
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with:
+        node-version: 20
+        cache: npm
+        cache-dependency-path: gitnexus/package-lock.json
+
+    - name: Install dependencies
+      run: npm ci
+      shell: bash
+      working-directory: gitnexus
+
+    - name: Build
+      if: ${{ inputs.build == 'true' }}
+      run: npm run build
+      shell: bash
+      working-directory: gitnexus

.github/release.yml

@@ -0,0 +1,45 @@
+changelog:
+  exclude:
+    labels:
+      - chore
+    authors:
+      - dependabot
+      - dependabot[bot]
+  categories:
+    - title: "\U0001F6A8 Security"
+      labels:
+        - security
+    - title: "\U0001F4A5 Breaking Changes"
+      labels:
+        - breaking
+    - title: "\U0001F680 Features"
+      labels:
+        - enhancement
+    - title: "\U0001F41B Bug Fixes"
+      labels:
+        - bug
+    - title: "\U0001F3CE\uFE0F Performance"
+      labels:
+        - performance
+    - title: "\U0001F9EA Tests"
+      labels:
+        - test
+    - title: "\U0001F504 Refactoring"
+      labels:
+        - refactor
+    - title: "\U0001F477 CI/CD"
+      labels:
+        - ci
+    - title: "\U0001F4E6 Dependencies"
+      labels:
+        - dependencies
+    - title: "\U0001F4DD Other Changes"
+      labels:
+        - "*"
+      exclude:
+        labels:
+          - dependencies
+          - ci
+          - test
+          - refactor
+          - chore

.github/workflows/ci-integration.yml

@@ -0,0 +1,173 @@
+name: Integration Tests
+
+on:
+  workflow_call:
+    inputs:
+      collect-coverage:
+        description: 'Whether to run the coverage collection job (only needed for PR reports)'
+        required: false
+        default: true
+        type: boolean
+
+jobs:
+  # ── Integration test matrix ─────────────────────────────────────────
+  # Each test-group runs on a SEPARATE runner per OS, giving full process
+  # isolation for the KuzuDB native C++ addon.
+  # 3 OS x 4 groups = 12 parallel jobs.
+  #
+  # Groups:
+  #   kuzu-db    — 7 files using withTestKuzuDB / kuzu-adapter (native addon)
+  #                Each file runs as its own `vitest run` invocation for full
+  #                process isolation. KuzuDB's native N-API addon registers
+  #                persistent handles that prevent fork workers from exiting
+  #                on Linux, and its C++ destructors segfault during
+  #                process.exit(). Running each file in its own process lets
+  #                the OS reclaim all resources cleanly.
+  #   pipeline   — 3 files: ingestion pipeline + csv, each creates own temp DB
+  #   e2e        — 2 files: child-process only (spawnSync), no in-process kuzu
+  #   standalone — 4 files: pure logic, no kuzu, no child processes
+  test-matrix:
+    name: integration (${{ matrix.os }} / ${{ matrix.test-group }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        test-group: [kuzu-db, pipeline, e2e, standalone]
+        include:
+          - test-group: kuzu-db
+            # Marker — actual files are listed in the run step below
+            test-glob: ''
+          - test-group: pipeline
+            test-glob: >-
+              test/integration/pipeline.test.ts
+              test/integration/csv-pipeline.test.ts
+              test/integration/parsing.test.ts
+          - test-group: e2e
+            test-glob: >-
+              test/integration/cli-e2e.test.ts
+              test/integration/hooks-e2e.test.ts
+          - test-group: standalone
+            test-glob: >-
+              test/integration/filesystem-walker.test.ts
+              test/integration/enrichment.test.ts
+              test/integration/tree-sitter-languages.test.ts
+              test/integration/worker-pool.test.ts
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      # kuzu-db: run each file in its own vitest process for full isolation.
+      # KuzuDB's native addon hangs fork workers on Linux — process isolation
+      # is the only reliable fix boundary.
+      - name: Run integration tests — kuzu-db (process-isolated)
+        if: matrix.test-group == 'kuzu-db'
+        working-directory: gitnexus
+        shell: bash
+        run: |
+          set -e
+          files=(
+            test/integration/kuzu-core-adapter.test.ts
+            test/integration/kuzu-pool.test.ts
+            test/integration/local-backend.test.ts
+            test/integration/local-backend-calltool.test.ts
+            test/integration/search-core.test.ts
+            test/integration/search-pool.test.ts
+            test/integration/augmentation.test.ts
+          )
+          exit_code=0
+          for f in "${files[@]}"; do
+            echo "::group::$f"
+            if ! npx vitest run --reporter=verbose --pool=forks "$f"; then
+              exit_code=1
+              echo "::error::Test file failed: $f"
+            fi
+            echo "::endgroup::"
+          done
+          exit $exit_code
+
+      # Non-kuzu groups: run all files in a single vitest invocation
+      - name: Run integration tests — ${{ matrix.test-group }}
+        if: matrix.test-group != 'kuzu-db'
+        shell: bash
+        env:
+          TEST_GLOB: ${{ matrix.test-glob }}
+        run: npx vitest run --reporter=verbose $TEST_GLOB
+        working-directory: gitnexus
+
+  # ── Coverage collection (ubuntu only) ─────────────────────────────────
+  # Runs non-kuzu integration tests with coverage enabled so the PR report
+  # can merge integration + unit coverage for a combined view.
+  # kuzu-db tests are excluded because each file must run in its own vitest
+  # process (native addon isolation) which prevents single-run coverage merge.
+  coverage:
+    name: integration (ubuntu / coverage)
+    if: inputs.collect-coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Run integration tests with coverage
+        working-directory: gitnexus
+        run: >-
+          npx vitest run
+          --reporter=default
+          --reporter=json
+          --outputFile=integration-results.json
+          --coverage
+          --coverage.reporter=json-summary
+          --coverage.reporter=json
+          --coverage.reporter=text
+          --coverage.thresholdAutoUpdate=false
+          --coverage.reportOnFailure=true
+          --coverage.thresholds.statements=0
+          --coverage.thresholds.branches=0
+          --coverage.thresholds.functions=0
+          --coverage.thresholds.lines=0
+          test/integration/pipeline.test.ts
+          test/integration/csv-pipeline.test.ts
+          test/integration/parsing.test.ts
+          test/integration/cli-e2e.test.ts
+          test/integration/hooks-e2e.test.ts
+          test/integration/filesystem-walker.test.ts
+          test/integration/enrichment.test.ts
+          test/integration/tree-sitter-languages.test.ts
+          test/integration/worker-pool.test.ts
+
+      - name: Upload integration coverage
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: integration-reports
+          path: |
+            gitnexus/coverage/coverage-summary.json
+            gitnexus/coverage/coverage-final.json
+            gitnexus/integration-results.json
+          retention-days: 5
+
+  # ── Unified status gate ──────────────────────────────────────────────
+  # Branch protection should require THIS job, not the matrix jobs directly.
+  # ci.yml's needs.integration.result aggregates through this gate.
+  status:
+    name: integration (all groups)
+    needs: test-matrix
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check all matrix jobs passed
+        shell: bash
+        env:
+          RESULT: ${{ needs.test-matrix.result }}
+        run: |
+          if [[ "$RESULT" != "success" ]]; then
+            echo "::error::Integration matrix failed or cancelled: $RESULT"
+            exit 1
+          fi

.github/workflows/ci-quality.yml

@@ -0,0 +1,14 @@
+name: Quality Checks
+
+on:
+  workflow_call:
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+      - run: npx tsc --noEmit
+        working-directory: gitnexus

.github/workflows/ci-report.yml

@@ -0,0 +1,432 @@
+name: CI Report
+
+# Triggered after the CI workflow completes.  Because workflow_run
+# always runs code from the *default branch*, it receives a read/write
+# GITHUB_TOKEN — even when the triggering PR comes from a fork.
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  actions: read        # needed to list/download workflow run artifacts
+  contents: read       # needed for sparse checkout of vitest.config.ts
+  pull-requests: write # needed to post sticky PR comment
+
+jobs:
+  pr-report:
+    name: PR Report
+    # Only run for pull-request CI runs
+    if: >-
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion != 'cancelled'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # ── Download artifacts from the CI run ────────────────────────
+      - name: Download artifacts
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const runId = context.payload.workflow_run.id;
+
+            const allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: runId,
+            });
+
+            async function downloadArtifact(name, dest) {
+              const match = allArtifacts.data.artifacts.find(a => a.name === name);
+              if (!match) {
+                core.warning(`Artifact "${name}" not found`);
+                return false;
+              }
+              const zip = await github.rest.actions.downloadArtifact({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                artifact_id: match.id,
+                archive_format: 'zip',
+              });
+              fs.mkdirSync(dest, { recursive: true });
+              fs.writeFileSync(path.join(dest, `${name}.zip`), Buffer.from(zip.data));
+              return true;
+            }
+
+            const temp = process.env.RUNNER_TEMP;
+            await downloadArtifact('pr-meta', path.join(temp, 'dl'));
+            await downloadArtifact('test-reports', path.join(temp, 'dl'));
+            await downloadArtifact('integration-reports', path.join(temp, 'dl'));
+
+      - name: Extract artifacts
+        shell: bash
+        run: |
+          cd "$RUNNER_TEMP/dl"
+          # Extract each artifact into its own directory to avoid filename collisions
+          for z in *.zip; do
+            [ -f "$z" ] || continue
+            name="${z%.zip}"
+            mkdir -p "$RUNNER_TEMP/artifacts/$name"
+            unzip -o "$z" -d "$RUNNER_TEMP/artifacts/$name"
+          done
+
+      - name: Read PR metadata
+        id: meta
+        shell: bash
+        run: |
+          DIR="$RUNNER_TEMP/artifacts/pr-meta"
+          if [ ! -f "$DIR/pr_number" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "::warning::pr_number artifact missing — skipping report"
+            exit 0
+          fi
+
+          # Validate PR number is a positive integer (artifact comes from
+          # untrusted fork code, so treat contents defensively).
+          PR_NUM=$(cat "$DIR/pr_number" | tr -d '[:space:]')
+          if ! [[ "$PR_NUM" =~ ^[0-9]+$ ]]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "::error::Invalid PR number in artifact: '$PR_NUM'"
+            exit 0
+          fi
+
+          echo "skip=false"              >> "$GITHUB_OUTPUT"
+          echo "pr_number=$PR_NUM"       >> "$GITHUB_OUTPUT"
+          # Validate job-result strings against known GitHub Actions values.
+          # Artifact contents come from the PR workflow (potentially untrusted
+          # fork code), so we whitelist to prevent newline injection into
+          # GITHUB_OUTPUT.
+          validate_result() {
+            local val
+            val=$(cat "$1" | tr -d '[:space:]')
+            case "$val" in
+              success|failure|cancelled|skipped) echo "$val" ;;
+              *) echo "unknown" ;;
+            esac
+          }
+
+          echo "quality=$(validate_result "$DIR/quality_result")"        >> "$GITHUB_OUTPUT"
+          echo "unit=$(validate_result "$DIR/unit_result")"              >> "$GITHUB_OUTPUT"
+          echo "integration=$(validate_result "$DIR/integration_result")" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout (for vitest config)
+        if: steps.meta.outputs.skip != 'true'
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          sparse-checkout: gitnexus/vitest.config.ts
+          sparse-checkout-cone-mode: false
+
+      # ── Merge coverage from unit + integration ─────────────────────
+      - name: Setup Node.js
+        if: steps.meta.outputs.skip != 'true'
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 20
+
+      - name: Install coverage merge tools
+        if: steps.meta.outputs.skip != 'true'
+        run: npm install --no-save istanbul-lib-coverage istanbul-lib-report istanbul-reports
+
+      - name: Merge coverage reports
+        if: steps.meta.outputs.skip != 'true'
+        id: coverage
+        shell: bash
+        run: |
+          DIR="$RUNNER_TEMP/artifacts"
+          UNIT_COV=$(find "$DIR/test-reports" -name "coverage-final.json" -type f 2>/dev/null | head -1)
+          INTEG_COV=$(find "$DIR/integration-reports" -name "coverage-final.json" -type f 2>/dev/null | head -1)
+          MERGED_DIR="$RUNNER_TEMP/merged-coverage"
+          mkdir -p "$MERGED_DIR"
+
+          if [ -n "$UNIT_COV" ] && [ -n "$INTEG_COV" ]; then
+            echo "has_merged=true" >> "$GITHUB_OUTPUT"
+            # Merge using Node.js + istanbul-lib-coverage.
+            # Paths are passed via env vars to avoid shell interpolation
+            # inside the script string.
+            UNIT_COV_PATH="$UNIT_COV" \
+            INTEG_COV_PATH="$INTEG_COV" \
+            MERGED_OUT_DIR="$MERGED_DIR" \
+            node -e "
+              const libCoverage = require('istanbul-lib-coverage');
+              const libReport = require('istanbul-lib-report');
+              const reports = require('istanbul-reports');
+              const fs = require('fs');
+
+              const map = libCoverage.createCoverageMap({});
+              map.merge(JSON.parse(fs.readFileSync(process.env.UNIT_COV_PATH, 'utf8')));
+              map.merge(JSON.parse(fs.readFileSync(process.env.INTEG_COV_PATH, 'utf8')));
+
+              const context = libReport.createContext({
+                coverageMap: map,
+                dir: process.env.MERGED_OUT_DIR,
+              });
+              reports.create('json-summary').execute(context);
+              console.log('Merged coverage written to ' + process.env.MERGED_OUT_DIR + '/coverage-summary.json');
+            "
+          elif [ -n "$UNIT_COV" ]; then
+            echo "has_merged=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::Integration coverage not found — using unit coverage only"
+          else
+            echo "has_merged=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::No coverage data found"
+          fi
+
+      - name: Build report
+        if: steps.meta.outputs.skip != 'true'
+        id: report
+        shell: bash
+        env:
+          QUALITY: ${{ steps.meta.outputs.quality }}
+          UNIT: ${{ steps.meta.outputs.unit }}
+          INTEG: ${{ steps.meta.outputs.integration }}
+          HAS_MERGED: ${{ steps.coverage.outputs.has_merged }}
+          RUN_URL: ${{ github.event.workflow_run.html_url }}
+        run: |
+          DIR="$RUNNER_TEMP/artifacts"
+          MERGED_DIR="$RUNNER_TEMP/merged-coverage"
+
+          # ── Helper: read coverage summary into prefixed vars ──
+          # Uses printf -v for safe variable assignment (no eval).
+          read_cov() {
+            local prefix=$1 file=$2
+            if [ -n "$file" ] && [ -f "$file" ]; then
+              local val
+              val=$(jq -r '.total.statements.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_STMTS" '%s' "$val"
+              val=$(jq -r '.total.branches.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_BRANCH" '%s' "$val"
+              val=$(jq -r '.total.functions.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_FUNCS" '%s' "$val"
+              val=$(jq -r '.total.lines.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_LINES" '%s' "$val"
+              val=$(jq -r '"\(.total.statements.covered)/\(.total.statements.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_STMTS_COV" '%s' "$val"
+              val=$(jq -r '"\(.total.branches.covered)/\(.total.branches.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_BRANCH_COV" '%s' "$val"
+              val=$(jq -r '"\(.total.functions.covered)/\(.total.functions.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_FUNCS_COV" '%s' "$val"
+              val=$(jq -r '"\(.total.lines.covered)/\(.total.lines.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_LINES_COV" '%s' "$val"
+              return 0
+            else
+              printf -v "${prefix}_STMTS" '%s' "N/A"
+              printf -v "${prefix}_BRANCH" '%s' "N/A"
+              printf -v "${prefix}_FUNCS" '%s' "N/A"
+              printf -v "${prefix}_LINES" '%s' "N/A"
+              printf -v "${prefix}_STMTS_COV" '%s' ""
+              printf -v "${prefix}_BRANCH_COV" '%s' ""
+              printf -v "${prefix}_FUNCS_COV" '%s' ""
+              printf -v "${prefix}_LINES_COV" '%s' ""
+              return 1
+            fi
+          }
+
+          # ── Read all three coverage reports ──
+          UNIT_SUMMARY=$(find "$DIR/test-reports" -name "coverage-summary.json" -type f 2>/dev/null | head -1)
+          INTEG_SUMMARY=$(find "$DIR/integration-reports" -name "coverage-summary.json" -type f 2>/dev/null | head -1)
+          MERGED_SUMMARY="$MERGED_DIR/coverage-summary.json"
+
+          read_cov "U" "$UNIT_SUMMARY"
+          HAS_UNIT=$?
+          read_cov "I" "$INTEG_SUMMARY"
+          HAS_INTEG=$?
+          read_cov "M" "$MERGED_SUMMARY"
+
+          # ── Locate test results (unit) ──
+          RESULTS_FILE=$(find "$DIR/test-reports" -name "test-results.json" -type f 2>/dev/null | head -1)
+          INTEG_RESULTS=$(find "$DIR/integration-reports" -name "integration-results.json" -type f 2>/dev/null | head -1)
+
+          if [ -n "$RESULTS_FILE" ]; then
+            U_TOTAL=$(jq -r '.numTotalTests' "$RESULTS_FILE" 2>/dev/null || echo 0)
+            U_PASSED=$(jq -r '.numPassedTests' "$RESULTS_FILE" 2>/dev/null || echo 0)
+            U_FAILED=$(jq -r '.numFailedTests' "$RESULTS_FILE" 2>/dev/null || echo 0)
+            U_SKIPPED=$(jq -r '.numPendingTests' "$RESULTS_FILE" 2>/dev/null || echo 0)
+            U_SUITES=$(jq -r '.numTotalTestSuites' "$RESULTS_FILE" 2>/dev/null || echo 0)
+            U_DURATION=$(jq -r '((.testResults | map(.endTime) | max) - (.startTime)) / 1000 | floor' "$RESULTS_FILE" 2>/dev/null || echo 0)
+          else
+            U_TOTAL=0; U_PASSED=0; U_FAILED=0; U_SKIPPED=0; U_SUITES=0; U_DURATION=0
+          fi
+
+          if [ -n "$INTEG_RESULTS" ]; then
+            I_TOTAL=$(jq -r '.numTotalTests' "$INTEG_RESULTS" 2>/dev/null || echo 0)
+            I_PASSED=$(jq -r '.numPassedTests' "$INTEG_RESULTS" 2>/dev/null || echo 0)
+            I_FAILED=$(jq -r '.numFailedTests' "$INTEG_RESULTS" 2>/dev/null || echo 0)
+            I_SKIPPED=$(jq -r '.numPendingTests' "$INTEG_RESULTS" 2>/dev/null || echo 0)
+            I_SUITES=$(jq -r '.numTotalTestSuites' "$INTEG_RESULTS" 2>/dev/null || echo 0)
+            I_DURATION=$(jq -r '((.testResults | map(.endTime) | max) - (.startTime)) / 1000 | floor' "$INTEG_RESULTS" 2>/dev/null || echo 0)
+          else
+            I_TOTAL=0; I_PASSED=0; I_FAILED=0; I_SKIPPED=0; I_SUITES=0; I_DURATION=0
+          fi
+
+          # ── Sum test results ──
+          TOTAL=$((U_TOTAL + I_TOTAL))
+          PASSED=$((U_PASSED + I_PASSED))
+          FAILED=$((U_FAILED + I_FAILED))
+          SKIPPED=$((U_SKIPPED + I_SKIPPED))
+          SUITES=$((U_SUITES + I_SUITES))
+          DURATION=$((U_DURATION + I_DURATION))
+
+          # ── Coverage thresholds (read from vitest.config.ts) ──
+          if [ -f gitnexus/vitest.config.ts ]; then
+            THRESH_STMTS=$(grep -oP 'statements:\s*\K[0-9]+' gitnexus/vitest.config.ts || echo 0)
+            THRESH_BRANCH=$(grep -oP 'branches:\s*\K[0-9]+' gitnexus/vitest.config.ts || echo 0)
+            THRESH_FUNCS=$(grep -oP 'functions:\s*\K[0-9]+' gitnexus/vitest.config.ts || echo 0)
+            THRESH_LINES=$(grep -oP 'lines:\s*\K[0-9]+' gitnexus/vitest.config.ts || echo 0)
+          else
+            THRESH_STMTS=0; THRESH_BRANCH=0; THRESH_FUNCS=0; THRESH_LINES=0
+          fi
+
+          # ── Status helpers ──
+          status_icon() {
+            case "$1" in
+              success) echo "✅" ;;
+              failure) echo "❌" ;;
+              cancelled) echo "⏭️" ;;
+              *) echo "❓" ;;
+            esac
+          }
+
+          cov_bar() {
+            local pct=$1 thresh=$2
+            if [ "$pct" = "N/A" ]; then echo "—"; return; fi
+            local filled
+            filled=$(awk "BEGIN { printf \"%d\", $pct / 5 }")
+            (( filled < 0 )) && filled=0
+            (( filled > 20 )) && filled=20
+            local empty=$((20 - filled))
+            local bar=""
+            for ((i=0; i<filled; i++)); do bar+="█"; done
+            for ((i=0; i<empty; i++)); do bar+="░"; done
+            if [ "$(awk "BEGIN { print ($pct >= $thresh) ? 1 : 0 }")" = "1" ]; then
+              echo "🟢 ${bar}"
+            else
+              echo "🔴 ${bar}"
+            fi
+          }
+
+          # ── Overall status ──
+          if [[ "$QUALITY" == "success" && "$UNIT" == "success" && "$INTEG" == "success" ]]; then
+            OVERALL="✅ **All checks passed**"
+          else
+            OVERALL="❌ **Some checks failed**"
+          fi
+
+          # ── Build markdown ──
+          {
+            echo "body<<GITNEXUS_CI_REPORT_EOF_7f3a"
+            echo "## CI Report"
+            echo ""
+            echo "${OVERALL}"
+            echo ""
+            echo "### Pipeline Status"
+            echo ""
+            echo "| Stage | Status | Details |"
+            echo "|-------|--------|---------|"
+            echo "| $(status_icon "$QUALITY") Typecheck | \`${QUALITY}\` | tsc --noEmit |"
+            echo "| $(status_icon "$UNIT") Unit Tests | \`${UNIT}\` | 3 platforms |"
+            echo "| $(status_icon "$INTEG") Integration | \`${INTEG}\` | 3 OS x 4 groups = 12 jobs |"
+            echo ""
+
+            if [ "$TOTAL" -gt 0 ] 2>/dev/null; then
+              echo "### Test Results"
+              echo ""
+              if [ "$FAILED" = "0" ]; then
+                echo "✅ **${PASSED}** passed"
+              else
+                echo "❌ **${FAILED}** failed / **${PASSED}** passed"
+              fi
+              if [ "$SKIPPED" != "0" ]; then
+                echo " · ${SKIPPED} skipped"
+              fi
+              echo " · ${SUITES} suites · ${TOTAL} total"
+              echo " · ⏱️ ${DURATION}s"
+              if [ "$I_TOTAL" -gt 0 ] 2>/dev/null; then
+                echo " · 📊 ${U_TOTAL} unit + ${I_TOTAL} integration"
+              fi
+              echo ""
+            fi
+
+            # ── Coverage table helper ──
+            cov_table() {
+              local label=$1 s=$2 b=$3 f=$4 l=$5 sc=$6 bc=$7 fc=$8 lc=$9
+              shift 9
+              local ts=$1 tb=$2 tf=$3 tl=$4
+              echo "#### ${label}"
+              echo ""
+              echo "| Metric | Coverage | Covered | Threshold | Status |"
+              echo "|--------|----------|---------|-----------|--------|"
+              echo "| Statements | **${s}%** | ${sc} | ${ts}% | $(cov_bar "$s" "$ts") |"
+              echo "| Branches | **${b}%** | ${bc} | ${tb}% | $(cov_bar "$b" "$tb") |"
+              echo "| Functions | **${f}%** | ${fc} | ${tf}% | $(cov_bar "$f" "$tf") |"
+              echo "| Lines | **${l}%** | ${lc} | ${tl}% | $(cov_bar "$l" "$tl") |"
+              echo ""
+            }
+
+            if [ "$M_STMTS" != "N/A" ]; then
+              echo "### Code Coverage"
+              echo ""
+              cov_table "Combined (Unit + Integration)" \
+                "$M_STMTS" "$M_BRANCH" "$M_FUNCS" "$M_LINES" \
+                "$M_STMTS_COV" "$M_BRANCH_COV" "$M_FUNCS_COV" "$M_LINES_COV" \
+                "$THRESH_STMTS" "$THRESH_BRANCH" "$THRESH_FUNCS" "$THRESH_LINES"
+
+              echo "<details>"
+              echo "<summary>Coverage breakdown by test suite</summary>"
+              echo ""
+              if [ "$U_STMTS" != "N/A" ]; then
+                cov_table "Unit Tests" \
+                  "$U_STMTS" "$U_BRANCH" "$U_FUNCS" "$U_LINES" \
+                  "$U_STMTS_COV" "$U_BRANCH_COV" "$U_FUNCS_COV" "$U_LINES_COV" \
+                  "$THRESH_STMTS" "$THRESH_BRANCH" "$THRESH_FUNCS" "$THRESH_LINES"
+              fi
+              if [ "$I_STMTS" != "N/A" ]; then
+                cov_table "Integration Tests" \
+                  "$I_STMTS" "$I_BRANCH" "$I_FUNCS" "$I_LINES" \
+                  "$I_STMTS_COV" "$I_BRANCH_COV" "$I_FUNCS_COV" "$I_LINES_COV" \
+                  "$THRESH_STMTS" "$THRESH_BRANCH" "$THRESH_FUNCS" "$THRESH_LINES"
+              fi
+              echo "</details>"
+              echo ""
+              echo "<details>"
+              echo "<summary>Coverage thresholds are auto-ratcheted — they only go up</summary>"
+              echo ""
+              echo "Vitest \`thresholds.autoUpdate\` bumps the floor whenever local coverage exceeds it."
+              echo "CI enforces the current thresholds; developers commit the ratcheted values."
+              echo "</details>"
+              echo ""
+            elif [ "$U_STMTS" != "N/A" ]; then
+              echo "### Code Coverage (Unit only)"
+              echo ""
+              cov_table "Unit Tests" \
+                "$U_STMTS" "$U_BRANCH" "$U_FUNCS" "$U_LINES" \
+                "$U_STMTS_COV" "$U_BRANCH_COV" "$U_FUNCS_COV" "$U_LINES_COV" \
+                "$THRESH_STMTS" "$THRESH_BRANCH" "$THRESH_FUNCS" "$THRESH_LINES"
+              echo "<details>"
+              echo "<summary>Coverage thresholds are auto-ratcheted — they only go up</summary>"
+              echo ""
+              echo "Vitest \`thresholds.autoUpdate\` bumps the floor whenever local coverage exceeds it."
+              echo "CI enforces the current thresholds; developers commit the ratcheted values."
+              echo "</details>"
+              echo ""
+            else
+              echo "### Code Coverage"
+              echo ""
+              echo "⚠️ Coverage data unavailable - check the [unit test job](${RUN_URL}) for details."
+              echo ""
+            fi
+
+            echo "---"
+            echo "<sub>📋 [View full run](${RUN_URL}) · Generated by CI</sub>"
+            echo "GITNEXUS_CI_REPORT_EOF_7f3a"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Comment on PR
+        if: steps.meta.outputs.skip != 'true'
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
+        with:
+          header: ci-report
+          number: ${{ steps.meta.outputs.pr_number }}
+          message: ${{ steps.report.outputs.body }}

.github/workflows/ci-unit-tests.yml

@@ -0,0 +1,53 @@
+name: Unit Tests
+
+on:
+  workflow_call:
+
+jobs:
+  unit-tests:
+    name: unit (ubuntu / coverage)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+
+      - name: Run unit tests with coverage
+        run: >-
+          npx vitest run test/unit
+          --reporter=default
+          --reporter=json
+          --outputFile=test-results.json
+          --coverage
+          --coverage.reporter=json-summary
+          --coverage.reporter=json
+          --coverage.reporter=text
+          --coverage.thresholdAutoUpdate=false
+          --coverage.reportOnFailure=true
+        working-directory: gitnexus
+
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: test-reports
+          path: |
+            gitnexus/coverage/coverage-summary.json
+            gitnexus/coverage/coverage-final.json
+            gitnexus/test-results.json
+          retention-days: 5
+
+  cross-platform:
+    name: unit (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        # Ubuntu already covered by the coverage job above
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+      - run: npx vitest run test/unit
+        working-directory: gitnexus

.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
+  pull_request:
+    branches: [main]
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
+  workflow_call:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# ── Reusable workflow orchestration ─────────────────────────────────
+# Each concern lives in its own workflow file for maintainability:
+#   ci-quality.yml       — typecheck (tsc --noEmit)
+#   ci-unit-tests.yml    — unit tests with coverage + cross-platform
+#   ci-integration.yml   — integration test matrix (3 OS x 4 groups)
+#
+# Shared setup is DRY via .github/actions/setup-gitnexus composite action.
+
+jobs:
+  quality:
+    uses: ./.github/workflows/ci-quality.yml
+    permissions:
+      contents: read
+
+  unit-tests:
+    uses: ./.github/workflows/ci-unit-tests.yml
+    permissions:
+      contents: read
+
+  integration:
+    uses: ./.github/workflows/ci-integration.yml
+    with:
+      collect-coverage: ${{ github.event_name == 'pull_request' }}
+    permissions:
+      contents: read
+
+  # ── Save PR metadata for the reporting workflow ─────────────────
+  # The ci-report.yml workflow (triggered by workflow_run) needs the
+  # PR number and job results to post a comment.  We save them as an
+  # artifact because workflow_run context doesn't reliably carry PR
+  # info for fork PRs.
+  save-pr-meta:
+    name: Save PR Metadata
+    if: always() && github.event_name == 'pull_request'
+    needs: [quality, unit-tests, integration]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Write metadata
+        shell: bash
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+          QUALITY: ${{ needs.quality.result }}
+          UNIT: ${{ needs.unit-tests.result }}
+          INTEG: ${{ needs.integration.result }}
+        run: |
+          mkdir -p pr-meta
+          echo "$PR_NUMBER"  > pr-meta/pr_number
+          echo "$QUALITY"    > pr-meta/quality_result
+          echo "$UNIT"       > pr-meta/unit_result
+          echo "$INTEG"      > pr-meta/integration_result
+
+      - name: Upload PR metadata
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: pr-meta
+          path: pr-meta/
+          retention-days: 1
+
+  # ── Unified CI gate ──────────────────────────────────────────────
+  # Single required check for branch protection.
+  ci-status:
+    name: CI Gate
+    needs: [quality, unit-tests, integration]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check all jobs passed
+        shell: bash
+        env:
+          QUALITY: ${{ needs.quality.result }}
+          UNIT: ${{ needs.unit-tests.result }}
+          INTEG: ${{ needs.integration.result }}
+        run: |
+          echo "Quality:     $QUALITY"
+          echo "Unit Tests:  $UNIT"
+          echo "Integration: $INTEG"
+          if [[ "$QUALITY" != "success" ]] ||
+             [[ "$UNIT" != "success" ]] ||
+             [[ "$INTEG" != "success" ]]; then
+            echo "::error::One or more CI jobs failed"
+            exit 1
+          fi

.github/workflows/claude-code-review.yml

@@ -0,0 +1,97 @@
+name: Claude Code Review
+
+# Uses pull_request_target so the workflow runs as defined on the default branch,
+# which allows access to secrets for posting review comments on fork PRs.
+# SECURITY: The checkout below uses the PR head SHA to review the correct code.
+# The claude-code-action sandboxes execution — it does NOT run arbitrary code
+# from the checked-out source.
+
+on:
+  # Trigger only when explicitly requested:
+  #   - Add the "claude-review" label to a PR, OR
+  #   - Comment "@claude" or "/review" on a PR
+  pull_request_target:
+    types: [labeled]
+  issue_comment:
+    types: [created]
+
+jobs:
+  claude-review:
+    # Run only when:
+    #   1. The "claude-review" label is added to a non-draft PR by a trusted contributor, OR
+    #   2. A trusted contributor comments "@claude" or "/review" on a PR
+    if: |
+      (
+        github.event_name == 'pull_request_target' &&
+        github.event.label.name == 'claude-review' &&
+        github.event.pull_request.draft == false &&
+        (github.event.pull_request.author_association == 'OWNER' ||
+         github.event.pull_request.author_association == 'MEMBER' ||
+         github.event.pull_request.author_association == 'COLLABORATOR')
+      ) ||
+      (
+        github.event_name == 'issue_comment' &&
+        github.event.issue.pull_request &&
+        (contains(github.event.comment.body, '@claude') ||
+         contains(github.event.comment.body, '/review')) &&
+        (github.event.comment.author_association == 'OWNER' ||
+         github.event.comment.author_association == 'MEMBER' ||
+         github.event.comment.author_association == 'COLLABORATOR')
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write       # needed to push fork branch to origin
+      pull-requests: write
+      issues: read
+      id-token: write
+
+    steps:
+      # For issue_comment triggers, resolve the PR number, head SHA, and branch name
+      - name: Resolve PR context
+        id: pr
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            let pr;
+            if (context.eventName === 'issue_comment') {
+              const resp = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.issue.number,
+              });
+              pr = resp.data;
+            } else {
+              pr = context.payload.pull_request;
+            }
+            core.setOutput('number', pr.number);
+            core.setOutput('sha', pr.head.sha);
+            core.setOutput('branch', pr.head.ref);
+            core.setOutput('is_fork', String(pr.head.repo.full_name !== pr.base.repo.full_name));
+
+      - name: Checkout PR head
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          ref: ${{ steps.pr.outputs.sha }}
+          fetch-depth: 1
+
+      # claude-code-action fetches branches by name from origin, which fails
+      # for fork PRs. Work around by pushing the fork branch to origin so
+      # the action can find it.  Cleaned up in the post step below.
+      - name: Push fork branch to origin
+        if: steps.pr.outputs.is_fork == 'true'
+        run: git push origin HEAD:refs/heads/${{ steps.pr.outputs.branch }}
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'
+
+      # Clean up the temporary branch we pushed for fork PRs
+      - name: Delete fork branch from origin
+        if: always() && steps.pr.outputs.is_fork == 'true'
+        run: git push origin --delete refs/heads/${{ steps.pr.outputs.branch }} || true

.github/workflows/claude.yml

@@ -0,0 +1,42 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read

.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+# No workflow-level permissions — scoped per job below.
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+      pull-requests: write
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: npm
+          cache-dependency-path: gitnexus/package-lock.json
+      - run: npm ci
+        working-directory: gitnexus
+
+      - name: Verify version consistency
+        shell: bash
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "::error::Tag does not follow semver: v$TAG_VERSION"
+            exit 1
+          fi
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version (v$TAG_VERSION) does not match package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Version verified: $PKG_VERSION"
+        working-directory: gitnexus
+
+      - name: Build
+        run: npm run build
+        working-directory: gitnexus
+
+      - name: Dry-run publish
+        run: npm publish --dry-run
+        working-directory: gitnexus
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        working-directory: gitnexus
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
+        with:
+          generate_release_notes: true

.gitignore

@@ -17,6 +17,8 @@ dist/
 .DS_Store
 Thumbs.db
 
+.claude/settings.local.json
+
 # Environment variables
 .env
 .env.local
@@ -39,3 +41,22 @@ coverage/
 
 
 
+.env*.local
+.gitnexus
+.claude/settings.local.json
+
+# Claude Code worktrees
+.claude/worktrees/
+
+# Assets (screenshots, images)
+assets/
+
+# Generated files (should not be indexed)
+repomix-output*
+
+# Design docs (local only)
+docs/plans/
+
+gitnexus/test/fixtures/mini-repo/*.md
+gitnexus/test/fixtures/mini-repo/.claude
+gitnexus/test/fixtures/mini-repo/.gitignore

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

.sisyphus/drafts/gitnexus-brainstorming.md

@@ -0,0 +1,18 @@
+# Draft: Gitnexus Brainstorming - Clustering & Process Maps
+
+## Initial Context
+- Project: **GitnexusV2**
+- Structure: 
+    - `gitnexus/` (Likely the core application)
+    - `gitnexus-mcp/` (Likely a Model Context Protocol server)
+- Goal: Make it accurate and usable for smaller/dumber models.
+- Current Focus: Implementing **Clustering** and **Process Maps**.
+
+## Findings
+- **Clustering**: Found `gitnexus/src/core/ingestion/cluster-enricher.ts`.
+- **Process Maps**: No files matched `*process*map*` yet. Searching content next.
+
+## Open Questions
+- How is "process map" defined in this context? (Graph, mermaid diagram, flowchart?)
+- What is the input for clustering? (Code chunks, files, commits?)
+- What is the intended output for "smaller models"? (Simplified context, summaries?)

.sisyphus/drafts/noodlbox-comparison.md

@@ -0,0 +1,34 @@
+# Draft: Gitnexus vs Noodlbox Strategy
+
+## Objectives
+- Understand GitnexusV2 current state and goals.
+- Analyze Noodlbox capabilities from provided URL.
+- Compare features, architecture, and value proposition.
+- Provide strategic views and recommendations.
+
+## Research Findings
+- [GitnexusV2]: Zero-server, browser-native (WASM), KuzuDB based. Graph + Vector hybrid search.
+- [Noodlbox]: CLI-first, heavy install. Has "Session Hooks" and "Search Hooks" via plugins/CLI.
+
+## Comparison Points
+- **Core Philosophy**: Both bet on "Knowledge Graph + MCP" as the future. Noodlbox validates Gitnexus's direction.
+- **Architecture**:
+  - *Noodlbox*: CLI/Binary based. Likely local server management.
+  - *Gitnexus*: Zero-server, Browser-native (WASM). Lower friction, higher privacy.
+- **Features**:
+  - *Communities/Processes*: Both have them. Noodlbox uses them for "context injection". Gitnexus uses them for "visual exploration + query".
+  - *Impact Analysis*: Noodlbox has polished workflows (e.g., `detect_impact staged`). Gitnexus has the engine (`blastRadius`) but maybe not the specific workflow wrappers yet.
+- **UX/Integration**:
+  - *Noodlbox*: "Hooks" (Session/Search) are a killer feature. Proactively injecting context into the agent's session.
+  - *Gitnexus*: Powerful tools, but relies on agent *pulling* data?
+
+## Strategic Views
+1. **Validation**: The market direction is confirmed. You are building the right thing.
+2. **differentiation**: Lean into "Zero-Setup / Browser-Native". Noodlbox requires `noodl init` and CLI handling. Gitnexus could just *be*.
+3. **Opportunity**: Steal the "Session/Search Hooks" pattern. Make the agent smarter *automatically* without the user asking "check impact".
+4. **Workflow Polish**: Noodlbox's `/detect_impact staged` is a great specific use case. Gitnexus should wrap `blastRadius` into similar concrete workflows.
+
+## Technical Feasibility (Interception)
+- **Cursor**: Use `.cursorrules` to "shadow" default tools. Instruct agent to ALWAYS use `gitnexus_search` instead of `grep`.
+- **Claude Code**: Likely uses a private plugin API for `PreToolUse`. We can't match this exactly without an official plugin, but we can approximate it with strong prompt instructions in `AGENTS.md`.
+- **MCP Shadowing**: Define tools with names that conflict (e.g., `grep`)? No, unsafe. Better to use "Virtual Hooks" via system prompt instructions.

.windsurfrules

@@ -0,0 +1,5 @@
+# AI Agent Rules
+
+Follow .gitnexus/RULES.md for all project context and coding guidelines.
+
+This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices.

AGENTS.md

@@ -0,0 +1,78 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (1650 symbols, 4291 relationships, 125 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/GitNexus/clusters` | All functional areas |
+| `gitnexus://repo/GitNexus/processes` | All execution flows |
+| `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## CLI
+
+- Re-index: `npx gitnexus analyze`
+- Check freshness: `npx gitnexus status`
+- Generate docs: `npx gitnexus wiki`
+
+<!-- gitnexus:end -->

CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to GitNexus will be documented in this file.
+
+## [1.3.11] - 2026-03-08
+
+### Security
+
+- Fix FTS Cypher injection by escaping backslashes in search queries (#209) — @magyargergo
+
+### Added
+
+- Auto-reindex hook that runs `gitnexus analyze` after commits and merges, with automatic embeddings preservation (#205) — @L1nusB
+- 968 integration tests (up from ~840) covering unhappy paths across search, enrichment, CLI, pipeline, worker pool, and KuzuDB (#209) — @magyargergo
+- Coverage auto-ratcheting so thresholds bump automatically on CI (#209) — @magyargergo
+- Rich CI PR report with coverage bars, test counts, and threshold tracking (#209) — @magyargergo
+- Modular CI workflow architecture with separate unit-test, integration-test, and orchestrator jobs (#209) — @magyargergo
+
+### Fixed
+
+- KuzuDB native addon crashes on Linux/macOS by running integration tests in isolated vitest processes with `--pool=forks` (#209) — @magyargergo
+- Worker pool `MODULE_NOT_FOUND` crash when script path is invalid (#209) — @magyargergo
+
+### Changed
+
+- Added macOS to the cross-platform CI test matrix (#208) — @magyargergo
+
+## [1.3.10] - 2026-03-07
+
+### Security
+
+- **MCP transport buffer cap**: Added 10 MB `MAX_BUFFER_SIZE` limit to prevent out-of-memory attacks via oversized `Content-Length` headers or unbounded newline-delimited input
+- **Content-Length validation**: Reject `Content-Length` values exceeding the buffer cap before allocating memory
+- **Stack overflow prevention**: Replaced recursive `readNewlineMessage` with iterative loop to prevent stack overflow from consecutive empty lines
+- **Ambiguous prefix hardening**: Tightened `looksLikeContentLength` to require 14+ bytes before matching, preventing false framing detection on short input
+- **Closed transport guard**: `send()` now rejects with a clear error when called after `close()`, with proper write-error propagation
+
+### Added
+
+- **Dual-framing MCP transport** (`CompatibleStdioServerTransport`): Auto-detects Content-Length (Codex/OpenCode) and newline-delimited JSON (Cursor/Claude Code) framing on the first message, responds in the same format (#207)
+- **Lazy CLI module loading**: All CLI subcommands now use `createLazyAction()` to defer heavy imports (tree-sitter, ONNX, KuzuDB) until invocation, significantly improving `gitnexus mcp` startup time (#207)
+- **Type-safe lazy actions**: `createLazyAction` uses constrained generics to validate export names against module types at compile time
+- **Regression test suite**: 13 unit tests covering transport framing, security hardening, buffer limits, and lazy action loading
+
+### Fixed
+
+- **CALLS edge sourceId alignment**: `findEnclosingFunctionId` now generates IDs with `:startLine` suffix matching node creation format, fixing process detector finding 0 entry points (#194)
+- **LRU cache zero maxSize crash**: Guard `createASTCache` against `maxSize=0` when repos have no parseable files (#144)
+
+### Changed
+
+- Transport constructor accepts `NodeJS.ReadableStream` / `NodeJS.WritableStream` (widened from concrete `ReadStream`/`WriteStream`)
+- `processReadBuffer` simplified to break on first error instead of stale-buffer retry loop
+
+## [1.3.9] - 2026-03-06
+
+### Fixed
+
+- Aligned CALLS edge sourceId with node ID format in parse worker (#194)
+
+## [1.3.8] - 2026-03-05
+
+### Fixed
+
+- Force-exit after analyze to prevent KuzuDB native cleanup hang (#192)

CLAUDE.md

@@ -0,0 +1,78 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (1650 symbols, 4291 relationships, 125 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/GitNexus/clusters` | All functional areas |
+| `gitnexus://repo/GitNexus/processes` | All execution flows |
+| `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## CLI
+
+- Re-index: `npx gitnexus analyze`
+- Check freshness: `npx gitnexus status`
+- Generate docs: `npx gitnexus wiki`
+
+<!-- gitnexus:end -->

LICENSE

@@ -0,0 +1,73 @@
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Abhigyan Patwari (https://github.com/abhigyanpatwari/GitNexus)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

README.md

@@ -1,486 +1,506 @@
-# GitNexus V2
+# GitNexus
+⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
 
-**Zero-Server, Graph-Based Code Intelligence Engine**
-Works fully in-browser through WebAssembly. (DB engine, Embeddings model, AST parsing, all happens inside browser)
+<div align="center">
 
-https://github.com/user-attachments/assets/2fb7c522-20d1-48f6-9583-36c3969aa4dc
+  <a href="https://trendshift.io/repositories/19809" target="_blank">
+    <img src="https://trendshift.io/api/badge/repositories/19809" alt="abhigyanpatwari%2FGitNexus | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
+  </a>
 
-https://gitnexus.vercel.app
-Being client sided, it costs me zero to deploy, so you can use it for free :-) (would love a ⭐ though)
+  <h2>Join the official Discord to discuss ideas, issues etc!</h2>
 
-> *Like DeepWiki, but deeper.* 😉
+  <a href="https://discord.gg/AAsRVT6fGb">
+    <img src="https://img.shields.io/discord/1477255801545429032?color=5865F2&logo=discord&logoColor=white" alt="Discord"/>
+  </a>
+  <a href="https://www.npmjs.com/package/gitnexus">
+    <img src="https://img.shields.io/npm/v/gitnexus.svg" alt="npm version"/>
+  </a>
+  <a href="https://polyformproject.org/licenses/noncommercial/1.0.0/">
+    <img src="https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg" alt="License: PolyForm Noncommercial"/>
+  </a>
 
-DeepWiki helps you *understand* code. GitNexus lets you *analyze* it—because a knowledge graph tracks every dependency, call chain, and relationship. 
+</div>
 
-That's the difference between:
-- "What does this function do?" → *understanding*
-- "What breaks if I change this function?" → *analysis*
+**Building nervous system for agent context.**
 
-**Some quick tech jargon:**
-- **Enhanced Search**: BM25 + Semantic + 1-hop graph expansion via Cypher
-- **Full WASM Stack**: Tree-sitter parsing + KuzuDB graph database, all in-browser
-- **Repo Map**: Complete code knowledge graph with CALLS, IMPORTS, EXTENDS relations
-- **Vector Index**: HNSW embeddings for semantic similarity search
-- **Cypher Queries**: Relational analysis for accurate context retrieval
-- **Grounded AI**: Every answer cites `[[file:line]]` as proof
+Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart tools so AI agents never miss code.
 
-**What you can do:**
 
-| Capability | Description |
-|------------|-------------|
-| **Codebase-wide audits** | Find layer violations, forbidden dependencies |
-| **Blast radius analysis** | See every function affected by a change |
-| **Dead code detection** | Identify orphaned nodes with zero incoming calls |
-| **Dependency tracing** | Follow import chains across the entire codebase |
-| **AI analyses with citations** | Ask questions, analyze, get answers with `[[file:line]]` proof |
 
-**100% client-side.** Your code never leaves your browser.
 
-**Supports:** TypeScript, JavaScript, Python (Go, Java, C in progress)
+https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
+
+
+
+> *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
+
+**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=abhigyanpatwari/GitNexus&type=date&legend=top-left)](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left)
+
+
+## Two Ways to Use GitNexus
+
+|                   | **CLI + MCP**                                            | **Web UI**                                             |
+| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
+| **What**    | Index repos locally, connect AI agents via MCP                 | Visual graph explorer + AI chat in browser                   |
+| **For**     | Daily development with Cursor, Claude Code, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                   |
+| **Scale**   | Full repos, any size                                           | Limited by browser memory (~5k files), or unlimited via backend mode |
+| **Install** | `npm install -g gitnexus`                                    | No install —[gitnexus.vercel.app](https://gitnexus.vercel.app) |
+| **Storage** | KuzuDB native (fast, persistent)                               | KuzuDB WASM (in-memory, per session)                         |
+| **Parsing** | Tree-sitter native bindings                                    | Tree-sitter WASM                                             |
+| **Privacy** | Everything local, no network                                   | Everything in-browser, no server                             |
+
+> **Bridge mode:** `gitnexus serve` connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing.
+
+---
+
+## CLI + MCP (recommended)
+
+The CLI indexes your repository and runs an MCP server that gives AI agents deep codebase awareness.
+
+### Quick Start
+
+```bash
+# Index your repo (run from repo root)
+npx gitnexus 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 gitnexus setup` once — or set it up manually below.
+
+### MCP Setup
+
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+
+### Editor Support
+
+| Editor                | MCP | Skills | Hooks (auto-augment) | Support        |
+| --------------------- | --- | ------ | -------------------- | -------------- |
+| **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse) | **Full** |
+| **Cursor**      | Yes | Yes    | —                   | MCP + Skills   |
+| **Windsurf**    | Yes | —     | —                   | MCP            |
+| **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |
+
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that auto-reindex after commits.
+
+### Community Integrations
+
+| Agent | Install | Source |
+|-------|---------|--------|
+| [pi](https://pi.dev) | `pi install npm:pi-gitnexus` | [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) |
+
+If you prefer manual configuration:
+
+**Claude Code** (full support — MCP + skills + hooks):
+
+```bash
+claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
+**Cursor** (`~/.cursor/mcp.json` — global, works for all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+**OpenCode** (`~/.config/opencode/config.json`):
+
+```json
+{
+  "mcp": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+### CLI Commands
+
+```bash
+gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
+gitnexus list                    # List all indexed repositories
+gitnexus status                  # Show index status for current repo
+gitnexus clean                   # Delete index for current repo
+gitnexus clean --all --force     # Delete all indexes
+gitnexus wiki [path]             # Generate repository wiki from knowledge graph
+gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+gitnexus wiki --base-url <url>   # Wiki with custom LLM API base URL
+```
+
+### What Your AI Agent Gets
+
+**7 tools** exposed via MCP:
+
+| Tool               | What It Does                                                      | `repo` Param |
+| ------------------ | ----------------------------------------------------------------- | -------------- |
+| `list_repos`     | Discover all indexed repositories                                 | —             |
+| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)             | Optional       |
+| `context`        | 360-degree symbol view — categorized refs, process participation | Optional       |
+| `impact`         | Blast radius analysis with depth grouping and confidence          | Optional       |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes       | Optional       |
+| `rename`         | Multi-file coordinated rename with graph + text search            | Optional       |
+| `cypher`         | Raw Cypher graph queries                                          | Optional       |
+
+> When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({query: "auth", repo: "my-app"})`.
+
+**Resources** for instant context:
+
+| Resource                                  | Purpose                                              |
+| ----------------------------------------- | ---------------------------------------------------- |
+| `gitnexus://repos`                      | List all indexed repositories (read this first)      |
+| `gitnexus://repo/{name}/context`        | Codebase stats, staleness check, and available tools |
+| `gitnexus://repo/{name}/clusters`       | All functional clusters with cohesion scores         |
+| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details                          |
+| `gitnexus://repo/{name}/processes`      | All execution flows                                  |
+| `gitnexus://repo/{name}/process/{name}` | Full process trace with steps                        |
+| `gitnexus://repo/{name}/schema`         | Graph schema for Cypher queries                      |
+
+**2 MCP prompts** for guided workflows:
+
+| Prompt            | What It Does                                                              |
+| ----------------- | ------------------------------------------------------------------------- |
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level       |
+| `generate_map`  | Architecture documentation from the knowledge graph with mermaid diagrams |
+
+**4 agent skills** installed to `.claude/skills/` automatically:
+
+- **Exploring** — Navigate unfamiliar code using the knowledge graph
+- **Debugging** — Trace bugs through call chains
+- **Impact Analysis** — Analyze blast radius before changes
+- **Refactoring** — Plan safe refactors using dependency mapping
+
+---
+
+## Multi-Repo MCP Architecture
+
+GitNexus uses a **global registry** so one MCP server can serve multiple indexed repos. No per-project MCP config needed — set it up once and it works everywhere.
+
+```mermaid
+flowchart TD
+    subgraph CLI [CLI Commands]
+        Setup["gitnexus setup"]
+        Analyze["gitnexus analyze"]
+        Clean["gitnexus clean"]
+        List["gitnexus list"]
+    end
+
+    subgraph Registry ["~/.gitnexus/"]
+        RegFile["registry.json"]
+    end
+
+    subgraph Repos [Project Repos]
+        RepoA[".gitnexus/ in repo A"]
+        RepoB[".gitnexus/ in repo B"]
+    end
+
+    subgraph MCP [MCP Server]
+        Server["server.ts"]
+        Backend["LocalBackend"]
+        Pool["Connection Pool"]
+        ConnA["KuzuDB conn A"]
+        ConnB["KuzuDB conn B"]
+    end
+
+    Setup -->|"writes global MCP config"| CursorConfig["~/.cursor/mcp.json"]
+    Analyze -->|"registers repo"| RegFile
+    Analyze -->|"stores index"| RepoA
+    Clean -->|"unregisters repo"| RegFile
+    List -->|"reads"| RegFile
+    Server -->|"reads registry"| RegFile
+    Server --> Backend
+    Backend --> Pool
+    Pool -->|"lazy open"| ConnA
+    Pool -->|"lazy open"| ConnB
+    ConnA -->|"queries"| RepoA
+    ConnB -->|"queries"| RepoB
+```
+
+**How it works:** Each `gitnexus analyze` stores the index in `.gitnexus/` inside the repo (portable, gitignored) and registers a pointer in `~/.gitnexus/registry.json`. When an AI agent starts, the MCP server reads the registry and can serve any indexed repo. KuzuDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). If only one repo is indexed, the `repo` parameter is optional on all tools — agents don't need to change anything.
+
+---
+
+## Web UI (browser-based)
+
+A fully client-side graph explorer and AI chat. No server, no install — your code never leaves the browser.
+
+**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — drag & drop a ZIP and start exploring.
 
 <img width="2550" height="1343" alt="gitnexus_img" src="https://github.com/user-attachments/assets/cc5d637d-e0e5-48e6-93ff-5bcfdb929285" />
 
----
-
-## 🔍 The Problem with AI Coding Tools
-
-Tools like **Cursor**, **Claude Code**, **Cline**, **Roo Code**, and **Windsurf** are powerful—but they share a fundamental limitation: **they don't truly know your codebase structure**.
-
-| Tool | Context Strategy | The Gap |
-|------|------------------|---------|
-| **Cursor** | Files in tabs + embeddings | No call graph. Can't trace "what calls this?" |
-| **Claude Code** | File search + grep | Text-based. Misses semantic connections |
-| **Cline/Roo Code** | Repo map + tree-sitter | Static structure. No runtime dependencies tracked |
-| **Windsurf** | Cascade context | Limited dependency depth |
-
-**What happens:**
-1. AI edits `UserService.validate()` 
-2. Doesn't know 47 functions depend on its return type
-3. **Breaking changes ship** 💥
-
-### The Solution: Graph Coverage
-
-A knowledge graph tracks **actual relationships**, not just file contents:
-
-```mermaid
-graph LR
-    EDIT[AI wants to edit UserService.validate] --> QUERY[Graph Query: What depends on this?]
-    QUERY --> DEPS["47 callers across 12 files"]
-    DEPS --> SAFE[AI sees full blast radius first]
-```
-
-**Current state:** GitNexus is a standalone tool—a better DeepWiki that's 100% client-side with graph-powered analysis.
-
-**Future goal (MCP):** Expose GitNexus as an MCP server so tools like Cursor and Claude Code can query it for accurate context. They ask "what calls X?", GitNexus returns the actual call graph. No more guessing.
-
-
----
-
-## 🚀 Quick Start
+Or run locally:
 
 ```bash
-git clone <repository-url>
-cd gitnexus
+git clone https://github.com/abhigyanpatwari/gitnexus.git
+cd gitnexus/gitnexus-web
 npm install
 npm run dev
 ```
 
-Open http://localhost:5173, drag & drop a ZIP of your codebase, and start exploring.
+The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, KuzuDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.
+
+**Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
 
 ---
 
-## 🏗️ Indexing Architecture
+## The Problem GitNexus Solves
 
-Two-phase indexing: **Knowledge Graph** (blocking) → **Embeddings** (background).
+Tools like **Cursor**, **Claude Code**, **Cline**, **Roo Code**, and **Windsurf** are powerful — but they don't truly know your codebase structure.
 
-### Phase 1-5: Knowledge Graph Creation
+**What happens:**
+
+1. AI edits `UserService.validate()`
+2. Doesn't know 47 functions depend on its return type
+3. **Breaking changes ship**
+
+### Traditional Graph RAG vs GitNexus
+
+Traditional approaches give the LLM raw graph edges and hope it explores enough. GitNexus **precomputes structure at index time** — clustering, tracing, scoring — so tools return complete context in one call:
 
 ```mermaid
-flowchart TD
-    subgraph P1["Phase 1: Extract (0-15%)"]
-        E1[Decompress ZIP] --> E2[Collect file paths]
+flowchart TB
+    subgraph Traditional["Traditional Graph RAG"]
+        direction TB
+        U1["User: What depends on UserService?"]
+        U1 --> LLM1["LLM receives raw graph"]
+        LLM1 --> Q1["Query 1: Find callers"]
+        Q1 --> Q2["Query 2: What files?"]
+        Q2 --> Q3["Query 3: Filter tests?"]
+        Q3 --> Q4["Query 4: High-risk?"]
+        Q4 --> OUT1["Answer after 4+ queries"]
     end
-    
-    subgraph P2["Phase 2: Structure (15-30%)"]
-        S1[Build folder tree] --> S2[Create CONTAINS edges]
+
+    subgraph GN["GitNexus Smart Tools"]
+        direction TB
+        U2["User: What depends on UserService?"]
+        U2 --> TOOL["impact UserService upstream"]
+        TOOL --> PRECOMP["Pre-structured response:
+        8 callers, 3 clusters, all 90%+ confidence"]
+        PRECOMP --> OUT2["Complete answer, 1 query"]
     end
-    
-    subgraph P3["Phase 3: Parse (30-70%)"]
-        PA1[Load Tree-sitter WASM] --> PA2[Generate ASTs]
-        PA2 --> PA3[Extract symbols]
-        PA3 --> PA4[Populate Symbol Table]
-    end
-    
-    subgraph P4["Phase 4: Imports (70-82%)"]
-        I1[Find import statements] --> I2[Resolve paths]
-        I2 --> I3[Create IMPORTS edges]
-    end
-    
-    subgraph P5["Phase 5: Calls + Heritage (82-100%)"]
-        C1[Find function calls] --> C2[Resolve via Symbol Table]
-        C2 --> C3[Create CALLS edges]
-        C3 --> H1[Find extends/implements]
-        H1 --> H2[Create EXTENDS/IMPLEMENTS edges]
-    end
-    
-    P1 --> P2 --> P3 --> P4 --> P5
-    P5 --> DB[(KuzuDB WASM)]
-    DB --> READY[Graph Ready!]
 ```
 
-### Symbol Table: Dual HashMap
+**Core innovation: Precomputed Relational Intelligence**
 
-Resolution strategy for function calls:
-
-```mermaid
-flowchart TD
-    CALL[Found call: validateUser] --> CHECK1{In Import Map?}
-    CHECK1 -->|Yes| FOUND1[Use imported definition]
-    CHECK1 -->|No| CHECK2{In Current File?}
-    CHECK2 -->|Yes| FOUND2[Use local definition]
-    CHECK2 -->|No| CHECK3{Global Search}
-    CHECK3 -->|Found| FOUND3[Use first match]
-    CHECK3 -->|Not Found| SKIP[Skip - unresolved]
-    
-    FOUND1 --> EDGE[Create CALLS edge]
-    FOUND2 --> EDGE
-    FOUND3 --> EDGE
-```
-
-**Data structure:**
-```
-File-Scoped: Map<FilePath, Map<SymbolName, NodeID>>
-Global:      Map<SymbolName, SymbolDefinition[]>
-```
-
-### Phase 6+: Background Embeddings
-
-```mermaid
-flowchart LR
-    subgraph BG["Background (Non-blocking)"]
-        M1[Load snowflake-arctic-embed-xs] --> M2[Initialize WebGPU/WASM]
-        M2 --> E1[Batch embed nodes]
-        E1 --> E2[INSERT into CodeEmbedding table]
-        E2 --> V1[Create HNSW Vector Index]
-        V1 --> B1[Build BM25 Index]
-    end
-    
-    BG --> AI[AI Search Ready!]
-```
-
-User can explore the graph during embedding. AI features unlock when complete.
+- **Reliability** — LLM can't miss context, it's already in the tool response
+- **Token efficiency** — No 10-query chains to understand one function
+- **Model democratization** — Smaller LLMs work because tools do the heavy lifting
 
 ---
 
-## 📊 Graph Schema
+## How It Works
 
-### Node Types
+GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
 
-| Label | Description | Properties |
-|-------|-------------|------------|
-| `Folder` | Directory | `name`, `filePath` |
-| `File` | Source file | `name`, `filePath`, `language` |
-| `Function` | Function def | `name`, `filePath`, `startLine`, `endLine`, `isExported` |
-| `Class` | Class def | `name`, `filePath`, `startLine`, `endLine` |
-| `Interface` | Interface def | `name`, `filePath`, `startLine`, `endLine` |
-| `Method` | Class method | `name`, `filePath`, `startLine`, `endLine` |
-| `CodeElement` | Generic symbol | `name`, `filePath` |
+1. **Structure** — Walks the file tree and maps folder/file relationships
+2. **Parsing** — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
+3. **Resolution** — Resolves imports and function calls across files with language-aware logic
+4. **Clustering** — Groups related symbols into functional communities
+5. **Processes** — Traces execution flows from entry points through call chains
+6. **Search** — Builds hybrid search indexes for fast retrieval
 
-### Relationship Table: `CodeRelation`
+### Supported Languages
 
-Single edge table with `type` property:
-
-| Type | From | To | Description |
-|------|------|-----|-------------|
-| `CONTAINS` | Folder | File/Folder | Directory structure |
-| `DEFINES` | File | Function/Class/etc | Code definitions |
-| `IMPORTS` | File | File | Module dependencies |
-| `CALLS` | Function/Method | Function/Method | Call graph |
-| `EXTENDS` | Class | Class | Inheritance |
-| `IMPLEMENTS` | Class | Interface | Interface implementation |
+TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust, PHP, Swift
 
 ---
 
-## 🛠️ Agent Tools Architecture
+## Tool Examples
 
-The LangChain ReAct agent has **5 tools** for code exploration. These tools **use the graph** built during indexing.
+### Impact Analysis
 
-### Tool 1: `search` — Hybrid Search with Graph Context
+```
+impact({target: "UserService", direction: "upstream", minConfidence: 0.8})
 
-Combines **BM25** (keyword) + **Semantic** (vector) + **1-hop expansion**:
+TARGET: Class UserService (src/services/user.ts)
 
-```mermaid
-flowchart TD
-    Q[Query: auth middleware] --> BM25[BM25 Keyword Search]
-    Q --> SEM[Semantic Vector Search]
-    
-    BM25 --> RRF[Reciprocal Rank Fusion]
-    SEM --> RRF
-    
-    RRF --> TOP[Top K Results]
-    TOP --> HOP[1-Hop Graph Expansion]
-    
-    HOP --> OUT["Each result includes:
-    • ID, file, score
-    • Incoming connections (who calls this)
-    • Outgoing connections (what this calls)"]
+UPSTREAM (what depends on this):
+  Depth 1 (WILL BREAK):
+    handleLogin [CALLS 90%] -> src/api/auth.ts:45
+    handleRegister [CALLS 90%] -> src/api/auth.ts:78
+    UserController [CALLS 85%] -> src/controllers/user.ts:12
+  Depth 2 (LIKELY AFFECTED):
+    authRouter [IMPORTS] -> src/routes/auth.ts
 ```
 
-**How 1-hop works:**
-```cypher
-MATCH (n {id: $nodeId})
-OPTIONAL MATCH (n)-[r1:CodeRelation]->(dst)
-OPTIONAL MATCH (src)-[r2:CodeRelation]->(n)
-RETURN collect(dst.name), collect(src.name)
+Options: `maxDepth`, `minConfidence`, `relationTypes` (`CALLS`, `IMPORTS`, `EXTENDS`, `IMPLEMENTS`), `includeTests`
+
+### Process-Grouped Search
+
+```
+query({query: "authentication middleware"})
+
+processes:
+  - summary: "LoginFlow"
+    priority: 0.042
+    symbol_count: 4
+    process_type: cross_community
+    step_count: 7
+
+process_symbols:
+  - name: validateUser
+    type: Function
+    filePath: src/auth/validate.ts
+    process_id: proc_login
+    step_index: 2
+
+definitions:
+  - name: AuthConfig
+    type: Interface
+    filePath: src/types/auth.ts
 ```
 
-The agent sees not just *what matches*, but *what connects to it*.
+### Context (360-degree Symbol View)
 
----
+```
+context({name: "validateUser"})
 
-### Tool 2: `cypher` — Raw Graph Queries with Auto-Embedding
+symbol:
+  uid: "Function:validateUser"
+  kind: Function
+  filePath: src/auth/validate.ts
+  startLine: 15
 
-Execute Cypher directly. If you include `{{QUERY_VECTOR}}`, it auto-embeds:
+incoming:
+  calls: [handleLogin, handleRegister, UserController]
+  imports: [authRouter]
 
-```mermaid
-flowchart LR
-    CQ[Cypher with placeholder] --> CHECK{Contains QUERY_VECTOR?}
-    CHECK -->|Yes| EMBED[Embed query text]
-    EMBED --> REPLACE[Replace placeholder with vector]
-    CHECK -->|No| EXEC
-    REPLACE --> EXEC[Execute Cypher]
-    EXEC --> RES[Return Results]
+outgoing:
+  calls: [checkPassword, createSession]
+
+processes:
+  - name: LoginFlow (step 2/7)
+  - name: RegistrationFlow (step 3/5)
 ```
 
-**Example with auto-embedding:**
-```cypher
-CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'idx', {{QUERY_VECTOR}}, 10)
-YIELD node, distance
-WHERE distance < 0.4
-MATCH (caller:Function)-[:CodeRelation {type: 'CALLS'}]->(n:Function {id: node.nodeId})
-RETURN caller.name, n.name
+### Detect Changes (Pre-Commit)
+
+```
+detect_changes({scope: "all"})
+
+summary:
+  changed_count: 12
+  affected_count: 3
+  changed_files: 4
+  risk_level: medium
+
+changed_symbols: [validateUser, AuthService, ...]
+affected_processes: [LoginFlow, RegistrationFlow, ...]
 ```
 
-The agent provides `query: "authentication"` → system embeds it → injects the vector.
+### Rename (Multi-File)
 
----
+```
+rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})
 
-### Tool 3: `grep` — Regex Pattern Matching
-
-For exact strings, error codes, TODOs:
-
-```mermaid
-flowchart LR
-    PAT["Pattern: TODO|FIXME"] --> REGEX[Compile Regex]
-    REGEX --> SCAN[Scan all files]
-    SCAN --> MATCH[Match per line]
-    MATCH --> RES["file:line: content"]
+status: success
+files_affected: 5
+total_edits: 8
+graph_edits: 6     (high confidence)
+text_search_edits: 2  (review carefully)
+changes: [...]
 ```
 
----
-
-### Tool 4: `read` — Smart File Reader
-
-Fuzzy path matching with suggestions:
-
-```mermaid
-flowchart TD
-    REQ[Request: src/utils.ts] --> EXACT{Exact match?}
-    EXACT -->|Yes| RET[Return content]
-    EXACT -->|No| FUZZY[Fuzzy match by segments]
-    FUZZY --> FOUND{Found?}
-    FOUND -->|Yes| RET
-    FOUND -->|No| SUGGEST[Suggest similar files]
-```
-
----
-
-### Tool 5: `highlight` — Visual Graph Feedback
-
-Emits a marker that the UI parses to highlight nodes:
-```
-[HIGHLIGHT_NODES:Function:src/auth.ts:validate,Class:src/user.ts:UserService]
-```
-
----
-
-## 💡 Key Discovery: Unified Vector + Graph
-
-Most Graph RAG systems use **separate databases**—vector DB for semantic search, graph DB for traversal.
-
-KuzuDB supports **native vector indexing (HNSW)**, so we do both in **one Cypher query**:
+### Cypher Queries
 
 ```cypher
--- Semantic search + graph traversal in ONE query
-CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', $queryVector, 20)
-YIELD node AS emb, distance
-WITH emb, distance WHERE distance < 0.4
-MATCH (n:Function {id: emb.nodeId})<-[:CodeRelation {type: 'CALLS'}]-(caller:Function)
-RETURN n.name, caller.name, distance
-ORDER BY distance
+-- Find what calls auth functions with high confidence
+MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
+MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
+WHERE r.confidence > 0.8
+RETURN caller.name, fn.name, r.confidence
+ORDER BY r.confidence DESC
 ```
 
-**Why this matters:**
-- 🎯 **Single query execution** — No round-trips between systems
-- 📊 **Built-in relevance ranking** — Distance IS the score
-- ⚡ **No separate vector DB** — One database, one query language
-- 🌳 **LLM-friendly** — Agent writes one Cypher, gets semantic + structural results
-
 ---
 
-## 🔬 Deep Dive: Copy-on-Write Memory Issue
+## Wiki Generation
 
-Hit an interesting problem storing embeddings worth documenting.
+Generate LLM-powered documentation from your knowledge graph:
 
-**Setup:** Store 384-dim embeddings alongside code nodes.
-```cypher
-MATCH (n:CodeNode {id: $id}) SET n.embedding = $vec
+```bash
+# Requires an LLM API key (OPENAI_API_KEY, etc.)
+gitnexus wiki
+
+# Use a custom model or provider
+gitnexus wiki --model gpt-4o
+gitnexus wiki --base-url https://api.anthropic.com/v1
+
+# Force full regeneration
+gitnexus wiki --force
 ```
 
-**Problem:** Worked for ~20 nodes, exploded at ~1000:
-```
-Buffer manager exception: Unable to allocate memory!
-```
-
-**Root cause: Copy-on-Write.** Each `UPDATE` copies the entire record (~2KB of code content). 1000 updates = massive memory duplication in WASM.
-
-```mermaid
-flowchart LR
-    subgraph COW["Copy-on-Write Effect"]
-        OLD[Old: 2KB] --> NEW[New: 3.5KB]
-    end
-    COW -->|"× 1000 nodes"| BOOM[💥 Buffer Exhausted]
-```
-
-**Fix:** Separate `CodeEmbedding` table with `INSERT` only:
-
-```mermaid
-flowchart TD
-    subgraph Old["❌ Single Table"]
-        CN1[CodeNode with embedding<br/>UPDATE triggers COW]
-    end
-    
-    subgraph New["✅ Separate Table"]
-        CN2[CodeNode<br/>id, name, content]
-        CE[CodeEmbedding<br/>nodeId, embedding<br/>INSERT only]
-    end
-    
-    Old -->|"Memory explosion"| FAIL
-    New -->|"Works at scale"| WIN
-```
-
-**Lesson:** In-memory WASM DBs have hard limits. Profile at scale, not happy path.
+The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.
 
 ---
 
-## ⚡ V2 Technical Improvements
+## Tech Stack
 
-### Sigma.js + WebGL
-- V1: D3.js, choked at ~3k nodes
-- V2: Sigma.js + GPU rendering, smooth at 10k+
-
-### Dual HashMap Symbol Table
-- V1: Trie (prefix tree) - clever but slow
-- V2: File-scoped + Global hashmaps - **~2x speedup**
-
-### LRU AST Cache
-- Tree-sitter ASTs live in WASM memory
-- LRU cache (50 slots) with `tree.delete()` for cleanup
-- Memory stays bounded even for huge codebases
-
-### ForceAtlas2 in Web Worker
-- Layout algorithm runs off main thread
-- UI stays responsive during graph positioning
+| Layer                     | CLI                                   | Web                                     |
+| ------------------------- | ------------------------------------- | --------------------------------------- |
+| **Runtime**         | Node.js (native)                      | Browser (WASM)                          |
+| **Parsing**         | Tree-sitter native bindings           | Tree-sitter WASM                        |
+| **Database**        | KuzuDB native                         | KuzuDB WASM                             |
+| **Embeddings**      | HuggingFace transformers.js (GPU/CPU) | transformers.js (WebGPU/WASM)           |
+| **Search**          | BM25 + semantic + RRF                 | BM25 + semantic + RRF                   |
+| **Agent Interface** | MCP (stdio)                           | LangChain ReAct agent                   |
+| **Visualization**   | —                                    | Sigma.js + Graphology (WebGL)           |
+| **Frontend**        | —                                    | React 18, TypeScript, Vite, Tailwind v4 |
+| **Clustering**      | Graphology                            | Graphology                              |
+| **Concurrency**     | Worker threads + async                | Web Workers + Comlink                   |
 
 ---
 
-## 🚧 Roadmap
+## Roadmap
 
 ### Actively Building
 
-- [ ] **MCP Support** - Model Context Protocol for tool extensibility
-- [ ] **External DB Support** - Connect to Neo4j (hosted or Docker)
-- [ ] **Blast Radius Analysis Tool** - Dedicated UI for impact analysis
-- [ ] **Multi-Worker Pool** - Parallel parsing across Web Workers
-- [ ] **Ollama Support** - Local LLM integration
-- [ ] **CSV Export** - Export node/relationship tables
+- [ ] **LLM Cluster Enrichment** — Semantic cluster names via LLM API
+- [ ] **AST Decorator Detection** — Parse @Controller, @Get, etc.
+- [ ] **Incremental Indexing** — Only re-index changed files
 
-### 🎯 The Vision: Browser-Based MCP Server
+### Recently Completed
 
-**Goal:** Expose GitNexus as a local MCP server directly from the browser.
-
-This would let AI coding tools like **Cursor**, **Claude Code**, **Windsurf**, etc. connect to your running GitNexus instance and use its knowledge graph for:
-- 🔍 **Reliable context gathering** — AI gets actual dependencies, not grep guesses
-- 💥 **Blast radius detection** — Before making changes, query what would break
-- 🔐 **Codebase-wide audits** — Find violations, dead code, circular dependencies
-- 🧠 **Grounded answers** — Every response backed by graph traversal, not hallucination
-
-```mermaid
-graph LR
-    subgraph Browser["GitNexus (Browser)"]
-        KG[Knowledge Graph]
-        MCP[MCP Server]
-    end
-    
-    subgraph Tools["AI Coding Tools"]
-        CURSOR[Cursor]
-        CLAUDE[Claude Code]
-        WIND[Windsurf]
-    end
-    
-    KG --> MCP
-    MCP <-->|localhost| CURSOR
-    MCP <-->|localhost| CLAUDE
-    MCP <-->|localhost| WIND
-```
-
-**Why this matters:** Current AI coding tools are blind to real dependencies. They use grep or embeddings—better than nothing, but not enough to prevent breaking changes. A knowledge graph MCP would give them the accurate, structural context they need.
-
-### Recently Completed ✅
-
-- [x] Graph RAG Agent with 5 tools (search, cypher, grep, read, highlight)
-- [x] Browser embeddings (snowflake-arctic-embed-xs, 22M params)
-- [x] Vector index with HNSW in KuzuDB
-- [x] Hybrid search (BM25 + semantic + RRF)
-- [x] Streaming AI chat with tool visibility
-- [x] Grounded citations (`[[file:line]]` format)
-- [x] Multiple LLM providers (OpenAI, Azure, Gemini, Anthropic)
+- [X] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
+- [X] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
+- [X] Multi-Repo MCP, Zero-Config Setup, 11 Language Support
+- [X] Community Detection, Process Detection, Confidence Scoring
+- [X] Hybrid Search, Vector Index
 
 ---
 
-## 🛠 Tech Stack
+## Security & Privacy
 
-| Layer | Technology |
-|-------|------------|
-| **Frontend** | React 18, TypeScript, Vite, Tailwind v4 |
-| **Visualization** | Sigma.js, Graphology, ForceAtlas2 (WebGL) |
-| **Parsing** | Tree-sitter WASM (TS, JS, Python) |
-| **Database** | KuzuDB WASM (graph + vector HNSW) |
-| **Embeddings** | transformers.js, snowflake-arctic-embed-xs (22M) |
-| **AI** | LangChain ReAct agent, streaming |
-| **Concurrency** | Web Workers + Comlink |
+- **CLI**: Everything runs locally on your machine. No network calls. Index stored in `.gitnexus/` (gitignored). Global registry at `~/.gitnexus/` stores only paths and metadata.
+- **Web**: Everything runs in your browser. No code uploaded to any server. API keys stored in localStorage only.
+- Open source — audit the code yourself.
 
 ---
 
-## 🔐 Security & Privacy
+## Acknowledgments
 
-- All processing happens in your browser
-- No code uploaded to any server
-- API keys stored in localStorage only
-- Open source—audit the code yourself
-
----
-
-## 📝 License
-
-MIT License
-
----
-
-## 🙏 Acknowledgments
-
-- [Tree-sitter](https://tree-sitter.github.io/) - AST parsing
-- [KuzuDB](https://kuzudb.com/) - Embedded graph database with vector support
-- [Sigma.js](https://www.sigmajs.org/) - WebGL graph rendering
-- [transformers.js](https://huggingface.co/docs/transformers.js) - Browser ML
-- [LangChain](https://langchain.com/) - Agent orchestration
+- [Tree-sitter](https://tree-sitter.github.io/) — AST parsing
+- [KuzuDB](https://kuzudb.com/) — Embedded graph database with vector support
+- [Sigma.js](https://www.sigmajs.org/) — WebGL graph rendering
+- [transformers.js](https://huggingface.co/docs/transformers.js) — Browser ML
+- [Graphology](https://graphology.github.io/) — Graph data structures
+- [MCP](https://modelcontextprotocol.io/) — Model Context Protocol

eval/.env.example

@@ -0,0 +1,23 @@
+# ─── GitNexus SWE-bench Eval — API Keys ───
+# Copy this file to .env and fill in the keys you have.
+# You only need keys for the models you plan to test.
+
+# OpenRouter (covers Claude, MiniMax, GLM, and 200+ other models)
+# Get yours at: https://openrouter.ai/keys
+OPENROUTER_API_KEY=
+
+# Anthropic (direct — optional if using OpenRouter)
+# Get yours at: https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# ZhipuAI / GLM (direct — optional if using OpenRouter)
+# Get yours at: https://open.bigmodel.cn/
+ZHIPUAI_API_KEY=
+
+# MiniMax (direct — optional if using OpenRouter)
+MINIMAX_API_KEY=
+
+# ─── Optional ───
+
+# Cost tracking: set to "ignore_errors" if litellm can't find pricing for a model
+# MSWEA_COST_TRACKING=ignore_errors

eval/.gitignore

@@ -0,0 +1,16 @@
+# Evaluation results (large, should not be committed)
+results/
+*.traj.json
+preds.json
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Environment
+.env
+.venv/

eval/README.md

@@ -0,0 +1,210 @@
+# GitNexus SWE-bench Evaluation Harness
+
+Evaluate whether GitNexus code intelligence improves AI agent performance on real software engineering tasks. Runs SWE-bench instances across multiple models and compares baseline (no graph) vs GitNexus-enhanced configurations.
+
+## What This Tests
+
+**Hypothesis**: Giving AI agents structural code intelligence (call graphs, execution flows, blast radius analysis) improves their ability to resolve real GitHub issues — measured by resolve rate, cost, and efficiency.
+
+**Evaluation modes:**
+
+| Mode | What the agent gets |
+|------|-------------------|
+| `baseline` | Standard bash tools (grep, find, cat, sed) — control group |
+| `native` | Baseline + explicit GitNexus tools via eval-server (~100ms) |
+| `native_augment` | Native tools + grep results automatically enriched with graph context (**recommended**) |
+
+> **Recommended**: Use `native_augment` mode. It mirrors the Claude Code model — the agent gets both explicit GitNexus tools (fast bash commands) AND automatic enrichment of grep results with callers, callees, and execution flows. The agent decides when to use explicit tools vs rely on enriched search output.
+
+**Models supported:**
+
+- Claude 3.5 Haiku, Claude Sonnet 4, Claude Opus 4
+- MiniMax M1 2.5
+- GLM 4.7, GLM 5
+- Any model supported by litellm (add a YAML config)
+
+## Prerequisites
+
+- Python 3.11+
+- Docker (for SWE-bench containers)
+- Node.js 18+ (for GitNexus)
+- API keys for your chosen models
+
+## Setup
+
+```bash
+cd eval
+
+# Install dependencies
+pip install -e .
+
+# Set up API keys — copy the template and fill in your keys
+cp .env.example .env
+# Then edit .env and paste your key(s)
+```
+
+All models are routed through **OpenRouter** by default, so a single `OPENROUTER_API_KEY` is all you need. To use provider APIs directly (Anthropic, ZhipuAI, etc.), edit the model YAML in `configs/models/` and set the corresponding key in `.env`.
+
+```bash
+# Pull SWE-bench Docker images (pulled on-demand, but you can pre-pull)
+docker pull swebench/sweb.eval.x86_64.django_1776_django-16527:latest
+```
+
+## Quick Start
+
+### Debug a single instance
+
+```bash
+# Fastest way to verify everything works
+python run_eval.py debug -m claude-haiku -i django__django-16527 --subset lite
+```
+
+### Run a single configuration
+
+```bash
+# 5 instances, Claude Sonnet, native_augment mode (default)
+python run_eval.py single -m claude-sonnet --subset lite --slice 0:5
+
+# Baseline comparison (no GitNexus)
+python run_eval.py single -m claude-sonnet --mode baseline --subset lite --slice 0:5
+
+# Full Lite benchmark, 4 parallel workers
+python run_eval.py single -m claude-sonnet --subset lite -w 4
+```
+
+### Run the full matrix
+
+```bash
+# All models x all modes
+python run_eval.py matrix --subset lite -w 4
+
+# Key comparison: baseline vs native_augment
+python run_eval.py matrix -m claude-sonnet -m claude-haiku --modes baseline --modes native_augment --subset lite --slice 0:50
+```
+
+### Analyze results
+
+```bash
+# Summary table
+python -m analysis.analyze_results results/
+
+# Compare modes for a specific model
+python -m analysis.analyze_results compare-modes results/ -m claude-sonnet
+
+# GitNexus tool usage analysis
+python -m analysis.analyze_results gitnexus-usage results/
+
+# Export as CSV for further analysis
+python -m analysis.analyze_results summary results/ --format csv > results.csv
+
+# Run official SWE-bench test evaluation
+python -m analysis.analyze_results summary results/ --swebench-eval
+```
+
+### List available configurations
+
+```bash
+python run_eval.py list-configs
+```
+
+## Architecture
+
+```
+eval/
+  run_eval.py              # Main entry point (single, matrix, debug commands)
+  agents/
+    gitnexus_agent.py      # GitNexusAgent: extends DefaultAgent with augmentation + metrics
+  environments/
+    gitnexus_docker.py     # Docker env with GitNexus + eval-server + standalone tool scripts
+  bridge/
+    gitnexus_tools.sh      # Bash wrappers (legacy — now standalone scripts are installed directly)
+    mcp_bridge.py          # Legacy MCP bridge (kept for reference)
+  prompts/
+    system_baseline.jinja          # System: persona + format rules
+    instance_baseline.jinja        # Instance: task + workflow
+    system_native.jinja            # System: + GitNexus tool reference
+    instance_native.jinja          # Instance: + GitNexus debugging workflow
+    system_native_augment.jinja    # System: + GitNexus tools + grep enrichment docs
+    instance_native_augment.jinja  # Instance: + GitNexus workflow + risk assessment
+  configs/
+    models/                # Per-model YAML configs
+    modes/                 # Per-mode YAML configs (baseline, native, native_augment)
+  analysis/
+    analyze_results.py     # Post-run comparative analysis
+  results/                 # Output directory (gitignored)
+```
+
+## How It Works
+
+### Template structure
+
+mini-swe-agent requires two Jinja templates:
+- **system_template** → system message: persona, format rules, tool reference (static)
+- **instance_template** → first user message: task, workflow, rules, examples (contains `{{task}}`)
+
+Each mode has a `system_{mode}.jinja` + `instance_{mode}.jinja` pair. The agent loads both automatically based on the configured mode.
+
+### Per-instance flow
+
+1. Docker container starts with SWE-bench instance (repo at specific commit)
+2. **GitNexus setup**: Node.js + gitnexus installed, `gitnexus analyze` runs (or restores from cache)
+3. **Eval-server starts**: `gitnexus eval-server` daemon (persistent HTTP server, keeps KuzuDB warm)
+4. **Standalone tool scripts installed** in `/usr/local/bin/` — works with `subprocess.run` (no `.bashrc` needed)
+5. Agent runs with the configured model + system prompt + GitNexus tools
+6. Agent's patch is extracted as a git diff
+7. Metrics collected: cost, tokens, tool calls, GitNexus usage, augmentation stats
+
+### Tool architecture
+
+```
+Agent → bash command → /usr/local/bin/gitnexus-query
+  → curl localhost:4848/tool/query     (fast path: eval-server, ~100ms)
+  → npx gitnexus query                 (fallback: cold CLI, ~5-10s)
+```
+
+Each tool script in `/usr/local/bin/` is standalone — no sourcing, no env inheritance needed. This is critical because mini-swe-agent runs every command via `subprocess.run` in a fresh subshell.
+
+### Eval-server
+
+The eval-server is a lightweight HTTP daemon that:
+- Keeps KuzuDB warm in memory (no cold start per tool call)
+- Returns LLM-friendly text (not raw JSON — saves tokens)
+- Includes next-step hints to guide tool chaining (query → context → impact → fix)
+- Auto-shuts down after idle timeout
+
+### Index caching
+
+SWE-bench repos repeat (Django has 200+ instances at different commits). The harness caches GitNexus indexes per `(repo, commit)` hash in `~/.gitnexus-eval-cache/` to avoid redundant re-indexing.
+
+### Grep augmentation (native_augment mode)
+
+When the agent runs `grep` or `rg`, the observation is post-processed: the agent class calls `gitnexus-augment` on the search pattern and appends `[GitNexus]` annotations showing callers, callees, and execution flows for matched symbols. This mirrors the Claude Code / Cursor hook integration.
+
+## Adding Models
+
+Create a YAML file in `configs/models/`:
+
+```yaml
+# configs/models/my-model.yaml
+model:
+  model_name: "openrouter/provider/model-name"
+  cost_tracking: "ignore_errors"  # if not in litellm's cost DB
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0
+```
+
+The model name follows [litellm conventions](https://docs.litellm.ai/docs/providers).
+
+## Metrics Collected
+
+| Metric | Description |
+|--------|-------------|
+| Patch Rate | % of instances where agent produced a patch |
+| Resolve Rate | % of instances where patch passes tests (requires --swebench-eval) |
+| Total Cost | API cost across all instances |
+| Avg Cost/Instance | Cost efficiency |
+| API Calls | Number of LLM calls |
+| GN Tool Calls | How many GitNexus tools the agent used |
+| Augment Hits | How many grep/find results got enriched |
+| Augment Hit Rate | % of search commands that got useful enrichment |

eval/__init__.py

@@ -0,0 +1 @@
+# GitNexus SWE-bench Evaluation Harness

eval/agents/gitnexus_agent.py

@@ -0,0 +1,209 @@
+"""
+GitNexus-Enhanced Agent for SWE-bench Evaluation
+
+Extends mini-swe-agent's DefaultAgent with:
+1. Native augment mode: GitNexus tools via eval-server + grep enrichment (recommended)
+2. Native mode: GitNexus tools via eval-server only
+3. Baseline mode: Pure mini-swe-agent (no GitNexus — control group)
+
+The agent class itself is minimal — the heavy lifting is in:
+- Prompt selection (system + instance templates per mode)
+- Observation post-processing (grep result augmentation)
+- Metrics tracking (which tools the agent actually uses)
+
+Template structure (matches mini-swe-agent's expectations):
+  system_template  → system message: persona + format rules + tool reference
+  instance_template → first user message: task + workflow + rules + examples
+"""
+
+import logging
+import re
+import time
+from enum import Enum
+from pathlib import Path
+
+from minisweagent import Environment, Model
+from minisweagent.agents.default import AgentConfig, DefaultAgent
+
+logger = logging.getLogger("gitnexus_agent")
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+
+class GitNexusMode(str, Enum):
+    """Evaluation modes for GitNexus integration."""
+    BASELINE = "baseline"               # No GitNexus — pure mini-swe-agent
+    NATIVE = "native"                   # GitNexus tools via eval-server
+    NATIVE_AUGMENT = "native_augment"   # Native tools + grep enrichment (recommended)
+
+
+class GitNexusAgentConfig(AgentConfig):
+    """Extended config for GitNexus evaluation agent."""
+    gitnexus_mode: GitNexusMode = GitNexusMode.BASELINE
+    augment_timeout: float = 5.0
+    augment_min_pattern_length: int = 3
+    track_gitnexus_usage: bool = True
+
+
+class GitNexusAgent(DefaultAgent):
+    """
+    Agent that optionally enriches its capabilities with GitNexus code intelligence.
+
+    In BASELINE mode, behaves identically to DefaultAgent.
+    In NATIVE mode, GitNexus tools are available as bash commands via eval-server.
+    In NATIVE_AUGMENT mode, GitNexus tools + automatic grep result enrichment.
+    """
+
+    def __init__(self, model: Model, env: Environment, *, config_class: type = GitNexusAgentConfig, **kwargs):
+        mode = kwargs.get("gitnexus_mode", GitNexusMode.BASELINE)
+        if isinstance(mode, str):
+            mode = GitNexusMode(mode)
+
+        # Load system template
+        system_file = PROMPTS_DIR / f"system_{mode.value}.jinja"
+        if system_file.exists() and "system_template" not in kwargs:
+            kwargs["system_template"] = system_file.read_text()
+
+        # Load instance template
+        instance_file = PROMPTS_DIR / f"instance_{mode.value}.jinja"
+        if instance_file.exists() and "instance_template" not in kwargs:
+            kwargs["instance_template"] = instance_file.read_text()
+
+        super().__init__(model, env, config_class=config_class, **kwargs)
+        self.gitnexus_mode = mode
+        self.gitnexus_metrics = GitNexusMetrics()
+
+    def execute_actions(self, message: dict) -> list[dict]:
+        """Execute actions with optional GitNexus augmentation and tracking."""
+        if self.config.track_gitnexus_usage:
+            self._track_tool_usage(message)
+
+        outputs = [self.env.execute(action) for action in message.get("extra", {}).get("actions", [])]
+
+        # Augment grep/find observations in NATIVE_AUGMENT mode
+        if self.gitnexus_mode == GitNexusMode.NATIVE_AUGMENT:
+            actions = message.get("extra", {}).get("actions", [])
+            for i, (action, output) in enumerate(zip(actions, outputs)):
+                augmented = self._maybe_augment(action, output)
+                if augmented:
+                    outputs[i] = augmented
+
+        return self.add_messages(
+            *self.model.format_observation_messages(message, outputs, self.get_template_vars())
+        )
+
+    def _maybe_augment(self, action: dict, output: dict) -> dict | None:
+        """
+        If the action is a search command (grep, find, rg, ag), augment the output
+        with GitNexus knowledge graph context.
+        """
+        command = action.get("command", "")
+        if not command:
+            return None
+
+        pattern = self._extract_search_pattern(command)
+        if not pattern or len(pattern) < self.config.augment_min_pattern_length:
+            return None
+
+        start = time.time()
+        try:
+            augment_result = self.env.execute({
+                "command": f'gitnexus-augment "{pattern}" 2>&1 || true',
+                "timeout": self.config.augment_timeout,
+            })
+            elapsed = time.time() - start
+            self.gitnexus_metrics.augmentation_calls += 1
+            self.gitnexus_metrics.augmentation_time += elapsed
+
+            augment_text = augment_result.get("output", "").strip()
+            if augment_text and "[GitNexus]" in augment_text:
+                original_output = output.get("output", "")
+                output = dict(output)
+                output["output"] = f"{original_output}\n\n{augment_text}"
+                self.gitnexus_metrics.augmentation_hits += 1
+                return output
+        except Exception as e:
+            logger.debug(f"Augmentation failed for pattern '{pattern}': {e}")
+            self.gitnexus_metrics.augmentation_errors += 1
+
+        return None
+
+    @staticmethod
+    def _extract_search_pattern(command: str) -> str | None:
+        """Extract the search pattern from a grep/find/rg command."""
+        patterns = [
+            r'(?:grep|rg|ag)\s+(?:-[a-zA-Z]*\s+)*["\']([^"\']+)["\']',
+            r'(?:grep|rg|ag)\s+(?:-[a-zA-Z]*\s+)*(\S+)',
+        ]
+
+        for pat in patterns:
+            match = re.search(pat, command)
+            if match:
+                result = match.group(1)
+                if result.startswith("/") or result.startswith("."):
+                    continue
+                if result.startswith("-"):
+                    continue
+                return result
+
+        return None
+
+    def _track_tool_usage(self, message: dict):
+        """Track which GitNexus tools the agent uses."""
+        for action in message.get("extra", {}).get("actions", []):
+            command = action.get("command", "")
+            if "gitnexus-query" in command:
+                self.gitnexus_metrics.tool_calls["query"] += 1
+            elif "gitnexus-context" in command:
+                self.gitnexus_metrics.tool_calls["context"] += 1
+            elif "gitnexus-impact" in command:
+                self.gitnexus_metrics.tool_calls["impact"] += 1
+            elif "gitnexus-cypher" in command:
+                self.gitnexus_metrics.tool_calls["cypher"] += 1
+            elif "gitnexus-overview" in command:
+                self.gitnexus_metrics.tool_calls["overview"] += 1
+
+    def serialize(self, *extra_dicts) -> dict:
+        """Serialize with GitNexus-specific metrics."""
+        gitnexus_data = {
+            "info": {
+                "gitnexus": {
+                    "mode": self.gitnexus_mode.value,
+                    "metrics": self.gitnexus_metrics.to_dict(),
+                },
+            },
+        }
+        return super().serialize(gitnexus_data, *extra_dicts)
+
+
+class GitNexusMetrics:
+    """Tracks GitNexus-specific metrics during evaluation."""
+
+    def __init__(self):
+        self.tool_calls: dict[str, int] = {
+            "query": 0,
+            "context": 0,
+            "impact": 0,
+            "cypher": 0,
+            "overview": 0,
+        }
+        self.augmentation_calls: int = 0
+        self.augmentation_hits: int = 0
+        self.augmentation_errors: int = 0
+        self.augmentation_time: float = 0.0
+        self.index_time: float = 0.0
+
+    @property
+    def total_tool_calls(self) -> int:
+        return sum(self.tool_calls.values())
+
+    def to_dict(self) -> dict:
+        return {
+            "tool_calls": dict(self.tool_calls),
+            "total_tool_calls": self.total_tool_calls,
+            "augmentation_calls": self.augmentation_calls,
+            "augmentation_hits": self.augmentation_hits,
+            "augmentation_errors": self.augmentation_errors,
+            "augmentation_time_seconds": round(self.augmentation_time, 2),
+            "index_time_seconds": round(self.index_time, 2),
+        }

eval/analysis/analyze_results.py

@@ -0,0 +1,446 @@
+#!/usr/bin/env python3
+"""
+Results Analyzer for GitNexus SWE-bench Evaluation
+
+Reads evaluation results and generates comparative analysis:
+- Resolve rate by model x mode
+- Cost comparison (total, per-instance)
+- Token/API call efficiency
+- GitNexus tool usage patterns
+- Augmentation hit rates
+
+Usage:
+    python -m analysis.analyze_results /path/to/results
+    python -m analysis.analyze_results /path/to/results --format markdown
+    python -m analysis.analyze_results /path/to/results --swebench-eval  # run actual test verification
+"""
+
+import json
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+logger = logging.getLogger("analyze_results")
+console = Console()
+app = typer.Typer(rich_markup_mode="rich", add_completion=False)
+
+
+def load_run_results(results_dir: Path) -> dict[str, dict]:
+    """
+    Load all run results from the results directory.
+    
+    Returns: {run_id: {summary, preds, instances}}
+    """
+    runs = {}
+
+    for run_dir in sorted(results_dir.iterdir()):
+        if not run_dir.is_dir():
+            continue
+
+        run_id = run_dir.name
+        run_data: dict[str, Any] = {"run_id": run_id, "dir": run_dir}
+
+        # Load summary
+        summary_path = run_dir / "summary.json"
+        if summary_path.exists():
+            run_data["summary"] = json.loads(summary_path.read_text())
+
+        # Load predictions
+        preds_path = run_dir / "preds.json"
+        if preds_path.exists():
+            run_data["preds"] = json.loads(preds_path.read_text())
+
+        # Load individual trajectories for detailed metrics
+        run_data["trajectories"] = {}
+        for traj_dir in run_dir.iterdir():
+            if not traj_dir.is_dir():
+                continue
+            for traj_file in traj_dir.glob("*.traj.json"):
+                try:
+                    traj = json.loads(traj_file.read_text())
+                    instance_id = traj.get("instance_id", traj_dir.name)
+                    run_data["trajectories"][instance_id] = traj
+                except Exception:
+                    pass
+
+        if run_data.get("preds") or run_data.get("summary"):
+            runs[run_id] = run_data
+
+    return runs
+
+
+def parse_run_id(run_id: str) -> tuple[str, str]:
+    """Parse 'model_mode' into (model, mode)."""
+    # Handle multi-word model names like 'minimax-2.5'
+    # Modes are: baseline, mcp, augment, full
+    known_modes = {"baseline", "mcp", "augment", "full"}
+    parts = run_id.rsplit("_", 1)
+    if len(parts) == 2 and parts[1] in known_modes:
+        return parts[0], parts[1]
+    return run_id, "unknown"
+
+
+def compute_metrics(run_data: dict) -> dict:
+    """Compute evaluation metrics for a single run."""
+    preds = run_data.get("preds", {})
+    summary = run_data.get("summary", {})
+    trajectories = run_data.get("trajectories", {})
+
+    n_instances = len(preds)
+    n_with_patch = sum(1 for p in preds.values() if p.get("model_patch", "").strip())
+
+    # Cost and API call metrics from trajectories
+    costs = []
+    api_calls = []
+    gn_tool_calls = []
+    gn_augment_hits = []
+    gn_augment_calls = []
+
+    for instance_id, traj in trajectories.items():
+        info = traj.get("info", {})
+        model_stats = info.get("model_stats", {})
+        costs.append(model_stats.get("instance_cost", 0))
+        api_calls.append(model_stats.get("api_calls", 0))
+
+        gn = info.get("gitnexus", {}).get("metrics", {})
+        if gn:
+            gn_tool_calls.append(gn.get("total_tool_calls", 0))
+            gn_augment_hits.append(gn.get("augmentation_hits", 0))
+            gn_augment_calls.append(gn.get("augmentation_calls", 0))
+
+    # Also try summary-level metrics
+    if not costs and summary:
+        results = summary.get("results", [])
+        for r in results:
+            costs.append(r.get("cost", 0))
+            api_calls.append(r.get("n_calls", 0))
+            gn = r.get("gitnexus_metrics", {})
+            if gn:
+                gn_tool_calls.append(gn.get("total_tool_calls", 0))
+                gn_augment_hits.append(gn.get("augmentation_hits", 0))
+                gn_augment_calls.append(gn.get("augmentation_calls", 0))
+
+    total_cost = sum(costs)
+    total_calls = sum(api_calls)
+
+    return {
+        "n_instances": n_instances,
+        "n_with_patch": n_with_patch,
+        "patch_rate": n_with_patch / max(n_instances, 1),
+        "total_cost": total_cost,
+        "avg_cost": total_cost / max(n_instances, 1),
+        "total_api_calls": total_calls,
+        "avg_api_calls": total_calls / max(n_instances, 1),
+        "total_gn_tool_calls": sum(gn_tool_calls),
+        "avg_gn_tool_calls": sum(gn_tool_calls) / max(len(gn_tool_calls), 1) if gn_tool_calls else 0,
+        "total_augment_hits": sum(gn_augment_hits),
+        "total_augment_calls": sum(gn_augment_calls),
+        "augment_hit_rate": sum(gn_augment_hits) / max(sum(gn_augment_calls), 1) if gn_augment_calls else 0,
+    }
+
+
+def run_swebench_evaluation(results_dir: Path, run_id: str, subset: str = "lite") -> dict | None:
+    """
+    Run the official SWE-bench evaluation on predictions.
+    
+    Requires: pip install swebench
+    """
+    preds_path = results_dir / run_id / "preds.json"
+    if not preds_path.exists():
+        return None
+
+    dataset_mapping = {
+        "lite": "princeton-nlp/SWE-Bench_Lite",
+        "verified": "princeton-nlp/SWE-Bench_Verified",
+        "full": "princeton-nlp/SWE-Bench",
+    }
+
+    try:
+        eval_output = results_dir / run_id / "swebench_eval"
+        cmd = [
+            sys.executable, "-m", "swebench.harness.run_evaluation",
+            "--dataset_name", dataset_mapping.get(subset, subset),
+            "--predictions_path", str(preds_path),
+            "--max_workers", "4",
+            "--run_id", run_id,
+            "--output_dir", str(eval_output),
+        ]
+
+        logger.info(f"Running SWE-bench evaluation for {run_id}...")
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+        if result.returncode == 0:
+            # Parse evaluation results
+            report_path = eval_output / run_id / "results.json"
+            if report_path.exists():
+                return json.loads(report_path.read_text())
+
+        logger.error(f"SWE-bench eval failed: {result.stderr[:500]}")
+        return None
+
+    except Exception as e:
+        logger.error(f"SWE-bench eval error: {e}")
+        return None
+
+
+# ─── CLI Commands ───────────────────────────────────────────────────────────
+
+
+@app.command()
+def summary(
+    results_dir: str = typer.Argument(..., help="Path to results directory"),
+    format: str = typer.Option("table", "--format", help="Output format: table, markdown, json, csv"),
+    swebench_eval: bool = typer.Option(False, "--swebench-eval", help="Run official SWE-bench test evaluation"),
+    subset: str = typer.Option("lite", "--subset", help="SWE-bench subset (for --swebench-eval)"),
+):
+    """Generate comparative analysis of evaluation results."""
+    results_path = Path(results_dir)
+    if not results_path.exists():
+        console.print(f"[red]Results directory not found: {results_path}[/red]")
+        raise typer.Exit(1)
+
+    runs = load_run_results(results_path)
+    if not runs:
+        console.print("[yellow]No evaluation results found[/yellow]")
+        raise typer.Exit(0)
+
+    console.print(f"\n[bold]Found {len(runs)} evaluation runs[/bold]\n")
+
+    # Compute metrics per run
+    all_metrics = {}
+    for run_id, run_data in runs.items():
+        model, mode = parse_run_id(run_id)
+        metrics = compute_metrics(run_data)
+        metrics["model"] = model
+        metrics["mode"] = mode
+
+        # Optionally run SWE-bench evaluation
+        if swebench_eval:
+            eval_result = run_swebench_evaluation(results_path, run_id, subset)
+            if eval_result:
+                metrics["resolved"] = eval_result.get("resolved", 0)
+                metrics["resolve_rate"] = eval_result.get("resolved", 0) / max(metrics["n_instances"], 1)
+
+        all_metrics[run_id] = metrics
+
+    if format == "table":
+        _print_table(all_metrics)
+    elif format == "markdown":
+        _print_markdown(all_metrics)
+    elif format == "json":
+        console.print(json.dumps(all_metrics, indent=2))
+    elif format == "csv":
+        _print_csv(all_metrics)
+
+
+@app.command()
+def compare_modes(
+    results_dir: str = typer.Argument(..., help="Path to results directory"),
+    model: str = typer.Option(..., "-m", "--model", help="Model to compare across modes"),
+):
+    """Compare modes for a specific model (baseline vs mcp vs augment vs full)."""
+    results_path = Path(results_dir)
+    runs = load_run_results(results_path)
+
+    # Filter to the specified model
+    model_runs = {
+        run_id: data for run_id, data in runs.items()
+        if parse_run_id(run_id)[0] == model
+    }
+
+    if not model_runs:
+        console.print(f"[yellow]No results found for model: {model}[/yellow]")
+        raise typer.Exit(1)
+
+    console.print(f"\n[bold]Mode comparison for {model}[/bold]\n")
+
+    metrics = {}
+    for run_id, run_data in model_runs.items():
+        _, mode = parse_run_id(run_id)
+        metrics[mode] = compute_metrics(run_data)
+
+    # Print comparison table
+    table = Table(title=f"Mode Comparison: {model}")
+    table.add_column("Metric", style="bold")
+    for mode in ["baseline", "mcp", "augment", "full"]:
+        if mode in metrics:
+            table.add_column(mode, justify="right")
+
+    rows = [
+        ("Instances", "n_instances", "d"),
+        ("With Patch", "n_with_patch", "d"),
+        ("Patch Rate", "patch_rate", ".1%"),
+        ("Total Cost", "total_cost", "$.4f"),
+        ("Avg Cost", "avg_cost", "$.4f"),
+        ("Total API Calls", "total_api_calls", "d"),
+        ("Avg API Calls", "avg_api_calls", ".1f"),
+        ("GN Tool Calls", "total_gn_tool_calls", "d"),
+        ("Augment Hits", "total_augment_hits", "d"),
+        ("Augment Hit Rate", "augment_hit_rate", ".1%"),
+    ]
+
+    for label, key, fmt in rows:
+        values = []
+        for mode in ["baseline", "mcp", "augment", "full"]:
+            if mode in metrics:
+                v = metrics[mode].get(key, 0)
+                if fmt == ".1%":
+                    values.append(f"{v:.1%}")
+                elif fmt == "$.4f":
+                    values.append(f"${v:.4f}")
+                elif fmt == ".1f":
+                    values.append(f"{v:.1f}")
+                else:
+                    values.append(str(v))
+        table.add_row(label, *values)
+
+    # Add delta rows (improvement over baseline)
+    if "baseline" in metrics:
+        baseline_cost = metrics["baseline"]["avg_cost"]
+        baseline_calls = metrics["baseline"]["avg_api_calls"]
+
+        table.add_section()
+        for mode in ["mcp", "augment", "full"]:
+            if mode not in metrics:
+                continue
+            mode_cost = metrics[mode]["avg_cost"]
+            mode_calls = metrics[mode]["avg_api_calls"]
+
+            cost_delta = ((mode_cost - baseline_cost) / max(baseline_cost, 0.001)) * 100
+            calls_delta = ((mode_calls - baseline_calls) / max(baseline_calls, 1)) * 100
+
+            cost_str = f"{cost_delta:+.1f}%"
+            calls_str = f"{calls_delta:+.1f}%"
+
+            # Color-code: negative is good (cheaper/fewer calls)
+            cost_color = "green" if cost_delta < 0 else "red"
+            calls_color = "green" if calls_delta < 0 else "red"
+
+            console.print(f"  {mode} vs baseline: cost [{cost_color}]{cost_str}[/{cost_color}], calls [{calls_color}]{calls_str}[/{calls_color}]")
+
+    console.print(table)
+
+
+@app.command()
+def gitnexus_usage(
+    results_dir: str = typer.Argument(..., help="Path to results directory"),
+):
+    """Analyze GitNexus tool usage patterns across all runs."""
+    results_path = Path(results_dir)
+    runs = load_run_results(results_path)
+
+    console.print("\n[bold]GitNexus Tool Usage Analysis[/bold]\n")
+
+    table = Table(title="Tool Usage by Run")
+    table.add_column("Run", style="bold")
+    table.add_column("query", justify="right")
+    table.add_column("context", justify="right")
+    table.add_column("impact", justify="right")
+    table.add_column("cypher", justify="right")
+    table.add_column("Total", justify="right")
+    table.add_column("Augment Hits", justify="right")
+
+    for run_id, run_data in sorted(runs.items()):
+        _, mode = parse_run_id(run_id)
+        if mode == "baseline":
+            continue
+
+        # Aggregate tool calls across trajectories
+        tool_totals: dict[str, int] = {"query": 0, "context": 0, "impact": 0, "cypher": 0, "overview": 0}
+        augment_hits = 0
+
+        for traj in run_data.get("trajectories", {}).values():
+            gn = traj.get("info", {}).get("gitnexus", {}).get("metrics", {})
+            for tool, count in gn.get("tool_calls", {}).items():
+                tool_totals[tool] = tool_totals.get(tool, 0) + count
+            augment_hits += gn.get("augmentation_hits", 0)
+
+        # Also check summary
+        for r in run_data.get("summary", {}).get("results", []):
+            gn = r.get("gitnexus_metrics", {})
+            for tool, count in gn.get("tool_calls", {}).items():
+                tool_totals[tool] = tool_totals.get(tool, 0) + count
+            augment_hits += gn.get("augmentation_hits", 0)
+
+        total = sum(tool_totals.values())
+        if total > 0 or augment_hits > 0:
+            table.add_row(
+                run_id,
+                str(tool_totals.get("query", 0)),
+                str(tool_totals.get("context", 0)),
+                str(tool_totals.get("impact", 0)),
+                str(tool_totals.get("cypher", 0)),
+                str(total),
+                str(augment_hits),
+            )
+
+    console.print(table)
+
+
+# ─── Output Formatters ─────────────────────────────────────────────────────
+
+
+def _print_table(all_metrics: dict):
+    """Print rich table summary."""
+    table = Table(title="Evaluation Results")
+    table.add_column("Run", style="bold")
+    table.add_column("Model")
+    table.add_column("Mode")
+    table.add_column("N", justify="right")
+    table.add_column("Patched", justify="right")
+    table.add_column("Rate", justify="right")
+    table.add_column("Cost", justify="right")
+    table.add_column("Calls", justify="right")
+    table.add_column("GN Tools", justify="right")
+
+    for run_id, m in sorted(all_metrics.items()):
+        resolved_str = ""
+        if "resolve_rate" in m:
+            resolved_str = f" ({m['resolve_rate']:.0%})"
+
+        table.add_row(
+            run_id,
+            m["model"],
+            m["mode"],
+            str(m["n_instances"]),
+            str(m["n_with_patch"]),
+            f"{m['patch_rate']:.0%}{resolved_str}",
+            f"${m['total_cost']:.2f}",
+            str(m["total_api_calls"]),
+            str(m["total_gn_tool_calls"]) if m["total_gn_tool_calls"] > 0 else "-",
+        )
+
+    console.print(table)
+
+
+def _print_markdown(all_metrics: dict):
+    """Print markdown table."""
+    print("| Run | Model | Mode | N | Patched | Rate | Cost | Calls | GN Tools |")
+    print("|-----|-------|------|---|---------|------|------|-------|----------|")
+    for run_id, m in sorted(all_metrics.items()):
+        gn = str(m["total_gn_tool_calls"]) if m["total_gn_tool_calls"] > 0 else "-"
+        print(f"| {run_id} | {m['model']} | {m['mode']} | {m['n_instances']} | {m['n_with_patch']} | {m['patch_rate']:.0%} | ${m['total_cost']:.2f} | {m['total_api_calls']} | {gn} |")
+
+
+def _print_csv(all_metrics: dict):
+    """Print CSV output."""
+    print("run_id,model,mode,n_instances,n_with_patch,patch_rate,total_cost,avg_cost,total_api_calls,avg_api_calls,total_gn_tool_calls,total_augment_hits,augment_hit_rate")
+    for run_id, m in sorted(all_metrics.items()):
+        print(
+            f"{run_id},{m['model']},{m['mode']},{m['n_instances']},{m['n_with_patch']},"
+            f"{m['patch_rate']:.4f},{m['total_cost']:.4f},{m['avg_cost']:.4f},"
+            f"{m['total_api_calls']},{m['avg_api_calls']:.1f},{m['total_gn_tool_calls']},"
+            f"{m['total_augment_hits']},{m['augment_hit_rate']:.4f}"
+        )
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    app()

eval/bridge/gitnexus_tools.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+# GitNexus CLI tool wrappers for SWE-bench evaluation
+#
+# These functions call the GitNexus eval-server (HTTP daemon) for near-instant
+# tool responses. The eval-server keeps KuzuDB warm in memory.
+#
+# If the eval-server is not running, falls back to direct CLI commands.
+#
+# Usage:
+#   gitnexus-query "how does authentication work"
+#   gitnexus-context "validateUser"
+#   gitnexus-impact "AuthService" upstream
+#   gitnexus-cypher "MATCH (n:Function) RETURN n.name LIMIT 10"
+#   gitnexus-overview
+
+GITNEXUS_EVAL_PORT="${GITNEXUS_EVAL_PORT:-4848}"
+GITNEXUS_EVAL_URL="http://127.0.0.1:${GITNEXUS_EVAL_PORT}"
+
+_gitnexus_call() {
+    local tool="$1"
+    shift
+    local json_body="$1"
+
+    # Try eval-server first (fastest path — KuzuDB stays warm)
+    local result
+    result=$(curl -sf -X POST "${GITNEXUS_EVAL_URL}/tool/${tool}" \
+        -H "Content-Type: application/json" \
+        -d "${json_body}" 2>/dev/null)
+
+    if [ $? -eq 0 ] && [ -n "$result" ]; then
+        echo "$result"
+        return 0
+    fi
+
+    # Fallback: direct CLI (cold start, slower but always works)
+    case "$tool" in
+        query)
+            local q=$(echo "$json_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('query',''))" 2>/dev/null)
+            npx gitnexus query "$q" 2>&1
+            ;;
+        context)
+            local n=$(echo "$json_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('name',''))" 2>/dev/null)
+            npx gitnexus context "$n" 2>&1
+            ;;
+        impact)
+            local t=$(echo "$json_body" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('target',''))" 2>/dev/null)
+            local d=$(echo "$json_body" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('direction','upstream'))" 2>/dev/null)
+            npx gitnexus impact "$t" --direction "$d" 2>&1
+            ;;
+        cypher)
+            local cq=$(echo "$json_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('query',''))" 2>/dev/null)
+            npx gitnexus cypher "$cq" 2>&1
+            ;;
+        *)
+            echo "Unknown tool: $tool" >&2
+            return 1
+            ;;
+    esac
+}
+
+gitnexus-query() {
+    local query="$1"
+    local task_context="${2:-}"
+    local goal="${3:-}"
+
+    if [ -z "$query" ]; then
+        echo "Usage: gitnexus-query <query> [task_context] [goal]"
+        echo "Search the code knowledge graph for execution flows related to a concept."
+        echo ""
+        echo "Examples:"
+        echo '  gitnexus-query "authentication flow"'
+        echo '  gitnexus-query "database connection" "fixing connection pool leak"'
+        return 1
+    fi
+
+    local args="{\"query\": \"$query\""
+    [ -n "$task_context" ] && args="$args, \"task_context\": \"$task_context\""
+    [ -n "$goal" ] && args="$args, \"goal\": \"$goal\""
+    args="$args}"
+
+    _gitnexus_call query "$args"
+}
+
+gitnexus-context() {
+    local name="$1"
+    local file_path="${2:-}"
+
+    if [ -z "$name" ]; then
+        echo "Usage: gitnexus-context <symbol_name> [file_path]"
+        echo "Get a 360-degree view of a code symbol: callers, callees, processes, file location."
+        echo ""
+        echo "Examples:"
+        echo '  gitnexus-context "validateUser"'
+        echo '  gitnexus-context "AuthService" "src/auth/service.py"'
+        return 1
+    fi
+
+    local args="{\"name\": \"$name\""
+    [ -n "$file_path" ] && args="$args, \"file_path\": \"$file_path\""
+    args="$args}"
+
+    _gitnexus_call context "$args"
+}
+
+gitnexus-impact() {
+    local target="$1"
+    local direction="${2:-upstream}"
+
+    if [ -z "$target" ]; then
+        echo "Usage: gitnexus-impact <symbol_name> [upstream|downstream]"
+        echo "Analyze the blast radius of changing a code symbol."
+        echo ""
+        echo "  upstream  = what depends on this (what breaks if you change it)"
+        echo "  downstream = what this depends on (what it uses)"
+        echo ""
+        echo "Examples:"
+        echo '  gitnexus-impact "AuthService" upstream'
+        echo '  gitnexus-impact "validateUser" downstream'
+        return 1
+    fi
+
+    _gitnexus_call impact "{\"target\": \"$target\", \"direction\": \"$direction\"}"
+}
+
+gitnexus-cypher() {
+    local query="$1"
+
+    if [ -z "$query" ]; then
+        echo "Usage: gitnexus-cypher <cypher_query>"
+        echo "Execute a raw Cypher query against the code knowledge graph."
+        echo ""
+        echo "Schema: Nodes: File, Function, Class, Method, Interface, Community, Process"
+        echo "Edges via CodeRelation.type: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS"
+        echo ""
+        echo "Examples:"
+        echo "  gitnexus-cypher 'MATCH (a)-[:CodeRelation {type: \"CALLS\"}]->(b:Function {name: \"save\"}) RETURN a.name, a.filePath'"
+        echo "  gitnexus-cypher 'MATCH (n:Class) RETURN n.name, n.filePath LIMIT 20'"
+        return 1
+    fi
+
+    _gitnexus_call cypher "{\"query\": \"$query\"}"
+}
+
+gitnexus-overview() {
+    echo "=== Code Knowledge Graph Overview ==="
+    _gitnexus_call list_repos '{}'
+}
+
+# Export functions so they're available in subshells
+export -f _gitnexus_call 2>/dev/null
+export -f gitnexus-query 2>/dev/null
+export -f gitnexus-context 2>/dev/null
+export -f gitnexus-impact 2>/dev/null
+export -f gitnexus-cypher 2>/dev/null
+export -f gitnexus-overview 2>/dev/null

eval/bridge/mcp_bridge.py

@@ -0,0 +1,336 @@
+"""
+MCP Bridge for GitNexus
+
+Starts the GitNexus MCP server as a subprocess and provides a Python interface
+to call MCP tools. Used by the bash wrapper scripts and the augmentation layer.
+
+The bridge communicates with the MCP server via stdio using the JSON-RPC protocol.
+"""
+
+import json
+import logging
+import os
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("mcp_bridge")
+
+
+class MCPBridge:
+    """
+    Manages a GitNexus MCP server subprocess and proxies tool calls to it.
+    
+    Usage:
+        bridge = MCPBridge(repo_path="/path/to/repo")
+        bridge.start()
+        result = bridge.call_tool("query", {"query": "authentication"})
+        bridge.stop()
+    """
+
+    def __init__(self, repo_path: str | None = None):
+        self.repo_path = repo_path or os.getcwd()
+        self.process: subprocess.Popen | None = None
+        self._request_id = 0
+        self._lock = threading.Lock()
+        self._started = False
+
+    def start(self) -> bool:
+        """Start the GitNexus MCP server subprocess."""
+        if self._started:
+            return True
+
+        try:
+            # Find gitnexus binary
+            gitnexus_bin = self._find_gitnexus()
+            if not gitnexus_bin:
+                logger.error("GitNexus not found. Install with: npm install -g gitnexus")
+                return False
+
+            self.process = subprocess.Popen(
+                [gitnexus_bin, "mcp"],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=self.repo_path,
+                text=False,
+            )
+
+            # Send initialize request
+            init_result = self._send_request("initialize", {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "gitnexus-eval", "version": "0.1.0"},
+            })
+
+            if init_result is None:
+                logger.error("MCP server failed to initialize")
+                self.stop()
+                return False
+
+            # Send initialized notification
+            self._send_notification("notifications/initialized", {})
+            self._started = True
+            logger.info("MCP bridge started successfully")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to start MCP bridge: {e}")
+            self.stop()
+            return False
+
+    def stop(self):
+        """Stop the MCP server subprocess."""
+        if self.process:
+            try:
+                self.process.stdin.close()
+                self.process.terminate()
+                self.process.wait(timeout=5)
+            except Exception:
+                try:
+                    self.process.kill()
+                except Exception:
+                    pass
+            self.process = None
+        self._started = False
+
+    def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        """
+        Call a GitNexus MCP tool and return the result.
+        
+        Returns the tool result content or None on error.
+        """
+        if not self._started:
+            logger.error("MCP bridge not started")
+            return None
+
+        result = self._send_request("tools/call", {
+            "name": tool_name,
+            "arguments": arguments or {},
+        })
+
+        if result is None:
+            return None
+
+        # Extract text content from MCP response
+        content = result.get("content", [])
+        if content and isinstance(content, list):
+            texts = [item.get("text", "") for item in content if item.get("type") == "text"]
+            return {"text": "\n".join(texts), "raw": content}
+
+        return {"text": "", "raw": content}
+
+    def list_tools(self) -> list[dict]:
+        """List available MCP tools."""
+        result = self._send_request("tools/list", {})
+        if result:
+            return result.get("tools", [])
+        return []
+
+    def read_resource(self, uri: str) -> str | None:
+        """Read an MCP resource by URI."""
+        result = self._send_request("resources/read", {"uri": uri})
+        if result:
+            contents = result.get("contents", [])
+            if contents:
+                return contents[0].get("text", "")
+        return None
+
+    def _find_gitnexus(self) -> str | None:
+        """Find the gitnexus CLI binary."""
+        # Check if npx is available (preferred - uses local install)
+        for cmd in ["npx"]:
+            try:
+                result = subprocess.run(
+                    [cmd, "gitnexus", "--version"],
+                    capture_output=True, text=True, timeout=15,
+                    cwd=self.repo_path,
+                )
+                if result.returncode == 0:
+                    return cmd  # Will use "npx gitnexus mcp"
+            except Exception:
+                continue
+
+        # Check for global install
+        try:
+            result = subprocess.run(
+                ["gitnexus", "--version"],
+                capture_output=True, text=True, timeout=10,
+            )
+            if result.returncode == 0:
+                return "gitnexus"
+        except Exception:
+            pass
+
+        return None
+
+    def _next_id(self) -> int:
+        with self._lock:
+            self._request_id += 1
+            return self._request_id
+
+    def _send_request(self, method: str, params: dict) -> dict | None:
+        """Send a JSON-RPC request and wait for response."""
+        if not self.process or not self.process.stdin or not self.process.stdout:
+            return None
+
+        request_id = self._next_id()
+        request = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+            "params": params,
+        }
+
+        try:
+            message = json.dumps(request)
+            # MCP uses Content-Length header framing
+            header = f"Content-Length: {len(message.encode('utf-8'))}\r\n\r\n"
+            self.process.stdin.write(header.encode("utf-8"))
+            self.process.stdin.write(message.encode("utf-8"))
+            self.process.stdin.flush()
+
+            # Read response
+            response = self._read_response(timeout=30)
+            if response and response.get("id") == request_id:
+                if "error" in response:
+                    logger.error(f"MCP error: {response['error']}")
+                    return None
+                return response.get("result")
+            return None
+
+        except Exception as e:
+            logger.error(f"MCP request failed: {e}")
+            return None
+
+    def _send_notification(self, method: str, params: dict):
+        """Send a JSON-RPC notification (no response expected)."""
+        if not self.process or not self.process.stdin:
+            return
+
+        notification = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+        }
+
+        try:
+            message = json.dumps(notification)
+            header = f"Content-Length: {len(message.encode('utf-8'))}\r\n\r\n"
+            self.process.stdin.write(header.encode("utf-8"))
+            self.process.stdin.write(message.encode("utf-8"))
+            self.process.stdin.flush()
+        except Exception as e:
+            logger.error(f"MCP notification failed: {e}")
+
+    def _read_response(self, timeout: float = 30) -> dict | None:
+        """Read a JSON-RPC response from the MCP server."""
+        if not self.process or not self.process.stdout:
+            return None
+
+        start = time.time()
+
+        try:
+            while time.time() - start < timeout:
+                # Read Content-Length header
+                header_line = b""
+                while True:
+                    byte = self.process.stdout.read(1)
+                    if not byte:
+                        return None
+                    header_line += byte
+                    if header_line.endswith(b"\r\n\r\n"):
+                        break
+                    if header_line.endswith(b"\n\n"):
+                        break
+
+                # Parse content length
+                header_str = header_line.decode("utf-8").strip()
+                content_length = None
+                for line in header_str.split("\r\n"):
+                    if line.lower().startswith("content-length:"):
+                        content_length = int(line.split(":")[1].strip())
+                        break
+
+                if content_length is None:
+                    continue
+
+                # Read body
+                body = self.process.stdout.read(content_length)
+                if not body:
+                    return None
+
+                message = json.loads(body.decode("utf-8"))
+
+                # Skip notifications (no id), return responses
+                if "id" in message:
+                    return message
+
+            return None
+
+        except Exception as e:
+            logger.error(f"Error reading MCP response: {e}")
+            return None
+
+
+class MCPToolCLI:
+    """
+    CLI wrapper that exposes MCP tools as simple command-line calls.
+    Used by the bash wrapper scripts inside Docker containers.
+    
+    Usage from bash:
+        python -m bridge.mcp_bridge query '{"query": "authentication"}'
+        python -m bridge.mcp_bridge context '{"name": "validateUser"}'
+    """
+
+    def __init__(self):
+        self.bridge = MCPBridge()
+
+    def run(self, tool_name: str, args_json: str = "{}") -> int:
+        """Run a single tool call and print the result."""
+        try:
+            args = json.loads(args_json)
+        except json.JSONDecodeError:
+            # Try to parse as simple key=value pairs
+            args = self._parse_simple_args(args_json)
+
+        if not self.bridge.start():
+            print("ERROR: Failed to start GitNexus MCP bridge", file=sys.stderr)
+            return 1
+
+        try:
+            result = self.bridge.call_tool(tool_name, args)
+            if result:
+                print(result.get("text", ""))
+                return 0
+            else:
+                print("No results", file=sys.stderr)
+                return 1
+        finally:
+            self.bridge.stop()
+
+    @staticmethod
+    def _parse_simple_args(args_str: str) -> dict:
+        """Parse 'key=value key2=value2' style arguments."""
+        args = {}
+        for part in args_str.split():
+            if "=" in part:
+                key, value = part.split("=", 1)
+                args[key] = value
+        return args
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python -m bridge.mcp_bridge <tool_name> [args_json]", file=sys.stderr)
+        print("Tools: query, context, impact, cypher, list_repos, detect_changes, rename", file=sys.stderr)
+        sys.exit(1)
+
+    tool = sys.argv[1]
+    args_json = sys.argv[2] if len(sys.argv) > 2 else "{}"
+
+    cli = MCPToolCLI()
+    sys.exit(cli.run(tool, args_json))

eval/configs/models/claude-haiku.yaml

@@ -0,0 +1,8 @@
+# Claude Haiku 4.5 — fast, cheap, good baseline
+# Via OpenRouter (set OPENROUTER_API_KEY in .env)
+model:
+  model_name: "openrouter/anthropic/claude-haiku-4.5"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0

eval/configs/models/claude-opus.yaml

@@ -0,0 +1,9 @@
+# Claude Opus 4 — most capable, highest cost
+# Via OpenRouter (set OPENROUTER_API_KEY in .env)
+# To use Anthropic directly, change to: anthropic/claude-opus-4-20250514
+model:
+  model_name: "openrouter/anthropic/claude-opus-4"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 16384
+    temperature: 0

eval/configs/models/claude-sonnet.yaml

@@ -0,0 +1,9 @@
+# Claude Sonnet 4 — strong all-around model
+# Via OpenRouter (set OPENROUTER_API_KEY in .env)
+# To use Anthropic directly, change to: anthropic/claude-sonnet-4-20250514
+model:
+  model_name: "openrouter/anthropic/claude-sonnet-4"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 16384
+    temperature: 0

eval/configs/models/glm-4.7.yaml

@@ -0,0 +1,7 @@
+# GLM 4.7 — via OpenRouter (set OPENROUTER_API_KEY in .env)
+model:
+  model_name: "openrouter/zhipuai/glm-4.7"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0

eval/configs/models/glm-5.yaml

@@ -0,0 +1,7 @@
+# GLM 5 — via OpenRouter (set OPENROUTER_API_KEY in .env)
+model:
+  model_name: "openrouter/zhipuai/glm-5"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0

eval/configs/models/minimax-2.5.yaml

@@ -0,0 +1,7 @@
+# MiniMax M1 2.5 — via OpenRouter (set OPENROUTER_API_KEY in .env)
+model:
+  model_name: "openrouter/minimax/minimax-m1-2.5"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0

eval/configs/models/minimax-m2.1.yaml

@@ -0,0 +1,11 @@
+# MiniMax M2.5 — via OpenRouter (set OPENROUTER_API_KEY in .env)
+# Uses text-based model class because MiniMax doesn't support tool_calls natively.
+# The action_regex tells mini-swe-agent to parse ```bash blocks from responses.
+model:
+  model_class: litellm_textbased
+  model_name: "openrouter/minimax/minimax-m2.5"
+  action_regex: "```(?:bash|mswea_bash_command)\\s*\\n(.*?)\\n```"
+  cost_tracking: "ignore_errors"
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0

eval/configs/modes/baseline.yaml

@@ -0,0 +1,9 @@
+# Baseline mode — no GitNexus, pure mini-swe-agent (control group)
+agent:
+  agent_class: "eval.agents.gitnexus_agent.GitNexusAgent"
+  gitnexus_mode: "baseline"
+  step_limit: 30
+  cost_limit: 3.0
+
+environment:
+  environment_class: "docker"

eval/configs/modes/native.yaml

@@ -0,0 +1,19 @@
+# Native mode — GitNexus tools only, no grep enrichment
+#
+# Explicit tools: gitnexus-query, gitnexus-context, gitnexus-impact, gitnexus-cypher
+# Available as fast bash commands (~100ms via eval-server)
+#
+# Use this mode to isolate the value of explicit tools without grep augmentation.
+agent:
+  agent_class: "eval.agents.gitnexus_agent.GitNexusAgent"
+  gitnexus_mode: "native"
+  step_limit: 30
+  cost_limit: 3.0
+  track_gitnexus_usage: true
+
+environment:
+  environment_class: "eval.environments.gitnexus_docker.GitNexusDockerEnvironment"
+  enable_gitnexus: true
+  skip_embeddings: true
+  gitnexus_timeout: 120
+  eval_server_port: 4848

eval/configs/modes/native_augment.yaml

@@ -0,0 +1,24 @@
+# Native + Augment mode — the primary evaluation mode
+#
+# Combines two capabilities (mirroring the Claude Code model):
+# 1. Explicit GitNexus tools: gitnexus-query, gitnexus-context, gitnexus-impact, gitnexus-cypher
+#    Available as fast bash commands (~100ms via eval-server)
+# 2. Automatic grep enrichment: grep/rg results are transparently augmented with
+#    [GitNexus] annotations showing callers, callees, and execution flows
+#
+# The agent decides when to use explicit tools vs rely on enriched grep results.
+agent:
+  agent_class: "eval.agents.gitnexus_agent.GitNexusAgent"
+  gitnexus_mode: "native_augment"
+  step_limit: 30
+  cost_limit: 3.0
+  augment_timeout: 5.0
+  augment_min_pattern_length: 3
+  track_gitnexus_usage: true
+
+environment:
+  environment_class: "eval.environments.gitnexus_docker.GitNexusDockerEnvironment"
+  enable_gitnexus: true
+  skip_embeddings: true
+  gitnexus_timeout: 120
+  eval_server_port: 4848

eval/environments/gitnexus_docker.py

@@ -0,0 +1,397 @@
+"""
+GitNexus Docker Environment for SWE-bench Evaluation
+
+Extends mini-swe-agent's Docker environment to:
+1. Install GitNexus (Node.js + npm + gitnexus package)
+2. Run `gitnexus analyze` on the repository
+3. Start the eval-server daemon (persistent HTTP server with warm KuzuDB)
+4. Install standalone tool scripts in /usr/local/bin/ (works with subprocess.run)
+5. Cache indexes per (repo, base_commit) to avoid re-indexing
+
+IMPORTANT: mini-swe-agent runs every command with subprocess.run in a fresh subshell.
+This means .bashrc is NOT sourced, exported functions are NOT available, and env vars
+don't persist. The tool scripts must be standalone executables in $PATH.
+
+Architecture:
+  Agent bash cmd → /usr/local/bin/gitnexus-query → curl localhost:4848/tool/query → eval-server → KuzuDB
+  Fallback: → npx gitnexus query (cold start, slower)
+
+Tool call latency: ~50-100ms via eval-server, ~5-10s via CLI fallback.
+"""
+
+import hashlib
+import json
+import logging
+import shutil
+import time
+from pathlib import Path
+
+from minisweagent.environments.docker import DockerEnvironment
+
+logger = logging.getLogger("gitnexus_docker")
+
+DEFAULT_CACHE_DIR = Path.home() / ".gitnexus-eval-cache"
+EVAL_SERVER_PORT = 4848
+
+# Standalone tool scripts installed into /usr/local/bin/ inside the container.
+# Each script calls the eval-server via curl, with a CLI fallback.
+# These are standalone — no sourcing, no env inheritance needed.
+
+TOOL_SCRIPT_QUERY = r'''#!/bin/bash
+PORT="${GITNEXUS_EVAL_PORT:-__PORT__}"
+query="$1"; task_ctx="${2:-}"; goal="${3:-}"
+[ -z "$query" ] && echo "Usage: gitnexus-query <query> [task_context] [goal]" && exit 1
+args="{\"query\": \"$query\""
+[ -n "$task_ctx" ] && args="$args, \"task_context\": \"$task_ctx\""
+[ -n "$goal" ] && args="$args, \"goal\": \"$goal\""
+args="$args}"
+result=$(curl -sf -X POST "http://127.0.0.1:${PORT}/tool/query" -H "Content-Type: application/json" -d "$args" 2>/dev/null)
+if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi
+cd /testbed && npx gitnexus query "$query" 2>&1
+'''
+
+TOOL_SCRIPT_CONTEXT = r'''#!/bin/bash
+PORT="${GITNEXUS_EVAL_PORT:-__PORT__}"
+name="$1"; file_path="${2:-}"
+[ -z "$name" ] && echo "Usage: gitnexus-context <symbol_name> [file_path]" && exit 1
+args="{\"name\": \"$name\""
+[ -n "$file_path" ] && args="$args, \"file_path\": \"$file_path\""
+args="$args}"
+result=$(curl -sf -X POST "http://127.0.0.1:${PORT}/tool/context" -H "Content-Type: application/json" -d "$args" 2>/dev/null)
+if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi
+cd /testbed && npx gitnexus context "$name" 2>&1
+'''
+
+TOOL_SCRIPT_IMPACT = r'''#!/bin/bash
+PORT="${GITNEXUS_EVAL_PORT:-__PORT__}"
+target="$1"; direction="${2:-upstream}"
+[ -z "$target" ] && echo "Usage: gitnexus-impact <symbol_name> [upstream|downstream]" && exit 1
+result=$(curl -sf -X POST "http://127.0.0.1:${PORT}/tool/impact" -H "Content-Type: application/json" -d "{\"target\": \"$target\", \"direction\": \"$direction\"}" 2>/dev/null)
+if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi
+cd /testbed && npx gitnexus impact "$target" --direction "$direction" 2>&1
+'''
+
+TOOL_SCRIPT_CYPHER = r'''#!/bin/bash
+PORT="${GITNEXUS_EVAL_PORT:-__PORT__}"
+query="$1"
+[ -z "$query" ] && echo "Usage: gitnexus-cypher <cypher_query>" && exit 1
+result=$(curl -sf -X POST "http://127.0.0.1:${PORT}/tool/cypher" -H "Content-Type: application/json" -d "{\"query\": \"$query\"}" 2>/dev/null)
+if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi
+cd /testbed && npx gitnexus cypher "$query" 2>&1
+'''
+
+TOOL_SCRIPT_AUGMENT = r'''#!/bin/bash
+cd /testbed && npx gitnexus augment "$1" 2>&1 || true
+'''
+
+TOOL_SCRIPT_OVERVIEW = r'''#!/bin/bash
+PORT="${GITNEXUS_EVAL_PORT:-__PORT__}"
+echo "=== Code Knowledge Graph Overview ==="
+result=$(curl -sf -X POST "http://127.0.0.1:${PORT}/tool/list_repos" -H "Content-Type: application/json" -d "{}" 2>/dev/null)
+if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi
+cd /testbed && npx gitnexus list 2>&1
+'''
+
+
+class GitNexusDockerEnvironment(DockerEnvironment):
+    """
+    Docker environment with GitNexus pre-installed, indexed, and eval-server running.
+
+    Setup flow:
+    1. Start Docker container (base SWE-bench image)
+    2. Install Node.js + gitnexus inside the container
+    3. Run `gitnexus analyze` (or restore from cache)
+    4. Start `gitnexus eval-server` daemon (keeps KuzuDB warm)
+    5. Install standalone tool scripts in /usr/local/bin/
+    6. Agent runs with near-instant GitNexus tool calls
+    """
+
+    def __init__(
+        self,
+        *,
+        enable_gitnexus: bool = True,
+        cache_dir: str | Path | None = None,
+        skip_embeddings: bool = True,
+        gitnexus_timeout: int = 120,
+        eval_server_port: int = EVAL_SERVER_PORT,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.enable_gitnexus = enable_gitnexus
+        self.cache_dir = Path(cache_dir) if cache_dir else DEFAULT_CACHE_DIR
+        self.skip_embeddings = skip_embeddings
+        self.gitnexus_timeout = gitnexus_timeout
+        self.eval_server_port = eval_server_port
+        self.index_time: float = 0.0
+        self._gitnexus_ready = False
+
+    def start(self) -> dict:
+        """Start the container and set up GitNexus."""
+        result = super().start()
+
+        if self.enable_gitnexus:
+            try:
+                self._setup_gitnexus()
+            except Exception as e:
+                logger.warning(f"GitNexus setup failed, continuing without it: {e}")
+                self._gitnexus_ready = False
+
+        return result
+
+    def _setup_gitnexus(self):
+        """Install and configure GitNexus in the container."""
+        start = time.time()
+
+        self._ensure_nodejs()
+        self._install_gitnexus()
+        self._index_repository()
+        self._start_eval_server()
+        self._install_tools()
+
+        self.index_time = time.time() - start
+        self._gitnexus_ready = True
+        logger.info(f"GitNexus setup completed in {self.index_time:.1f}s")
+
+    def _ensure_nodejs(self):
+        """Ensure Node.js >= 18 is available in the container."""
+        check = self.execute({"command": "node --version 2>/dev/null || echo 'NOT_FOUND'"})
+        output = check.get("output", "").strip()
+
+        if "NOT_FOUND" in output:
+            logger.info("Installing Node.js in container...")
+            install_cmds = [
+                "apt-get update -qq",
+                "apt-get install -y -qq curl ca-certificates",
+                "curl -fsSL https://deb.nodesource.com/setup_20.x | bash -",
+                "apt-get install -y -qq nodejs",
+            ]
+            for cmd in install_cmds:
+                result = self.execute({"command": cmd, "timeout": 60})
+                if result.get("returncode", 1) != 0:
+                    raise RuntimeError(f"Failed to install Node.js: {result.get('output', '')}")
+        else:
+            logger.info(f"Node.js already available: {output}")
+
+    def _install_gitnexus(self):
+        """Install the gitnexus npm package globally."""
+        check = self.execute({"command": "npx gitnexus --version 2>/dev/null || echo 'NOT_FOUND'"})
+        if "NOT_FOUND" in check.get("output", ""):
+            logger.info("Installing gitnexus...")
+            result = self.execute({
+                "command": "npm install -g gitnexus",
+                "timeout": 60,
+            })
+            if result.get("returncode", 1) != 0:
+                raise RuntimeError(f"Failed to install gitnexus: {result.get('output', '')}")
+
+    def _index_repository(self):
+        """Run gitnexus analyze on the repo, using cache if available."""
+        repo_info = self._get_repo_info()
+        cache_key = self._make_cache_key(repo_info)
+        cache_path = self.cache_dir / cache_key
+
+        if cache_path.exists():
+            logger.info(f"Restoring GitNexus index from cache: {cache_key}")
+            self._restore_cache(cache_path)
+            return
+
+        logger.info("Running gitnexus analyze...")
+        skip_flag = "--skip-embeddings" if self.skip_embeddings else ""
+        result = self.execute({
+            "command": f"cd /testbed && npx gitnexus analyze . {skip_flag} 2>&1",
+            "timeout": self.gitnexus_timeout,
+        })
+
+        if result.get("returncode", 1) != 0:
+            output = result.get("output", "")
+            if "error" in output.lower() and "indexed" not in output.lower():
+                raise RuntimeError(f"gitnexus analyze failed: {output[-500:]}")
+
+        self._save_cache(cache_path, repo_info)
+
+    def _start_eval_server(self):
+        """Start the GitNexus eval-server daemon in the background."""
+        logger.info(f"Starting eval-server on port {self.eval_server_port}...")
+
+        self.execute({
+            "command": (
+                f"nohup npx gitnexus eval-server --port {self.eval_server_port} "
+                f"--idle-timeout 600 "
+                f"> /tmp/gitnexus-eval-server.log 2>&1 &"
+            ),
+            "timeout": 5,
+        })
+
+        # Wait for the server to be ready (up to 15s for KuzuDB init)
+        for i in range(30):
+            time.sleep(0.5)
+            health = self.execute({
+                "command": f"curl -sf http://127.0.0.1:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
+                "timeout": 3,
+            })
+            output = health.get("output", "").strip()
+            if "NOT_READY" not in output and "ok" in output:
+                logger.info(f"Eval-server ready after {(i + 1) * 0.5:.1f}s")
+                return
+
+        log_output = self.execute({
+            "command": "cat /tmp/gitnexus-eval-server.log 2>/dev/null | tail -20",
+        })
+        logger.warning(
+            f"Eval-server didn't become ready in 15s. "
+            f"Tools will fall back to direct CLI.\n"
+            f"Server log: {log_output.get('output', 'N/A')}"
+        )
+
+    def _install_tools(self):
+        """
+        Install standalone GitNexus tool scripts in /usr/local/bin/.
+
+        Each script is a self-contained bash script that:
+        1. Calls the eval-server via curl (fast path, ~100ms)
+        2. Falls back to direct CLI if eval-server is unavailable
+
+        These are standalone executables — no sourcing, env inheritance, or .bashrc
+        needed. This is critical because mini-swe-agent runs every command via
+        subprocess.run in a fresh subshell.
+
+        Uses heredocs with quoted delimiter to avoid all quoting/escaping issues.
+        """
+        port = str(self.eval_server_port)
+
+        tools = {
+            "gitnexus-query": TOOL_SCRIPT_QUERY,
+            "gitnexus-context": TOOL_SCRIPT_CONTEXT,
+            "gitnexus-impact": TOOL_SCRIPT_IMPACT,
+            "gitnexus-cypher": TOOL_SCRIPT_CYPHER,
+            "gitnexus-augment": TOOL_SCRIPT_AUGMENT,
+            "gitnexus-overview": TOOL_SCRIPT_OVERVIEW,
+        }
+
+        for name, script in tools.items():
+            script_content = script.replace("__PORT__", port).strip()
+            # Use heredoc with quoted delimiter — prevents all variable expansion and quoting issues
+            self.execute({
+                "command": f"cat << 'GITNEXUS_SCRIPT_EOF' > /usr/local/bin/{name}\n{script_content}\nGITNEXUS_SCRIPT_EOF\nchmod +x /usr/local/bin/{name}",
+                "timeout": 5,
+            })
+
+        logger.info(f"Installed {len(tools)} GitNexus tool scripts in /usr/local/bin/")
+
+    def _get_repo_info(self) -> dict:
+        """Get repository identity info from the container."""
+        repo_result = self.execute({
+            "command": "cd /testbed && basename $(git remote get-url origin 2>/dev/null || basename $(pwd)) .git"
+        })
+        commit_result = self.execute({"command": "cd /testbed && git rev-parse HEAD 2>/dev/null || echo unknown"})
+
+        return {
+            "repo": repo_result.get("output", "unknown").strip(),
+            "commit": commit_result.get("output", "unknown").strip(),
+        }
+
+    @staticmethod
+    def _make_cache_key(repo_info: dict) -> str:
+        """Create a deterministic cache key from repo info."""
+        content = f"{repo_info['repo']}:{repo_info['commit']}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+    def _save_cache(self, cache_path: Path, repo_info: dict):
+        """Save the GitNexus index to the host cache directory."""
+        try:
+            cache_path.mkdir(parents=True, exist_ok=True)
+
+            find_result = self.execute({
+                "command": "find /root/.gitnexus -name 'kuzu' -type d 2>/dev/null | head -1"
+            })
+            gitnexus_dir = find_result.get("output", "").strip()
+
+            if gitnexus_dir:
+                parent = str(Path(gitnexus_dir).parent)
+                self.execute({
+                    "command": f"cd {parent} && tar czf /tmp/gitnexus-cache.tar.gz .",
+                    "timeout": 30,
+                })
+
+                container_id = getattr(self, "_container_id", None) or getattr(self, "container_id", None)
+                if container_id:
+                    import subprocess as sp
+                    sp.run(
+                        ["docker", "cp", f"{container_id}:/tmp/gitnexus-cache.tar.gz",
+                         str(cache_path / "index.tar.gz")],
+                        check=True, capture_output=True,
+                    )
+                    (cache_path / "metadata.json").write_text(json.dumps(repo_info, indent=2))
+                    logger.info(f"Cached GitNexus index: {cache_path}")
+
+        except Exception as e:
+            logger.warning(f"Failed to cache GitNexus index: {e}")
+            if cache_path.exists():
+                shutil.rmtree(cache_path, ignore_errors=True)
+
+    def _restore_cache(self, cache_path: Path):
+        """Restore a cached GitNexus index into the container."""
+        try:
+            cache_tarball = cache_path / "index.tar.gz"
+            if not cache_tarball.exists():
+                logger.warning("Cache tarball not found, re-indexing")
+                self._index_repository()
+                return
+
+            container_id = getattr(self, "_container_id", None) or getattr(self, "container_id", None)
+            if container_id:
+                import subprocess as sp
+
+                self.execute({"command": "mkdir -p /root/.gitnexus"})
+
+                storage_result = self.execute({
+                    "command": "npx gitnexus list 2>/dev/null | grep -o '/root/.gitnexus/[^ ]*' | head -1 || echo '/root/.gitnexus/repos/default'"
+                })
+                storage_path = storage_result.get("output", "").strip() or "/root/.gitnexus/repos/default"
+                self.execute({"command": f"mkdir -p {storage_path}"})
+
+                sp.run(
+                    ["docker", "cp", str(cache_tarball), f"{container_id}:/tmp/gitnexus-cache.tar.gz"],
+                    check=True, capture_output=True,
+                )
+                self.execute({
+                    "command": f"cd {storage_path} && tar xzf /tmp/gitnexus-cache.tar.gz",
+                    "timeout": 30,
+                })
+                logger.info("GitNexus index restored from cache")
+
+        except Exception as e:
+            logger.warning(f"Failed to restore cache, re-indexing: {e}")
+            self._index_repository()
+
+    def stop(self) -> dict:
+        """Stop the container, shutting down eval-server first."""
+        if self._gitnexus_ready:
+            try:
+                self.execute({
+                    "command": f"curl -sf -X POST http://127.0.0.1:{self.eval_server_port}/shutdown 2>/dev/null || true",
+                    "timeout": 3,
+                })
+            except Exception:
+                pass
+
+        return super().stop()
+
+    def get_template_vars(self) -> dict:
+        """Add GitNexus-specific template variables."""
+        base_vars = super().get_template_vars()
+        base_vars["gitnexus_ready"] = self._gitnexus_ready
+        base_vars["gitnexus_index_time"] = self.index_time
+        return base_vars
+
+    def serialize(self) -> dict:
+        """Include GitNexus environment info in serialization."""
+        base = super().serialize()
+        base.setdefault("info", {})["gitnexus_env"] = {
+            "enabled": self.enable_gitnexus,
+            "ready": self._gitnexus_ready,
+            "index_time_seconds": round(self.index_time, 2),
+            "skip_embeddings": self.skip_embeddings,
+            "eval_server_port": self.eval_server_port,
+        }
+        return base

eval/prompts/instance_baseline.jinja

@@ -0,0 +1,80 @@
+Please solve this issue: {{task}}
+
+You can execute bash commands and edit files to implement the necessary changes.
+
+## Recommended Workflow
+
+This workflows should be done step-by-step so that you can iterate on your changes and any possible problems.
+
+1. Analyze the codebase by finding and reading relevant files
+2. Create a script to reproduce the issue
+3. Edit the source code to resolve the issue
+4. Verify your fix works by running your script again
+5. Test edge cases to ensure your fix is robust
+6. Submit your changes and finish your work by issuing the following command: `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`.
+   Do not combine it with any other command. After this command, you cannot continue working on this task.
+
+## Important Rules
+
+1. Every response must contain exactly one action
+2. The action must be enclosed in triple backticks
+3. Directory or environment variable changes are not persistent. Every action is executed in a new subshell.
+   However, you can prefix any action with `MY_ENV_VAR=MY_VALUE cd /path/to/working/dir && ...` or write/load environment variables from files
+
+<system_info>
+{{system}} {{release}} {{version}} {{machine}}
+</system_info>
+
+## Formatting your response
+
+Here is an example of a correct response:
+
+<example_response>
+THOUGHT: I need to understand the structure of the repository first. Let me check what files are in the current directory to get a better understanding of the codebase.
+
+```mswea_bash_command
+ls -la
+```
+</example_response>
+
+## Useful command examples
+
+### Create a new file:
+
+```bash
+cat <<'EOF' > newfile.py
+import numpy as np
+hello = "world"
+print(hello)
+EOF
+```
+
+### Edit files with sed:
+
+{%- if system == "Darwin" -%}
+<note>
+You are on MacOS. For all the below examples, you need to use `sed -i ''` instead of `sed -i`.
+</note>
+{%- endif -%}
+
+```bash
+# Replace all occurrences
+sed -i 's/old_string/new_string/g' filename.py
+# Replace only first occurrence
+sed -i 's/old_string/new_string/' filename.py
+# Replace all occurrences in lines 1-10
+sed -i '1,10s/old_string/new_string/g' filename.py
+```
+
+### View file content:
+
+```bash
+# View specific lines with numbers
+nl -ba filename.py | sed -n '10,20p'
+```
+
+### Any other command you want to run
+
+```bash
+anything
+```

eval/prompts/instance_native.jinja

@@ -0,0 +1,102 @@
+Please solve this issue: {{task}}
+
+You can execute bash commands and edit files to implement the necessary changes.
+
+## Recommended Workflow
+
+Work step-by-step so you can iterate on your changes and catch problems early.
+
+1. **Understand the issue** — read the problem statement, identify the symptom and affected area
+2. **Find the relevant code** — use `gitnexus-query "<feature area>"` to find execution flows, or `grep` for specific strings
+3. **Understand the suspect** — use `gitnexus-context "<symbol>"` to see all callers and callees, then `cat` to read the source
+4. **Check blast radius** — before editing shared code, run `gitnexus-impact "<symbol>" upstream` to see what depends on it
+5. **Implement the fix** — make minimal, targeted changes
+6. **Verify** — run relevant tests, check edge cases
+7. **Submit** — issue: `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`
+   Do not combine it with any other command. After this command, you cannot continue working on this task.
+
+## Debugging Patterns
+
+| Symptom | Approach |
+|---------|----------|
+| Error message / exception | `gitnexus-query` for error text → `gitnexus-context` on throw sites |
+| Wrong return value | `gitnexus-context` on the function → trace callees for data flow |
+| Missing feature / incomplete behavior | `gitnexus-query` for feature area → find the execution flow → locate the gap |
+| Need to understand callers | `gitnexus-context` — graph-complete, finds callers grep would miss |
+
+## Risk Assessment
+
+Before editing shared code, check the blast radius:
+
+| Impact | Risk | Action |
+|--------|------|--------|
+| <5 symbols at d=1 | Low | Fix with confidence |
+| 5-15 symbols at d=1 | Medium | Fix carefully, run broader tests |
+| >15 symbols at d=1 | High | Minimal change, run full test suite |
+
+## Important Rules
+
+1. Every response must contain exactly one action
+2. The action must be enclosed in triple backticks
+3. Directory or environment variable changes are not persistent. Every action is executed in a new subshell.
+   However, you can prefix any action with `MY_ENV_VAR=MY_VALUE cd /path/to/working/dir && ...` or write/load environment variables from files
+4. Make minimal, targeted changes. Don't refactor unrelated code.
+5. GitNexus tools are ~100ms. Use them when they save you multiple grep iterations.
+
+<system_info>
+{{system}} {{release}} {{version}} {{machine}}
+</system_info>
+
+## Formatting your response
+
+Here is an example of a correct response:
+
+<example_response>
+THOUGHT: The issue mentions a problem with form field validation. Let me search the code knowledge graph for the relevant execution flows to understand how validation works in this codebase.
+
+```mswea_bash_command
+gitnexus-query "form field validation"
+```
+</example_response>
+
+## Useful command examples
+
+### Create a new file:
+
+```bash
+cat <<'EOF' > newfile.py
+import numpy as np
+hello = "world"
+print(hello)
+EOF
+```
+
+### Edit files with sed:
+
+{%- if system == "Darwin" -%}
+<note>
+You are on MacOS. For all the below examples, you need to use `sed -i ''` instead of `sed -i`.
+</note>
+{%- endif -%}
+
+```bash
+# Replace all occurrences
+sed -i 's/old_string/new_string/g' filename.py
+# Replace only first occurrence
+sed -i 's/old_string/new_string/' filename.py
+# Replace all occurrences in lines 1-10
+sed -i '1,10s/old_string/new_string/g' filename.py
+```
+
+### View file content:
+
+```bash
+# View specific lines with numbers
+nl -ba filename.py | sed -n '10,20p'
+```
+
+### Any other command you want to run
+
+```bash
+anything
+```

eval/prompts/instance_native_augment.jinja

@@ -0,0 +1,103 @@
+Please solve this issue: {{task}}
+
+You can execute bash commands and edit files to implement the necessary changes.
+
+## Recommended Workflow
+
+Work step-by-step so you can iterate on your changes and catch problems early.
+
+1. **Understand the issue** — read the problem statement, identify the symptom and affected area
+2. **Find the relevant code** — use `gitnexus-query "<feature area>"` to find execution flows, or `grep` for specific strings
+3. **Understand the suspect** — use `gitnexus-context "<symbol>"` to see all callers and callees, then `cat` to read the source
+4. **Check blast radius** — before editing shared code, run `gitnexus-impact "<symbol>" upstream` to see what depends on it
+5. **Implement the fix** — make minimal, targeted changes
+6. **Verify** — run relevant tests, check edge cases
+7. **Submit** — issue: `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`
+   Do not combine it with any other command. After this command, you cannot continue working on this task.
+
+## Debugging Patterns
+
+| Symptom | Approach |
+|---------|----------|
+| Error message / exception | `gitnexus-query` for error text → `gitnexus-context` on throw sites |
+| Wrong return value | `gitnexus-context` on the function → trace callees for data flow |
+| Missing feature / incomplete behavior | `gitnexus-query` for feature area → find the execution flow → locate the gap |
+| Need to understand callers | `gitnexus-context` — graph-complete, finds callers grep would miss |
+
+## Risk Assessment
+
+Before editing shared code, check the blast radius:
+
+| Impact | Risk | Action |
+|--------|------|--------|
+| <5 symbols at d=1 | Low | Fix with confidence |
+| 5-15 symbols at d=1 | Medium | Fix carefully, run broader tests |
+| >15 symbols at d=1 | High | Minimal change, run full test suite |
+
+## Important Rules
+
+1. Every response must contain exactly one action
+2. The action must be enclosed in triple backticks
+3. Directory or environment variable changes are not persistent. Every action is executed in a new subshell.
+   However, you can prefix any action with `MY_ENV_VAR=MY_VALUE cd /path/to/working/dir && ...` or write/load environment variables from files
+4. Make minimal, targeted changes. Don't refactor unrelated code.
+5. GitNexus tools are ~100ms. Use them when they save you multiple grep iterations.
+6. When grep results show `[GitNexus]` enrichments, use those for navigation.
+
+<system_info>
+{{system}} {{release}} {{version}} {{machine}}
+</system_info>
+
+## Formatting your response
+
+Here is an example of a correct response:
+
+<example_response>
+THOUGHT: The issue mentions a problem with form field validation. Let me search the code knowledge graph for the relevant execution flows to understand how validation works in this codebase.
+
+```mswea_bash_command
+gitnexus-query "form field validation"
+```
+</example_response>
+
+## Useful command examples
+
+### Create a new file:
+
+```bash
+cat <<'EOF' > newfile.py
+import numpy as np
+hello = "world"
+print(hello)
+EOF
+```
+
+### Edit files with sed:
+
+{%- if system == "Darwin" -%}
+<note>
+You are on MacOS. For all the below examples, you need to use `sed -i ''` instead of `sed -i`.
+</note>
+{%- endif -%}
+
+```bash
+# Replace all occurrences
+sed -i 's/old_string/new_string/g' filename.py
+# Replace only first occurrence
+sed -i 's/old_string/new_string/' filename.py
+# Replace all occurrences in lines 1-10
+sed -i '1,10s/old_string/new_string/g' filename.py
+```
+
+### View file content:
+
+```bash
+# View specific lines with numbers
+nl -ba filename.py | sed -n '10,20p'
+```
+
+### Any other command you want to run
+
+```bash
+anything
+```

eval/prompts/system_baseline.jinja

@@ -0,0 +1,15 @@
+You are a helpful assistant that can interact with a computer to solve software engineering tasks.
+
+Your response must contain exactly ONE bash code block with ONE command (or commands connected with && or ||).
+Include a THOUGHT section before your command where you explain your reasoning process.
+Format your response as shown in.
+
+<example_response>
+Your reasoning and analysis here. Explain why you want to perform the action.
+
+```mswea_bash_command
+your_command_here
+```
+</example_response>
+
+Failure to follow these rules will cause your response to be rejected.

eval/prompts/system_native.jinja

@@ -0,0 +1,54 @@
+You are a helpful assistant that can interact with a computer to solve software engineering tasks.
+
+Your response must contain exactly ONE bash code block with ONE command (or commands connected with && or ||).
+Include a THOUGHT section before your command where you explain your reasoning process.
+Format your response as shown in.
+
+<example_response>
+Your reasoning and analysis here. Explain why you want to perform the action.
+
+```mswea_bash_command
+your_command_here
+```
+</example_response>
+
+Failure to follow these rules will cause your response to be rejected.
+
+## Code Intelligence
+
+You have **GitNexus** — a knowledge graph over this entire codebase. It knows every function call chain, class hierarchy, execution flow, and symbol relationship. These are fast bash commands (~100ms). Use them when useful, skip them when a simple grep suffices.
+
+### GitNexus Commands
+
+**gitnexus-query "<concept>"** — Find execution flows related to a concept.
+Returns ranked execution flow traces with participating symbols and file locations.
+```bash
+gitnexus-query "form field validation"
+```
+
+**gitnexus-context "<symbol>" ["<file_path>"]** — 360-degree view of a symbol.
+Returns ALL callers, ALL callees, and execution flows. Graph-complete — finds callers that grep misses.
+```bash
+gitnexus-context "BoundField" "django/forms/boundfield.py"
+```
+
+**gitnexus-impact "<symbol>" [upstream|downstream]** — Blast radius analysis.
+What breaks if you change this: d=1 WILL BREAK, d=2 LIKELY AFFECTED, d=3 MAY NEED TESTING.
+```bash
+gitnexus-impact "BoundField" upstream
+```
+
+**gitnexus-cypher "<query>"** — Raw Cypher query against the code graph.
+```bash
+gitnexus-cypher 'MATCH (a)-[:CodeRelation {type: "CALLS"}]->(b:Function {name: "clean"}) RETURN a.name, a.filePath'
+```
+
+### When to Use What
+
+| I need to... | Use |
+|---|---|
+| Understand how a feature works end-to-end | `gitnexus-query` |
+| Find ALL callers of a function | `gitnexus-context` |
+| Know what breaks if I change something | `gitnexus-impact` upstream |
+| Find a string literal or error message | `grep` |
+| Read source code | `cat` / `nl -ba` |

eval/prompts/system_native_augment.jinja

@@ -0,0 +1,56 @@
+You are a helpful assistant that can interact with a computer to solve software engineering tasks.
+
+Your response must contain exactly ONE bash code block with ONE command (or commands connected with && or ||).
+Include a THOUGHT section before your command where you explain your reasoning process.
+Format your response as shown in.
+
+<example_response>
+Your reasoning and analysis here. Explain why you want to perform the action.
+
+```mswea_bash_command
+your_command_here
+```
+</example_response>
+
+Failure to follow these rules will cause your response to be rejected.
+
+## Code Intelligence
+
+You have **GitNexus** — a knowledge graph over this entire codebase. It knows every function call chain, class hierarchy, execution flow, and symbol relationship. These are fast bash commands (~100ms). Use them when useful, skip them when a simple grep suffices.
+
+Your `grep` results are also automatically enriched with `[GitNexus]` annotations showing callers, callees, and execution flows for matched symbols. Pay attention to these — they often point you to the right code without extra tool calls.
+
+### GitNexus Commands
+
+**gitnexus-query "<concept>"** — Find execution flows related to a concept.
+Returns ranked execution flow traces with participating symbols and file locations.
+```bash
+gitnexus-query "form field validation"
+```
+
+**gitnexus-context "<symbol>" ["<file_path>"]** — 360-degree view of a symbol.
+Returns ALL callers, ALL callees, and execution flows. Graph-complete — finds callers that grep misses.
+```bash
+gitnexus-context "BoundField" "django/forms/boundfield.py"
+```
+
+**gitnexus-impact "<symbol>" [upstream|downstream]** — Blast radius analysis.
+What breaks if you change this: d=1 WILL BREAK, d=2 LIKELY AFFECTED, d=3 MAY NEED TESTING.
+```bash
+gitnexus-impact "BoundField" upstream
+```
+
+**gitnexus-cypher "<query>"** — Raw Cypher query against the code graph.
+```bash
+gitnexus-cypher 'MATCH (a)-[:CodeRelation {type: "CALLS"}]->(b:Function {name: "clean"}) RETURN a.name, a.filePath'
+```
+
+### When to Use What
+
+| I need to... | Use |
+|---|---|
+| Understand how a feature works end-to-end | `gitnexus-query` |
+| Find ALL callers of a function | `gitnexus-context` |
+| Know what breaks if I change something | `gitnexus-impact` upstream |
+| Find a string literal or error message | `grep` |
+| Read source code | `cat` / `nl -ba` |

eval/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "gitnexus-swebench-eval"
+version = "0.1.0"
+description = "SWE-bench evaluation harness with GitNexus code intelligence integration"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mini-swe-agent>=2.0.0",
+    "litellm>=1.50.0",
+    "datasets>=3.0.0",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0",
+    "pandas>=2.0.0",
+    "tabulate>=0.9.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.5.0",
+]
+
+[project.scripts]
+gitnexus-eval = "run_eval:app"
+gitnexus-eval-analyze = "analysis.analyze_results:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agents", "environments", "analysis", "bridge"]
+extra-files = ["run_eval.py"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"

eval/run_eval.py

@@ -0,0 +1,515 @@
+#!/usr/bin/env python3
+"""
+GitNexus SWE-bench Evaluation Runner
+
+Main entry point for running SWE-bench evaluations with and without GitNexus.
+Supports running a single configuration or a full matrix of models x modes.
+
+Usage:
+    # Single run (default: native_augment mode — GitNexus tools + grep enrichment)
+    python run_eval.py single -m claude-sonnet --subset lite --slice 0:5
+
+    # Baseline comparison (no GitNexus)
+    python run_eval.py single -m claude-sonnet --mode baseline --subset lite --slice 0:5
+
+    # Matrix run (all models x all modes)
+    python run_eval.py matrix --subset lite --slice 0:50 --workers 4
+
+    # Single instance for debugging
+    python run_eval.py debug -m claude-haiku -i django__django-16527
+"""
+
+import concurrent.futures
+import json
+import logging
+import os
+import threading
+import time
+import traceback
+from itertools import product
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+
+# Load .env file from eval/ directory
+_env_file = Path(__file__).parent / ".env"
+if _env_file.exists():
+    for line in _env_file.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            key, _, value = line.partition("=")
+            key, value = key.strip(), value.strip()
+            if value and key not in os.environ:  # Don't override existing env vars
+                os.environ[key] = value
+
+logger = logging.getLogger("gitnexus_eval")
+console = Console()
+app = typer.Typer(rich_markup_mode="rich", add_completion=False)
+
+# Directory paths
+EVAL_DIR = Path(__file__).parent
+CONFIGS_DIR = EVAL_DIR / "configs"
+MODELS_DIR = CONFIGS_DIR / "models"
+MODES_DIR = CONFIGS_DIR / "modes"
+DEFAULT_OUTPUT_DIR = EVAL_DIR / "results"
+
+# Available models and modes (discovered from config files)
+AVAILABLE_MODELS = sorted([p.stem for p in MODELS_DIR.glob("*.yaml")])
+AVAILABLE_MODES = sorted([p.stem for p in MODES_DIR.glob("*.yaml")])
+
+# SWE-bench dataset mapping (same as mini-swe-agent)
+DATASET_MAPPING = {
+    "full": "princeton-nlp/SWE-Bench",
+    "verified": "princeton-nlp/SWE-Bench_Verified",
+    "lite": "princeton-nlp/SWE-Bench_Lite",
+}
+
+_output_lock = threading.Lock()
+
+
+def load_yaml_config(path: Path) -> dict:
+    """Load a YAML config file."""
+    with open(path) as f:
+        return yaml.safe_load(f) or {}
+
+
+def merge_configs(*configs: dict) -> dict:
+    """Recursively merge multiple config dicts (later values win)."""
+    result = {}
+    for config in configs:
+        for key, value in config.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = merge_configs(result[key], value)
+            else:
+                result[key] = value
+    return result
+
+
+def build_config(model_name: str, mode_name: str) -> dict:
+    """Build a complete config from model + mode YAML files."""
+    model_file = MODELS_DIR / f"{model_name}.yaml"
+    mode_file = MODES_DIR / f"{mode_name}.yaml"
+
+    if not model_file.exists():
+        raise FileNotFoundError(f"Model config not found: {model_file}")
+    if not mode_file.exists():
+        raise FileNotFoundError(f"Mode config not found: {mode_file}")
+
+    model_config = load_yaml_config(model_file)
+    mode_config = load_yaml_config(mode_file)
+
+    return merge_configs(mode_config, model_config)
+
+
+def load_instances(subset: str, split: str, slice_spec: str = "", filter_spec: str = "") -> list[dict]:
+    """Load SWE-bench instances."""
+    from datasets import load_dataset
+    import re
+
+    dataset_path = DATASET_MAPPING.get(subset, subset)
+    logger.info(f"Loading dataset: {dataset_path}, split: {split}")
+    instances = list(load_dataset(dataset_path, split=split))
+
+    if filter_spec:
+        instances = [i for i in instances if re.match(filter_spec, i["instance_id"])]
+
+    if slice_spec:
+        values = [int(x) if x else None for x in slice_spec.split(":")]
+        instances = instances[slice(*values)]
+
+    logger.info(f"Loaded {len(instances)} instances")
+    return instances
+
+
+def get_swebench_docker_image(instance: dict) -> str:
+    """Get Docker image name for a SWE-bench instance."""
+    image_name = instance.get("image_name")
+    if image_name is None:
+        iid = instance["instance_id"]
+        id_docker = iid.replace("__", "_1776_")
+        image_name = f"docker.io/swebench/sweb.eval.x86_64.{id_docker}:latest".lower()
+    return image_name
+
+
+def process_instance(
+    instance: dict,
+    config: dict,
+    output_dir: Path,
+    model_name: str,
+    mode_name: str,
+) -> dict:
+    """
+    Process a single SWE-bench instance with the given config.
+    Returns result dict with instance_id, exit_status, submission, metrics.
+    """
+    from minisweagent.models import get_model
+
+    instance_id = instance["instance_id"]
+    run_id = f"{model_name}_{mode_name}"
+    instance_dir = output_dir / run_id / instance_id
+    instance_dir.mkdir(parents=True, exist_ok=True)
+
+    result = {
+        "instance_id": instance_id,
+        "model": model_name,
+        "mode": mode_name,
+        "exit_status": None,
+        "submission": "",
+        "cost": 0.0,
+        "n_calls": 0,
+        "gitnexus_metrics": {},
+    }
+
+    agent = None
+
+    try:
+        # Build model
+        model = get_model(config=config.get("model", {}))
+
+        # Build environment
+        env_config = dict(config.get("environment", {}))
+        env_class_name = env_config.pop("environment_class", "docker")
+
+        if env_class_name == "eval.environments.gitnexus_docker.GitNexusDockerEnvironment":
+            from environments.gitnexus_docker import GitNexusDockerEnvironment
+            env_config["image"] = get_swebench_docker_image(instance)
+            env = GitNexusDockerEnvironment(**env_config)
+        else:
+            from minisweagent.environments.docker import DockerEnvironment
+            env = DockerEnvironment(image=get_swebench_docker_image(instance), **env_config)
+
+        # Build agent
+        agent_config = dict(config.get("agent", {}))
+        agent_class_name = agent_config.pop("agent_class", "eval.agents.gitnexus_agent.GitNexusAgent")
+
+        from agents.gitnexus_agent import GitNexusAgent
+        traj_path = instance_dir / f"{instance_id}.traj.json"
+        agent_config["output_path"] = traj_path
+        agent = GitNexusAgent(model, env, **agent_config)
+
+        # Run
+        logger.info(f"[{run_id}] Starting {instance_id}")
+        info = agent.run(instance["problem_statement"])
+
+        result["exit_status"] = info.get("exit_status")
+        result["cost"] = agent.cost
+        result["n_calls"] = agent.n_calls
+        result["gitnexus_metrics"] = agent.gitnexus_metrics.to_dict()
+
+        # Extract git diff patch from the container (SWE-bench needs the model_patch)
+        try:
+            patch_output = env.execute({"command": "cd /testbed && git diff"})
+            result["submission"] = patch_output.get("output", "").strip()
+        except Exception as patch_err:
+            logger.warning(f"[{run_id}] Failed to extract patch: {patch_err}")
+            result["submission"] = info.get("submission", "")
+
+    except Exception as e:
+        logger.error(f"[{run_id}] Error on {instance_id}: {e}")
+        result["exit_status"] = type(e).__name__
+        result["error"] = str(e)
+        result["traceback"] = traceback.format_exc()
+
+    finally:
+        if agent:
+            agent.save(
+                instance_dir / f"{instance_id}.traj.json",
+                {"instance_id": instance_id, "run_id": run_id},
+            )
+
+        # Update predictions file
+        _update_preds(output_dir / run_id / "preds.json", instance_id, model_name, result)
+
+    return result
+
+
+def _update_preds(preds_path: Path, instance_id: str, model_name: str, result: dict):
+    """Thread-safe update of predictions file."""
+    with _output_lock:
+        preds_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {}
+        if preds_path.exists():
+            data = json.loads(preds_path.read_text())
+        data[instance_id] = {
+            "model_name_or_path": model_name,
+            "instance_id": instance_id,
+            "model_patch": result.get("submission", ""),
+        }
+        preds_path.write_text(json.dumps(data, indent=2))
+
+
+def run_configuration(
+    model_name: str,
+    mode_name: str,
+    instances: list[dict],
+    output_dir: Path,
+    workers: int = 1,
+    redo_existing: bool = False,
+) -> list[dict]:
+    """Run a single (model, mode) configuration across all instances."""
+    config = build_config(model_name, mode_name)
+    run_id = f"{model_name}_{mode_name}"
+    run_dir = output_dir / run_id
+
+    # Skip existing instances
+    if not redo_existing and (run_dir / "preds.json").exists():
+        existing = set(json.loads((run_dir / "preds.json").read_text()).keys())
+        instances = [i for i in instances if i["instance_id"] not in existing]
+        if not instances:
+            logger.info(f"[{run_id}] All instances already completed, skipping")
+            return []
+
+    console.print(f"  [bold]{run_id}[/bold]: {len(instances)} instances, {workers} workers")
+
+    results = []
+
+    if workers <= 1:
+        for instance in instances:
+            result = process_instance(instance, config, output_dir, model_name, mode_name)
+            results.append(result)
+    else:
+        with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
+            futures = {
+                executor.submit(
+                    process_instance, instance, config, output_dir, model_name, mode_name
+                ): instance["instance_id"]
+                for instance in instances
+            }
+            for future in concurrent.futures.as_completed(futures):
+                try:
+                    results.append(future.result())
+                except Exception as e:
+                    iid = futures[future]
+                    logger.error(f"[{run_id}] Uncaught error for {iid}: {e}")
+
+    # Save run summary
+    summary = {
+        "run_id": run_id,
+        "model": model_name,
+        "mode": mode_name,
+        "config": config,
+        "total_instances": len(results),
+        "completed": sum(1 for r in results if r["exit_status"] not in [None, "error"]),
+        "total_cost": sum(r.get("cost", 0) for r in results),
+        "total_api_calls": sum(r.get("n_calls", 0) for r in results),
+        "results": results,
+    }
+    (run_dir / "summary.json").mkdir(parents=True, exist_ok=True) if not run_dir.exists() else None
+    run_dir.mkdir(parents=True, exist_ok=True)
+    (run_dir / "summary.json").write_text(json.dumps(summary, indent=2, default=str))
+
+    return results
+
+
+# ─── CLI Commands ───────────────────────────────────────────────────────────
+
+
+@app.command()
+def single(
+    model: str = typer.Option(..., "-m", "--model", help=f"Model config name. Available: {', '.join(AVAILABLE_MODELS)}"),
+    mode: str = typer.Option("native_augment", "--mode", help=f"Evaluation mode. Available: {', '.join(AVAILABLE_MODES)}"),
+    subset: str = typer.Option("lite", "--subset", help="SWE-bench subset: lite, verified, full"),
+    split: str = typer.Option("dev", "--split", help="Dataset split"),
+    slice_spec: str = typer.Option("", "--slice", help="Slice spec (e.g., '0:5')"),
+    filter_spec: str = typer.Option("", "--filter", help="Filter instance IDs by regex"),
+    workers: int = typer.Option(1, "-w", "--workers", help="Parallel workers"),
+    output: str = typer.Option(str(DEFAULT_OUTPUT_DIR), "-o", "--output", help="Output directory"),
+    redo: bool = typer.Option(False, "--redo", help="Redo existing instances"),
+):
+    """Run a single (model, mode) configuration on SWE-bench."""
+    output_dir = Path(output)
+    instances = load_instances(subset, split, slice_spec, filter_spec)
+
+    console.print(f"\n[bold]Running evaluation:[/bold] {model} + {mode}")
+    console.print(f"  Instances: {len(instances)}")
+    console.print(f"  Output: {output_dir}\n")
+
+    results = run_configuration(model, mode, instances, output_dir, workers, redo)
+
+    # Print summary
+    _print_summary(results, model, mode)
+
+
+@app.command()
+def matrix(
+    models: list[str] = typer.Option(AVAILABLE_MODELS, "-m", "--models", help="Models to evaluate (comma-separated or repeated)"),
+    modes: list[str] = typer.Option(AVAILABLE_MODES, "--modes", help="Modes to evaluate"),
+    subset: str = typer.Option("lite", "--subset", help="SWE-bench subset"),
+    split: str = typer.Option("dev", "--split", help="Dataset split"),
+    slice_spec: str = typer.Option("", "--slice", help="Slice spec"),
+    filter_spec: str = typer.Option("", "--filter", help="Filter instances by regex"),
+    workers: int = typer.Option(1, "-w", "--workers", help="Parallel workers per config"),
+    output: str = typer.Option(str(DEFAULT_OUTPUT_DIR), "-o", "--output", help="Output directory"),
+    redo: bool = typer.Option(False, "--redo", help="Redo existing instances"),
+):
+    """Run the full evaluation matrix: all models x all modes."""
+    output_dir = Path(output)
+    instances = load_instances(subset, split, slice_spec, filter_spec)
+
+    combos = list(product(models, modes))
+    console.print(f"\n[bold]Matrix evaluation:[/bold] {len(models)} models x {len(modes)} modes = {len(combos)} configs")
+    console.print(f"  Models: {', '.join(models)}")
+    console.print(f"  Modes: {', '.join(modes)}")
+    console.print(f"  Instances per config: {len(instances)}")
+    console.print(f"  Total runs: {len(combos) * len(instances)}")
+    console.print(f"  Output: {output_dir}\n")
+
+    all_results = {}
+    for model_name, mode_name in combos:
+        run_id = f"{model_name}_{mode_name}"
+        console.print(f"\n[bold cyan]━━━ {run_id} ━━━[/bold cyan]")
+        results = run_configuration(model_name, mode_name, instances, output_dir, workers, redo)
+        all_results[run_id] = results
+
+    # Print comparative summary
+    _print_matrix_summary(all_results)
+
+    # Save master summary
+    master = {
+        "timestamp": time.time(),
+        "models": models,
+        "modes": modes,
+        "subset": subset,
+        "n_instances": len(instances),
+        "runs": {
+            run_id: {
+                "total": len(results),
+                "cost": sum(r.get("cost", 0) for r in results),
+                "api_calls": sum(r.get("n_calls", 0) for r in results),
+            }
+            for run_id, results in all_results.items()
+        },
+    }
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "matrix_summary.json").write_text(json.dumps(master, indent=2, default=str))
+    console.print(f"\n[green]Results saved to {output_dir}[/green]")
+
+
+@app.command()
+def debug(
+    model: str = typer.Option("claude-haiku", "-m", "--model", help="Model config name"),
+    mode: str = typer.Option("native_augment", "--mode", help="Evaluation mode"),
+    instance_id: str = typer.Option(..., "-i", "--instance", help="SWE-bench instance ID"),
+    subset: str = typer.Option("lite", "--subset", help="SWE-bench subset"),
+    split: str = typer.Option("dev", "--split"),
+    output: str = typer.Option(str(DEFAULT_OUTPUT_DIR / "debug"), "-o", "--output"),
+):
+    """Debug a single SWE-bench instance."""
+    from datasets import load_dataset
+
+    dataset_path = DATASET_MAPPING.get(subset, subset)
+    instances = {inst["instance_id"]: inst for inst in load_dataset(dataset_path, split=split)}
+
+    if instance_id not in instances:
+        console.print(f"[red]Instance '{instance_id}' not found in {subset}/{split}[/red]")
+        raise typer.Exit(1)
+
+    instance = instances[instance_id]
+    config = build_config(model, mode)
+    output_dir = Path(output)
+
+    console.print(f"\n[bold]Debug run:[/bold] {model} + {mode}")
+    console.print(f"  Instance: {instance_id}")
+    console.print(f"  Problem: {instance['problem_statement'][:200]}...\n")
+
+    result = process_instance(instance, config, output_dir, model, mode)
+    _print_summary([result], model, mode)
+
+
+@app.command()
+def list_configs():
+    """List available model and mode configurations."""
+    console.print("\n[bold]Available Models:[/bold]")
+    for name in AVAILABLE_MODELS:
+        config = load_yaml_config(MODELS_DIR / f"{name}.yaml")
+        model_name = config.get("model", {}).get("model_name", "unknown")
+        console.print(f"  {name:<20} {model_name}")
+
+    console.print("\n[bold]Available Modes:[/bold]")
+    for name in AVAILABLE_MODES:
+        config = load_yaml_config(MODES_DIR / f"{name}.yaml")
+        gn_mode = config.get("agent", {}).get("gitnexus_mode", "baseline")
+        console.print(f"  {name:<20} gitnexus_mode={gn_mode}")
+
+    console.print(f"\n[bold]Matrix:[/bold] {len(AVAILABLE_MODELS)} models x {len(AVAILABLE_MODES)} modes = {len(AVAILABLE_MODELS) * len(AVAILABLE_MODES)} configurations")
+
+
+# ─── Summary Output ────────────────────────────────────────────────────────
+
+
+def _print_summary(results: list[dict], model: str, mode: str):
+    """Print a summary table for a single run."""
+    if not results:
+        console.print("[yellow]No results to display[/yellow]")
+        return
+
+    table = Table(title=f"{model} + {mode}")
+    table.add_column("Metric", style="bold")
+    table.add_column("Value")
+
+    total = len(results)
+    completed = sum(1 for r in results if r.get("submission"))
+    total_cost = sum(r.get("cost", 0) for r in results)
+    total_calls = sum(r.get("n_calls", 0) for r in results)
+
+    table.add_row("Instances", str(total))
+    table.add_row("Completed", f"{completed}/{total}")
+    table.add_row("Total Cost", f"${total_cost:.4f}")
+    table.add_row("Total API Calls", str(total_calls))
+    table.add_row("Avg Cost/Instance", f"${total_cost / max(total, 1):.4f}")
+    table.add_row("Avg Calls/Instance", f"{total_calls / max(total, 1):.1f}")
+
+    # GitNexus-specific metrics
+    gn_tool_calls = sum(
+        r.get("gitnexus_metrics", {}).get("total_tool_calls", 0) for r in results
+    )
+    gn_augment_hits = sum(
+        r.get("gitnexus_metrics", {}).get("augmentation_hits", 0) for r in results
+    )
+    if gn_tool_calls > 0:
+        table.add_row("GitNexus Tool Calls", str(gn_tool_calls))
+    if gn_augment_hits > 0:
+        table.add_row("Augmentation Hits", str(gn_augment_hits))
+
+    console.print(table)
+
+
+def _print_matrix_summary(all_results: dict[str, list[dict]]):
+    """Print a comparative matrix summary."""
+    table = Table(title="Evaluation Matrix Summary")
+    table.add_column("Configuration", style="bold")
+    table.add_column("Instances")
+    table.add_column("Completed")
+    table.add_column("Cost")
+    table.add_column("API Calls")
+    table.add_column("GN Tools")
+
+    for run_id, results in sorted(all_results.items()):
+        total = len(results)
+        completed = sum(1 for r in results if r.get("submission"))
+        cost = sum(r.get("cost", 0) for r in results)
+        calls = sum(r.get("n_calls", 0) for r in results)
+        gn_calls = sum(r.get("gitnexus_metrics", {}).get("total_tool_calls", 0) for r in results)
+
+        table.add_row(
+            run_id,
+            str(total),
+            f"{completed}/{total}",
+            f"${cost:.2f}",
+            str(calls),
+            str(gn_calls) if gn_calls > 0 else "-",
+        )
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(name)s] %(message)s")
+    app()

gitnexus-claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "gitnexus",
+  "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
+  "version": "1.3.6",
+  "author": {
+    "name": "GitNexus"
+  },
+  "homepage": "https://github.com/abhigyanpatwari/GitNexus",
+  "repository": "https://github.com/abhigyanpatwari/GitNexus",
+  "keywords": ["code-intelligence", "knowledge-graph", "mcp", "static-analysis"]
+}

gitnexus-claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-claude-plugin/hooks/gitnexus-hook.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * GitNexus Claude Code Plugin Hook
+ *
+ * PreToolUse  — intercepts Grep/Glob/Bash searches and augments
+ *               with graph context from the GitNexus index.
+ * PostToolUse — detects stale index after git mutations and notifies
+ *               the agent to reindex.
+ *
+ * NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
+ * Session context is injected via CLAUDE.md / skills instead.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = 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 {};
+  }
+}
+
+/**
+ * Find the .gitnexus directory by walking up from startDir.
+ * Returns the path to .gitnexus/ or null if not found.
+ */
+function findGitNexusDir(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < 5; i++) {
+    const candidate = path.join(dir, '.gitnexus');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Spawn a gitnexus CLI command synchronously.
+ * Detects binary on PATH once, then runs exactly once.
+ *
+ * SECURITY: Never use shell: true with user-controlled arguments.
+ * On Windows, invoke gitnexus.cmd directly (no shell needed).
+ */
+function runGitNexusCli(args, cwd, timeout) {
+  const isWin = process.platform === 'win32';
+
+  // Detect whether 'gitnexus' is on PATH (cheap check, no execution)
+  let useDirectBinary = false;
+  try {
+    const which = spawnSync(
+      isWin ? 'where' : 'which', ['gitnexus'],
+      { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    useDirectBinary = which.status === 0;
+  } catch { /* not on PATH */ }
+
+  if (useDirectBinary) {
+    return spawnSync(
+      isWin ? 'gitnexus.cmd' : 'gitnexus', args,
+      { encoding: 'utf-8', timeout, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+  }
+  // npx fallback needs shell on Windows since npx is a .cmd script
+  return spawnSync(
+    isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args],
+    { encoding: 'utf-8', timeout: timeout + 5000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+}
+
+/**
+ * Emit a hook response with additional context for the agent.
+ */
+function sendHookResponse(hookEventName, message) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: { hookEventName, additionalContext: message }
+  }));
+}
+
+/**
+ * PreToolUse handler — augment searches with graph context.
+ */
+function handlePreToolUse(input) {
+  const cwd = input.cwd || process.cwd();
+  if (!path.isAbsolute(cwd)) return;
+  if (!findGitNexusDir(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;
+
+  let result = '';
+  try {
+    const child = runGitNexusCli(['augment', '--', pattern], cwd, 7000);
+    if (!child.error && child.status === 0) {
+      result = child.stderr || '';
+    }
+  } catch { /* graceful failure */ }
+
+  if (result && result.trim()) {
+    sendHookResponse('PreToolUse', result.trim());
+  }
+}
+
+/**
+ * PostToolUse handler — detect index staleness after git mutations.
+ *
+ * Instead of spawning a full `gitnexus analyze` 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
+ * agent so it can decide when to reindex.
+ */
+function handlePostToolUse(input) {
+  const toolName = input.tool_name || '';
+  if (toolName !== 'Bash') return;
+
+  const command = (input.tool_input || {}).command || '';
+  if (!/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(command)) return;
+
+  // Only proceed if the command succeeded
+  const toolOutput = input.tool_output || {};
+  if (toolOutput.exit_code !== undefined && toolOutput.exit_code !== 0) return;
+
+  const cwd = input.cwd || process.cwd();
+  if (!path.isAbsolute(cwd)) return;
+  const gitNexusDir = findGitNexusDir(cwd);
+  if (!gitNexusDir) return;
+
+  // Compare HEAD against last indexed commit — skip if unchanged
+  let currentHead = '';
+  try {
+    const headResult = spawnSync('git', ['rev-parse', 'HEAD'], {
+      encoding: 'utf-8', timeout: 3000, cwd, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    currentHead = (headResult.stdout || '').trim();
+  } catch { return; }
+
+  if (!currentHead) return;
+
+  let lastCommit = '';
+  let hadEmbeddings = false;
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(gitNexusDir, 'meta.json'), 'utf-8'));
+    lastCommit = meta.lastCommit || '';
+    hadEmbeddings = (meta.stats && meta.stats.embeddings > 0);
+  } catch { /* no meta — treat as stale */ }
+
+  // If HEAD matches last indexed commit, no reindex needed
+  if (currentHead && currentHead === lastCommit) return;
+
+  const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  sendHookResponse('PostToolUse',
+    `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
+    `Run \`${analyzeCmd}\` to update the knowledge graph.`
+  );
+}
+
+// Dispatch map for hook events
+const handlers = {
+  PreToolUse: handlePreToolUse,
+  PostToolUse: handlePostToolUse,
+};
+
+function main() {
+  try {
+    const input = readInput();
+    const handler = handlers[input.hook_event_name || ''];
+    if (handler) handler(input);
+  } catch (err) {
+    if (process.env.GITNEXUS_DEBUG) {
+      console.error('GitNexus hook error:', (err.message || '').slice(0, 200));
+    }
+  }
+}
+
+main();

gitnexus-claude-plugin/hooks/hooks.json

@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep|Glob|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/gitnexus-hook.js",
+            "timeout": 10,
+            "statusMessage": "Enriching with GitNexus graph context..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/gitnexus-hook.js",
+            "timeout": 10,
+            "statusMessage": "Checking GitNexus index freshness..."
+          }
+        ]
+      }
+    ]
+  }
+}

gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus 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.
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Force full re-index even if up to date |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus 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.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus 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.
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Skip confirmation prompt |
+| `--all` | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Force full regeneration |
+| `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>` | LLM API base URL |
+| `--api-key <key>` | LLM API key |
+| `--concurrency <n>` | Parallel LLM calls (default: 3) |
+| `--gist` | Publish wiki as a public GitHub Gist |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

gitnexus-claude-plugin/skills/gitnexus-cli/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md

@@ -0,0 +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" → run `npx gitnexus analyze` in terminal.
+
+## 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    | `detect_changes` to see what your changes affect           |
+
+## 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
+```

gitnexus-claude-plugin/skills/gitnexus-debugging/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md

@@ -0,0 +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" → run `npx gitnexus analyze` in terminal.
+
+## 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
+```

gitnexus-claude-plugin/skills/gitnexus-exploring/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+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 gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

gitnexus-claude-plugin/skills/gitnexus-guide/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-claude-plugin/skills/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```

gitnexus-claude-plugin/skills/gitnexus-impact-analysis/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-claude-plugin/skills/gitnexus-pr-review/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: gitnexus-pr-review
+description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
+---
+
+# PR Review with GitNexus
+
+## When to Use
+
+- "Review this PR"
+- "What does PR #42 change?"
+- "Is this safe to merge?"
+- "What's the blast radius of this PR?"
+- "Are there missing tests for this PR?"
+- Reviewing someone else's code changes before merge
+
+## Workflow
+
+```
+1. gh pr diff <number>                                    → Get the raw diff
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+3. For each changed symbol:
+   gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
+4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
+5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+6. Summarize findings with risk assessment
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.
+
+## Checklist
+
+```
+- [ ] Fetch PR diff (gh pr diff or git diff base...head)
+- [ ] gitnexus_detect_changes to map changes to affected execution flows
+- [ ] gitnexus_impact on each non-trivial changed symbol
+- [ ] Review d=1 items (WILL BREAK) — are callers updated?
+- [ ] gitnexus_context on key changed symbols to understand full picture
+- [ ] Check if affected processes have test coverage
+- [ ] Assess overall risk level
+- [ ] Write review summary with findings
+```
+
+## Review Dimensions
+
+| Dimension | How GitNexus Helps |
+| --- | --- |
+| **Correctness** | `context` shows callers — are they all compatible with the change? |
+| **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
+| **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
+| **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
+| **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
+
+## Risk Assessment
+
+| Signal | Risk |
+| --- | --- |
+| Changes touch <3 symbols, 0-1 processes | LOW |
+| Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
+| Changes touch >10 symbols or many processes | HIGH |
+| Changes touch auth, payments, or data integrity code | CRITICAL |
+| d=1 callers exist outside the PR diff | Potential breakage — flag it |
+
+## Tools
+
+**gitnexus_detect_changes** — map PR diff to affected execution flows:
+
+```
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+
+→ Changed: 8 symbols in 4 files
+→ Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Risk: MEDIUM
+```
+
+**gitnexus_impact** — blast radius per changed symbol:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream"})
+
+→ d=1 (WILL BREAK):
+  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
+  - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_impact with tests** — check test coverage:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
+
+→ Tests that cover this symbol:
+  - validatePayment.test.ts [direct]
+  - checkout.integration.test.ts [via processCheckout]
+```
+
+**gitnexus_context** — understand a changed symbol's role:
+
+```
+gitnexus_context({name: "validatePayment"})
+
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates
+→ Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)
+```
+
+## Example: "Review PR #42"
+
+```
+1. gh pr diff 42 > /tmp/pr42.diff
+   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
+
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   → Changed symbols: validatePayment, PaymentInput, formatAmount
+   → Affected processes: CheckoutFlow, RefundFlow
+   → Risk: MEDIUM
+
+3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
+   → d=1: processCheckout, webhookHandler (WILL BREAK)
+   → webhookHandler is NOT in the PR diff — potential breakage!
+
+4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
+   → d=1: validatePayment (in PR), createPayment (NOT in PR)
+   → createPayment uses the old PaymentInput shape — breaking change!
+
+5. gitnexus_context({name: "formatAmount"})
+   → Called by 12 functions — but change is backwards-compatible (added optional param)
+
+6. Review summary:
+   - MEDIUM risk — 3 changed symbols affect 2 execution flows
+   - BUG: webhookHandler calls validatePayment but isn't updated for new signature
+   - BUG: createPayment depends on PaymentInput type which changed
+   - OK: formatAmount change is backwards-compatible
+   - Tests: checkout.test.ts covers processCheckout path, but no webhook test
+```
+
+## Review Output Format
+
+Structure your review as:
+
+```markdown
+## PR Review: <title>
+
+**Risk: LOW / MEDIUM / HIGH / CRITICAL**
+
+### Changes Summary
+- <N> symbols changed across <M> files
+- <P> execution flows affected
+
+### Findings
+1. **[severity]** Description of finding
+   - Evidence from GitNexus tools
+   - Affected callers/flows
+
+### Missing Coverage
+- Callers not updated in PR: ...
+- Untested flows: ...
+
+### Recommendation
+APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+```

gitnexus-claude-plugin/skills/gitnexus-refactoring/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

gitnexus-claude-plugin/skills/gitnexus-refactoring/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

gitnexus-cursor-integration/hooks/augment-shell.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# GitNexus beforeShellExecution hook for Cursor
+# Receives JSON on stdin with { command, cwd, timeout }
+# Returns JSON on stdout with { permission, agent_message }
+#
+# Extracts search pattern from grep/rg commands, runs gitnexus augment,
+# and injects the enriched context via agent_message.
+
+INPUT=$(cat)
+
+COMMAND=$(echo "$INPUT" | jq -r '.command // empty' 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+
+# Skip non-search commands
+case "$COMMAND" in
+  cd\ *|npm\ *|yarn\ *|pnpm\ *|git\ commit*|git\ push*|git\ pull*|mkdir\ *|rm\ *|cp\ *|mv\ *|echo\ *|cat\ *)
+    echo '{"permission":"allow"}'
+    exit 0
+    ;;
+esac
+
+# Extract search pattern from rg/grep commands
+PATTERN=""
+if echo "$COMMAND" | grep -qE '\brg\b'; then
+  PATTERN=$(echo "$COMMAND" | sed -n "s/.*\brg\s\+\(--[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+elif echo "$COMMAND" | grep -qE '\bgrep\b'; then
+  PATTERN=$(echo "$COMMAND" | sed -n "s/.*\bgrep\s\+\(-[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+fi
+
+if [ -z "$PATTERN" ] || [ ${#PATTERN} -lt 3 ]; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+
+# Run gitnexus augment
+RESULT=$(npx -y gitnexus augment "$PATTERN" 2>/dev/null)
+
+if [ -n "$RESULT" ]; then
+  # Escape for JSON
+  ESCAPED=$(echo "$RESULT" | jq -Rs .)
+  echo "{\"permission\":\"allow\",\"agent_message\":$ESCAPED}"
+else
+  echo '{"permission":"allow"}'
+fi
+
+exit 0

gitnexus-cursor-integration/hooks/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "./hooks/augment-shell.sh",
+        "timeout": 5,
+        "matcher": "\\brg\\b|\\bgrep\\b"
+      }
+    ]
+  }
+}

gitnexus-cursor-integration/skills/gitnexus-debugging/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: gitnexus-debugging
+description: Trace bugs through call chains using knowledge graph
+---
+
+# 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" → run `npx gitnexus analyze` in terminal.
+
+## 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 | `detect_changes` to see what your changes affect |
+
+## 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
+```

gitnexus-cursor-integration/skills/gitnexus-exploring/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: gitnexus-exploring
+description: Navigate unfamiliar code using GitNexus knowledge graph
+---
+
+# 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" → run `npx gitnexus analyze` in terminal.
+
+## 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
+```

gitnexus-cursor-integration/skills/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: gitnexus-impact-analysis
+description: Analyze blast radius before making code changes
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level | Meaning |
+|-------|-----------|---------|
+| d=1 | **WILL BREAK** | Direct callers/importers |
+| d=2 | LIKELY AFFECTED | Indirect dependencies |
+| d=3 | MAY NEED TESTING | Transitive effects |
+
+## Risk Assessment
+
+| Affected | Risk |
+|----------|------|
+| <5 symbols, few processes | LOW |
+| 5-15 symbols, 2-5 processes | MEDIUM |
+| >15 symbols or many processes | HIGH |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```

gitnexus-cursor-integration/skills/gitnexus-pr-review/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: gitnexus-pr-review
+description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
+---
+
+# PR Review with GitNexus
+
+## When to Use
+
+- "Review this PR"
+- "What does PR #42 change?"
+- "Is this safe to merge?"
+- "What's the blast radius of this PR?"
+- "Are there missing tests for this PR?"
+- Reviewing someone else's code changes before merge
+
+## Workflow
+
+```
+1. gh pr diff <number>                                    → Get the raw diff
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+3. For each changed symbol:
+   gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
+4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
+5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+6. Summarize findings with risk assessment
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.
+
+## Checklist
+
+```
+- [ ] Fetch PR diff (gh pr diff or git diff base...head)
+- [ ] gitnexus_detect_changes to map changes to affected execution flows
+- [ ] gitnexus_impact on each non-trivial changed symbol
+- [ ] Review d=1 items (WILL BREAK) — are callers updated?
+- [ ] gitnexus_context on key changed symbols to understand full picture
+- [ ] Check if affected processes have test coverage
+- [ ] Assess overall risk level
+- [ ] Write review summary with findings
+```
+
+## Review Dimensions
+
+| Dimension | How GitNexus Helps |
+| --- | --- |
+| **Correctness** | `context` shows callers — are they all compatible with the change? |
+| **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
+| **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
+| **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
+| **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
+
+## Risk Assessment
+
+| Signal | Risk |
+| --- | --- |
+| Changes touch <3 symbols, 0-1 processes | LOW |
+| Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
+| Changes touch >10 symbols or many processes | HIGH |
+| Changes touch auth, payments, or data integrity code | CRITICAL |
+| d=1 callers exist outside the PR diff | Potential breakage — flag it |
+
+## Tools
+
+**gitnexus_detect_changes** — map PR diff to affected execution flows:
+
+```
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+
+→ Changed: 8 symbols in 4 files
+→ Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Risk: MEDIUM
+```
+
+**gitnexus_impact** — blast radius per changed symbol:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream"})
+
+→ d=1 (WILL BREAK):
+  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
+  - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_impact with tests** — check test coverage:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
+
+→ Tests that cover this symbol:
+  - validatePayment.test.ts [direct]
+  - checkout.integration.test.ts [via processCheckout]
+```
+
+**gitnexus_context** — understand a changed symbol's role:
+
+```
+gitnexus_context({name: "validatePayment"})
+
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates
+→ Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)
+```
+
+## Example: "Review PR #42"
+
+```
+1. gh pr diff 42 > /tmp/pr42.diff
+   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
+
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   → Changed symbols: validatePayment, PaymentInput, formatAmount
+   → Affected processes: CheckoutFlow, RefundFlow
+   → Risk: MEDIUM
+
+3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
+   → d=1: processCheckout, webhookHandler (WILL BREAK)
+   → webhookHandler is NOT in the PR diff — potential breakage!
+
+4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
+   → d=1: validatePayment (in PR), createPayment (NOT in PR)
+   → createPayment uses the old PaymentInput shape — breaking change!
+
+5. gitnexus_context({name: "formatAmount"})
+   → Called by 12 functions — but change is backwards-compatible (added optional param)
+
+6. Review summary:
+   - MEDIUM risk — 3 changed symbols affect 2 execution flows
+   - BUG: webhookHandler calls validatePayment but isn't updated for new signature
+   - BUG: createPayment depends on PaymentInput type which changed
+   - OK: formatAmount change is backwards-compatible
+   - Tests: checkout.test.ts covers processCheckout path, but no webhook test
+```
+
+## Review Output Format
+
+Structure your review as:
+
+```markdown
+## PR Review: <title>
+
+**Risk: LOW / MEDIUM / HIGH / CRITICAL**
+
+### Changes Summary
+- <N> symbols changed across <M> files
+- <P> execution flows affected
+
+### Findings
+1. **[severity]** Description of finding
+   - Evidence from GitNexus tools
+   - Affected callers/flows
+
+### Missing Coverage
+- Callers not updated in PR: ...
+- Untested flows: ...
+
+### Recommendation
+APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+```

gitnexus-cursor-integration/skills/gitnexus-refactoring/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: gitnexus-refactoring
+description: Plan safe refactors using blast radius and dependency mapping
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor | Mitigation |
+|-------------|------------|
+| Many callers (>5) | Use gitnexus_rename for automated updates |
+| Cross-area refs | Use detect_changes after to verify scope |
+| String/dynamic refs | gitnexus_query to find them |
+| External/public API | Version and deprecate properly |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

gitnexus-test-setup/.gitignore

@@ -0,0 +1,7 @@
+
+# GitNexus AI Context
+.gitnexus-rules.md
+.cursorrules
+.windsurfrules
+CLAUDE.md
+.github/copilot-instructions.md

gitnexus-web/.gitignore

@@ -0,0 +1,2 @@
+.vercel
+.env*.local

gitnexus-web/package.json

@@ -11,11 +11,12 @@
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@isomorphic-git/lightning-fs": "^4.6.2",
-    "@langchain/anthropic": "^0.3.34",
-    "@langchain/core": "^0.3.0",
-    "@langchain/google-genai": "^0.1.0",
-    "@langchain/langgraph": "^0.2.74",
-    "@langchain/openai": "^0.3.0",
+    "@langchain/anthropic": "^1.3.10",
+    "@langchain/core": "^1.1.15",
+    "@langchain/google-genai": "^2.1.10",
+    "@langchain/langgraph": "^1.1.0",
+    "@langchain/ollama": "^1.2.0",
+    "@langchain/openai": "^1.2.2",
     "@sigma/edge-curve": "^3.1.0",
     "@tailwindcss/vite": "^4.1.18",
     "axios": "^1.13.2",
@@ -23,13 +24,17 @@
     "comlink": "^4.4.2",
     "d3": "^7.9.0",
     "graphology": "^0.26.0",
+    "graphology-indices": "^0.17.0",
+    "graphology-utils": "^2.3.0",
+    "mnemonist": "^0.39.0",
+    "pandemonium": "^2.4.0",
     "graphology-layout-force": "^0.2.4",
     "graphology-layout-forceatlas2": "^0.10.1",
     "graphology-layout-noverlap": "^0.4.2",
     "isomorphic-git": "^1.36.1",
     "jszip": "^3.10.1",
     "kuzu-wasm": "^0.11.1",
-    "langchain": "^0.3.37",
+    "langchain": "^1.2.10",
     "lru-cache": "^11.2.4",
     "lucide-react": "^0.562.0",
     "mermaid": "^11.12.2",
@@ -38,6 +43,7 @@
     "react-dom": "^18.3.1",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^16.1.0",
+    "react-zoom-pan-pinch": "^3.7.0",
     "remark-gfm": "^4.0.1",
     "sigma": "^3.0.2",
     "tailwindcss": "^4.1.18",
@@ -56,6 +62,7 @@
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vercel/node": "^5.5.16",
     "@vitejs/plugin-react": "^5.1.0",
+    "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.4.5",
     "vite": "^5.2.0",
     "vite-plugin-static-copy": "^3.1.4"