fix(ci): grant actions:read to publish workflow for pr-report job

feat: Phase 9 — Return-type-aware variable binding with unified fixpoint chain propagation

.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. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+
+### 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-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-tests.yml

@@ -0,0 +1,57 @@
+name: Tests
+
+on:
+  workflow_call:
+
+jobs:
+  tests:
+    name: ubuntu / coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Run all tests with coverage
+        run: >-
+          npx vitest run
+          --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: ${{ 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: 25
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+      - run: npx vitest run
+        working-directory: gitnexus

.github/workflows/ci.yml

@@ -0,0 +1,314 @@
+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-tests.yml         — all tests with coverage (ubuntu) + cross-platform
+#
+# The PR report runs inline (not via workflow_run) so it uses the
+# PR branch's code instead of main's — avoids stale report templates.
+
+jobs:
+  quality:
+    uses: ./.github/workflows/ci-quality.yml
+    permissions:
+      contents: read
+
+  tests:
+    uses: ./.github/workflows/ci-tests.yml
+    permissions:
+      contents: read
+
+  # ── Unified CI gate ──────────────────────────────────────────────
+  # Single required check for branch protection.
+  ci-status:
+    name: CI Gate
+    needs: [quality, tests]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check all jobs passed
+        shell: bash
+        env:
+          QUALITY: ${{ needs.quality.result }}
+          TESTS: ${{ needs.tests.result }}
+        run: |
+          echo "Quality:  $QUALITY"
+          echo "Tests:    $TESTS"
+          if [[ "$QUALITY" != "success" ]] ||
+             [[ "$TESTS" != "success" ]]; then
+            echo "::error::One or more CI jobs failed"
+            exit 1
+          fi
+
+  # ── PR Report ────────────────────────────────────────────────────
+  # Posts a sticky comment with test results, coverage, and
+  # per-platform status.  Runs inline so it uses the PR branch's
+  # report template (not main's stale version via workflow_run).
+  pr-report:
+    name: PR Report
+    if: always() && github.event_name == 'pull_request'
+    needs: [quality, tests]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      pull-requests: write
+    timeout-minutes: 5
+    steps:
+      - name: Download test reports
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: test-reports
+          path: ${{ runner.temp }}/test-reports
+        continue-on-error: true
+
+      - name: Fetch cross-platform job results
+        id: jobs
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            const jobs = await github.rest.actions.listJobsForWorkflowRun({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: context.runId,
+              per_page: 50,
+            });
+
+            const results = {};
+            for (const job of jobs.data.jobs) {
+              if (job.name.includes('ubuntu')) results.ubuntu = job.conclusion || 'pending';
+              else if (job.name.includes('windows')) results.windows = job.conclusion || 'pending';
+              else if (job.name.includes('macos')) results.macos = job.conclusion || 'pending';
+            }
+            core.setOutput('ubuntu', results.ubuntu || 'unknown');
+            core.setOutput('windows', results.windows || 'unknown');
+            core.setOutput('macos', results.macos || 'unknown');
+
+      - name: Fetch base branch coverage
+        id: base-coverage
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const runs = await github.rest.actions.listWorkflowRuns({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'ci.yml',
+              branch: 'main',
+              status: 'success',
+              per_page: 1,
+            });
+
+            if (runs.data.workflow_runs.length === 0) {
+              core.setOutput('found', 'false');
+              return;
+            }
+
+            const mainRunId = runs.data.workflow_runs[0].id;
+            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: mainRunId,
+            });
+
+            const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
+            if (!testReports) {
+              core.setOutput('found', 'false');
+              return;
+            }
+
+            const zip = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: testReports.id,
+              archive_format: 'zip',
+            });
+
+            const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
+            fs.mkdirSync(dest, { recursive: true });
+            fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
+            core.setOutput('found', 'true');
+            core.setOutput('dir', dest);
+
+      - name: Extract base coverage
+        if: steps.base-coverage.outputs.found == 'true'
+        shell: bash
+        run: |
+          cd "${{ steps.base-coverage.outputs.dir }}"
+          unzip -o base.zip -d base
+
+      - name: Build and post report
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        env:
+          QUALITY: ${{ needs.quality.result }}
+          TESTS: ${{ needs.tests.result }}
+          UBUNTU: ${{ steps.jobs.outputs.ubuntu }}
+          WINDOWS: ${{ steps.jobs.outputs.windows }}
+          MACOS: ${{ steps.jobs.outputs.macos }}
+          BASE_FOUND: ${{ steps.base-coverage.outputs.found }}
+          BASE_DIR: ${{ steps.base-coverage.outputs.dir }}
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const icon = (s) => ({ success: '✅', failure: '❌', cancelled: '⏭️' }[s] || '❓');
+            const temp = process.env.RUNNER_TEMP;
+
+            // ── Read coverage ──
+            function readCov(dir) {
+              const out = { stmts: 'N/A', branch: 'N/A', funcs: 'N/A', lines: 'N/A',
+                            stmtsCov: '', branchCov: '', funcsCov: '', linesCov: '' };
+              try {
+                const files = require('child_process')
+                  .execSync(`find "${dir}" -name coverage-summary.json -type f`, { encoding: 'utf8' })
+                  .trim().split('\n').filter(Boolean);
+                if (!files.length) return out;
+                const d = JSON.parse(fs.readFileSync(files[0], 'utf8')).total;
+                out.stmts = d.statements.pct; out.branch = d.branches.pct;
+                out.funcs = d.functions.pct;  out.lines = d.lines.pct;
+                out.stmtsCov = `${d.statements.covered}/${d.statements.total}`;
+                out.branchCov = `${d.branches.covered}/${d.branches.total}`;
+                out.funcsCov = `${d.functions.covered}/${d.functions.total}`;
+                out.linesCov = `${d.lines.covered}/${d.lines.total}`;
+              } catch {}
+              return out;
+            }
+
+            const cov = readCov(path.join(temp, 'test-reports'));
+            const base = process.env.BASE_FOUND === 'true'
+              ? readCov(path.join(process.env.BASE_DIR, 'base'))
+              : { stmts: 'N/A', branch: 'N/A', funcs: 'N/A', lines: 'N/A' };
+
+            // ── Read test results ──
+            let total = 0, passed = 0, failed = 0, skipped = 0, suites = 0, duration = '0s';
+            let skippedTests = [];
+            try {
+              const files = require('child_process')
+                .execSync(`find "${path.join(temp, 'test-reports')}" -name test-results.json -type f`, { encoding: 'utf8' })
+                .trim().split('\n').filter(Boolean);
+              if (files.length) {
+                const r = JSON.parse(fs.readFileSync(files[0], 'utf8'));
+                total = r.numTotalTests || 0;
+                passed = r.numPassedTests || 0;
+                failed = r.numFailedTests || 0;
+                skipped = r.numPendingTests || 0;
+                suites = r.numTotalTestSuites || 0;
+                const durS = Math.floor((Math.max(...r.testResults.map(t => t.endTime)) - r.startTime) / 1000);
+                duration = durS >= 60 ? `${Math.floor(durS / 60)}m ${durS % 60}s` : `${durS}s`;
+                // Collect skipped test names
+                for (const suite of r.testResults) {
+                  for (const t of (suite.assertionResults || [])) {
+                    if (t.status === 'pending' || t.status === 'skipped') {
+                      skippedTests.push(`- ${t.ancestorTitles.join(' > ')} > ${t.title}`);
+                    }
+                  }
+                }
+              }
+            } catch {}
+
+            // ── Coverage delta ──
+            function delta(pct, basePct) {
+              if (pct === 'N/A' || basePct === 'N/A') return '—';
+              const d = (pct - basePct).toFixed(1);
+              if (d > 0) return `📈 +${d}%`;
+              if (d < 0) return `📉 ${d}%`;
+              return '＝';
+            }
+
+            // ── Build markdown ──
+            const { QUALITY, TESTS, UBUNTU, WINDOWS, MACOS } = process.env;
+            const overall = (QUALITY === 'success' && TESTS === 'success')
+              ? '✅ **All checks passed**' : '❌ **Some checks failed**';
+            const sha = context.sha.slice(0, 7);
+
+            let body = `## CI Report\n\n${overall} &ensp; \`${sha}\`\n\n`;
+
+            body += `### Pipeline\n\n`;
+            body += `| Stage | Status | Ubuntu | Windows | macOS |\n`;
+            body += `|-------|--------|--------|---------|-------|\n`;
+            body += `| Typecheck | ${icon(QUALITY)} \`${QUALITY}\` | — | — | — |\n`;
+            body += `| Tests | ${icon(TESTS)} \`${TESTS}\` | ${icon(UBUNTU)} | ${icon(WINDOWS)} | ${icon(MACOS)} |\n\n`;
+
+            if (total > 0) {
+              body += `### Tests\n\n`;
+              body += `| Metric | Value |\n|--------|-------|\n`;
+              body += `| Total | **${total}** |\n`;
+              body += `| Passed | **${passed}** |\n`;
+              if (failed > 0) body += `| Failed | **${failed}** |\n`;
+              if (skipped > 0) body += `| Skipped | ${skipped} |\n`;
+              body += `| Files | ${suites} |\n`;
+              body += `| Duration | ${duration} |\n\n`;
+
+              if (failed === 0) {
+                body += `✅ All **${passed}** tests passed across **${suites}** files\n`;
+              } else {
+                body += `❌ **${failed}** failed / **${passed}** passed\n`;
+              }
+
+              if (skippedTests.length > 0) {
+                body += `\n<details>\n<summary>${skipped} test(s) skipped</summary>\n\n`;
+                body += skippedTests.join('\n') + '\n\n</details>\n';
+              }
+              body += '\n';
+            }
+
+            if (cov.stmts !== 'N/A') {
+              body += `### Coverage\n\n`;
+              body += `| Metric | Coverage | Covered | Base (main) | Delta |\n`;
+              body += `|--------|----------|---------|-------------|-------|\n`;
+              body += `| Statements | **${cov.stmts}%** | ${cov.stmtsCov} | ${base.stmts}% | ${delta(cov.stmts, base.stmts)} |\n`;
+              body += `| Branches | **${cov.branch}%** | ${cov.branchCov} | ${base.branch}% | ${delta(cov.branch, base.branch)} |\n`;
+              body += `| Functions | **${cov.funcs}%** | ${cov.funcsCov} | ${base.funcs}% | ${delta(cov.funcs, base.funcs)} |\n`;
+              body += `| Lines | **${cov.lines}%** | ${cov.linesCov} | ${base.lines}% | ${delta(cov.lines, base.lines)} |\n\n`;
+            } else {
+              body += `### Coverage\n\n⚠️ Coverage data unavailable — check the [test job](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) for details.\n\n`;
+            }
+
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            body += `---\n<sub>📋 [Full run](${runUrl}) · Coverage from Ubuntu · Generated by CI</sub>`;
+
+            // ── Post sticky comment ──
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+
+            const marker = '<!-- ci-report -->';
+            const existing = comments.find(c => c.body?.includes(marker));
+            const fullBody = marker + '\n' + body;
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: fullBody,
+              });
+            }

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

@@ -0,0 +1,123 @@
+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]
+
+# Serialize per-PR so concurrent @claude comments don't race on the
+# temporary fork branch push/delete.
+concurrency:
+  group: claude-review-${{ github.event.issue.number || github.event.pull_request.number }}
+  cancel-in-progress: false
+
+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 create fork branch ref via API
+      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. Create a temporary branch ref via the API so the action
+      # can find it. Using the API (not git push) avoids the GITHUB_TOKEN
+      # restriction that blocks pushing commits containing workflow file changes.
+      # Use a prefixed temporary branch name to avoid overwriting real branches
+      # (e.g. a fork branch named "main" would overwrite origin/main).
+      - name: Create fork branch ref on origin
+        id: push-fork
+        if: steps.pr.outputs.is_fork == 'true'
+        env:
+          FORK_BRANCH: claude-tmp/fork-pr-${{ steps.pr.outputs.number }}
+          FORK_SHA: ${{ steps.pr.outputs.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "FORK_BRANCH=$FORK_BRANCH" >> "$GITHUB_ENV"
+          gh api "repos/${{ github.repository }}/git/refs" \
+            --method POST \
+            -f ref="refs/heads/$FORK_BRANCH" \
+            -f sha="$FORK_SHA" \
+          || gh api "repos/${{ github.repository }}/git/refs/heads/$FORK_BRANCH" \
+            --method PATCH \
+            -f sha="$FORK_SHA" \
+            -F force=true
+
+      - 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 ref we created for fork PRs.
+      # Only delete if the create step actually succeeded.
+      - name: Delete fork branch ref from origin
+        if: always() && steps.push-fork.outcome == 'success'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh api "repos/${{ github.repository }}/git/refs/heads/$FORK_BRANCH" --method DELETE || true

.github/workflows/claude.yml

@@ -0,0 +1,118 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+# Serialize per-PR so concurrent @claude comments don't race on the
+# temporary fork branch push/delete.
+concurrency:
+  group: claude-code-${{ github.event.issue.number || github.event.pull_request.number || github.event.issue.id }}
+  cancel-in-progress: false
+
+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: write       # needed to create fork branch ref via API
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read         # required for Claude to read CI results on PRs
+    steps:
+      # For PR-related triggers, resolve fork context so we can create a
+      # temporary branch ref (claude-code-action fetches by branch name).
+      - name: Resolve PR context
+        id: pr
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            // Determine if this event is PR-related
+            let prNumber = null;
+            if (context.eventName === 'issue_comment' && context.payload.issue.pull_request) {
+              prNumber = context.payload.issue.number;
+            } else if (context.eventName === 'pull_request_review_comment') {
+              prNumber = context.payload.pull_request.number;
+            } else if (context.eventName === 'pull_request_review') {
+              prNumber = context.payload.pull_request.number;
+            }
+
+            if (!prNumber) {
+              core.setOutput('is_pr', 'false');
+              core.setOutput('is_fork', 'false');
+              return;
+            }
+
+            const resp = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+            });
+            const pr = resp.data;
+            const isFork = pr.head.repo.full_name !== pr.base.repo.full_name;
+
+            core.setOutput('is_pr', 'true');
+            core.setOutput('number', String(prNumber));
+            core.setOutput('is_fork', String(isFork));
+            core.setOutput('branch', pr.head.ref);
+            core.setOutput('sha', pr.head.sha);
+
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          ref: ${{ steps.pr.outputs.is_fork == 'true' && steps.pr.outputs.sha || '' }}
+          fetch-depth: 1
+
+      # claude-code-action fetches branches by name from origin, which fails
+      # for fork PRs. Create a temporary branch ref via the API so the action
+      # can find it. Using the API (not git push) avoids the GITHUB_TOKEN
+      # restriction that blocks pushing commits containing workflow file changes.
+      # Use a prefixed temporary branch name to avoid overwriting real branches
+      # (e.g. a fork branch named "main" would overwrite origin/main).
+      - name: Create fork branch ref on origin
+        id: push-fork
+        if: steps.pr.outputs.is_fork == 'true'
+        env:
+          FORK_BRANCH: claude-tmp/fork-pr-${{ steps.pr.outputs.number }}
+          FORK_SHA: ${{ steps.pr.outputs.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "FORK_BRANCH=$FORK_BRANCH" >> "$GITHUB_ENV"
+          gh api "repos/${{ github.repository }}/git/refs" \
+            --method POST \
+            -f ref="refs/heads/$FORK_BRANCH" \
+            -f sha="$FORK_SHA" \
+          || gh api "repos/${{ github.repository }}/git/refs/heads/$FORK_BRANCH" \
+            --method PATCH \
+            -f sha="$FORK_SHA" \
+            -F force=true
+
+      - 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
+
+      # Clean up the temporary branch ref we created for fork PRs.
+      # Only delete if the create step actually succeeded.
+      - name: Delete fork branch ref from origin
+        if: always() && steps.push-fork.outcome == 'success'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh api "repos/${{ github.repository }}/git/refs/heads/$FORK_BRANCH" --method DELETE || true

.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+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
+      actions: 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

@@ -1,46 +1,72 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# TypeScript build info
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+.claude/settings.local.json
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
 # Logs
-logs
 *.log
 npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
 
-node_modules
-dist
-dist-ssr
+# Testing
+coverage/
+
+# Misc
 *.local
 
-# Auto-generated files
-public/workers/compiled-queries.js
+.vercel
 
-# Editor directories and files
-.vscode/*
-!.vscode/extensions.json
-.idea
-.DS_Store
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
 
-# AI/Development tool directories
-.kilocode/
-.gemini/
-.cursor/
-.clinerules/
-.qoder/
 
-# Large JSON files
-gitnexus-project_*.json
-*-project_*.json
-.clinerules/byterover-rules.md
-.kilocode/rules/byterover-rules.md
-.roo/rules/byterover-rules.md
-.windsurf/rules/byterover-rules.md
-.cursor/rules/byterover-rules.mdc
-.kiro/steering/byterover-rules.md
-.qoder/rules/byterover-rules.md
-.augment/rules/byterover-rules.md
+
+
+
+.env*.local
+.gitnexus
+.claude/settings.local.json
+
+# Claude Code worktrees
+.claude/worktrees/
+
+# Claude code skills
+.claude/skills/generated/
+
+# 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
+
+# Ignore csharp generated obj and bin folders
+gitnexus/test/fixtures/lang-resolution/**/obj
+gitnexus/test/fixtures/lang-resolution/**/bin
+GitNexus.sln
+# Git worktrees
+.worktrees/

.history/gitnexus/vitest.config_20260317171253.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globalSetup: ['test/global-setup.ts'],
+    include: ['test/**/*.test.ts'],
+    testTimeout: 30000,
+    hookTimeout: 120000,
+    pool: 'forks',
+    globals: true,
+    setupFiles: ['test/setup.ts'],
+    teardownTimeout: 3000,
+    dangerouslyIgnoreUnhandledErrors: true, // LadybugDB N-API destructor segfaults on fork exit — not a test failure
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: [
+        'src/cli/index.ts',          // CLI entry point (commander wiring)
+        'src/server/**',              // HTTP server (requires network)
+        'src/core/wiki/**',           // Wiki generation (requires LLM)
+      ],
+      // Auto-ratchet: vitest bumps thresholds when coverage exceeds them.
+      // CI will fail if a PR drops below these floors.
+      thresholds: {
+        statements: 26,
+        branches: 23,
+        functions: 28,
+        lines: 27,
+        autoUpdate: true,
+      },
+    },
+  },
+});

.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,101 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (2094 symbols, 4982 relationships, 159 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
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to GitNexus will be documented in this file.
+
+## [Unreleased]
+
+### Changed
+- Migrated from KuzuDB to LadybugDB v0.15 (`@ladybugdb/core`, `@ladybugdb/wasm-core`)
+- Renamed all internal paths from `kuzu` to `lbug` (storage: `.gitnexus/kuzu` → `.gitnexus/lbug`)
+- Added automatic cleanup of stale KuzuDB index files
+- LadybugDB v0.15 requires explicit VECTOR extension loading for semantic search
+
+## [1.4.0] - 2026-03-13
+
+### Added
+
+- **Language-aware symbol resolution engine** with 3-tier resolver: exact FQN → scope-walk → guarded fuzzy fallback that refuses ambiguous matches (#238) — @magyargergo
+- **Method Resolution Order (MRO)** with 5 language-specific strategies: C++ leftmost-base, C#/Java class-over-interface, Python C3 linearization, Rust qualified syntax, default BFS (#238) — @magyargergo
+- **Constructor & struct literal resolution** across all languages — `new Foo()`, `User{...}`, C# primary constructors, target-typed new (#238) — @magyargergo
+- **Receiver-constrained resolution** using per-file TypeEnv — disambiguates `user.save()` vs `repo.save()` via `ownerId` matching (#238) — @magyargergo
+- **Heritage & ownership edges** — HAS_METHOD, OVERRIDES, Go struct embedding, Swift extension heritage, method signatures (`parameterCount`, `returnType`) (#238) — @magyargergo
+- **Language-specific resolver directory** (`resolvers/`) — extracted JVM, Go, C#, PHP, Rust resolvers from monolithic import-processor (#238) — @magyargergo
+- **Type extractor directory** (`type-extractors/`) — per-language type binding extraction with `Record<SupportedLanguages, Handler>` + `satisfies` dispatch (#238) — @magyargergo
+- **Export detection dispatch table** — compile-time exhaustive `Record` + `satisfies` pattern replacing switch/if chains (#238) — @magyargergo
+- **Language config module** (`language-config.ts`) — centralized tsconfig, go.mod, composer.json, .csproj, Swift package config loaders (#238) — @magyargergo
+- **Optional skill generation** via `npx gitnexus analyze --skills` — generates AI agent skills from KuzuDB knowledge graph (#171) — @zander-raycraft
+- **First-class C# support** — sibling-based modifier scanning, record/delegate/property/field/event declaration types (#163, #170, #178 via #237) — @Alice523, @benny-yamagata, @jnMetaCode
+- **C/C++ support fixes** — `.h` → C++ mapping, static-linkage export detection, qualified/parenthesized declarators, 48 entry point patterns (#163, #227 via #237) — @Alice523, @bitgineer
+- **Rust support fixes** — sibling-based `visibility_modifier` scanning for `pub` detection (#227 via #237) — @bitgineer
+- **Adaptive tree-sitter buffer sizing** — `Math.min(Math.max(contentLength * 2, 512KB), 32MB)` (#216 via #237) — @JasonOA888
+- **Call expression matching** in tree-sitter queries (#234 via #237) — @ex-nihilo-jg
+- **DeepSeek model configurations** (#217) — @JasonOA888
+- 282+ new unit tests, 178 integration resolver tests across 9 languages, 53 test files, 1146 total tests passing
+
+### Fixed
+
+- Skip unavailable native Swift parsers in sequential ingestion (#188) — @Gujiassh
+- Heritage heuristic language-gated — no longer applies class/interface rules to wrong languages (#238) — @magyargergo
+- C# `base_list` distinguishes EXTENDS vs IMPLEMENTS via symbol table + `I[A-Z]` heuristic (#238) — @magyargergo
+- Go `qualified_type` (`models.User`) correctly unwrapped in TypeEnv (#238) — @magyargergo
+- Global tier no longer blocks resolution when kind/arity filtering can narrow to 1 candidate (#238) — @magyargergo
+
+### Changed
+
+- `import-processor.ts` reduced from 1412 → 711 lines (50% reduction) via resolver and config extraction (#238) — @magyargergo
+- `type-env.ts` reduced from 635 → ~125 lines via type-extractor extraction (#238) — @magyargergo
+- CI/CD workflows hardened with security fixes and fork PR support (#222, #225) — @magyargergo
+
+## [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,101 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (2094 symbols, 4982 relationships, 159 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
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

COMPREHENSIVE_END_TO_END_VERIFICATION.md

@@ -1,207 +0,0 @@
-# 🔍 Comprehensive End-to-End Verification Report
-
-## Executive Summary
-✅ **ALL SYSTEMS VERIFIED** - The parallel processing implementation is now fully optimized with proper LRU caching, memory management, and cleanup mechanisms.
-
-## 🚨 Critical Issue Found & Fixed
-
-### **THE PROBLEM: LRU Cache Bypass in Parallel Mode**
-The parallel processing was **completely bypassing the LRU cache** for the main parsing logic, causing:
-- ❌ Every file parsed from scratch (no cache benefits)
-- ❌ Memory bloat and performance degradation
-- ❌ Sluggish behavior due to redundant processing
-
-### **THE FIX: Cache-First Processing**
-✅ Implemented **LRU cache-first processing** in `ParallelParsingProcessor.processFilesInParallel()`:
-```typescript
-// NEW: Check LRU cache before sending to workers
-for (const filePath of filePaths) {
-  const cacheKey = this.lruCache.generateFileCacheKey(filePath, contentHash);
-  const cachedResult = this.lruCache.getParsedFile(cacheKey);
-  if (cachedResult) {
-    // Use cached result ✅
-    cachedResults.push({...});
-  } else {
-    // Send to workers ✅
-    uncachedFiles.push(filePath);
-  }
-}
-```
-
----
-
-## 📋 Detailed Verification Results
-
-### 1. ✅ LRU Cache Integration
-**Status: VERIFIED & OPTIMIZED**
-
-#### Single-threaded Mode (`ParsingProcessor`):
-- ✅ File caching: `lruCache.getParsedFile()` / `setParsedFile()`
-- ✅ Query caching: `lruCache.getQueryResult()` / `setQueryResult()`
-- ✅ Parser caching: `lruCache.getParser()` / `setParser()`
-- ✅ Cache key generation: `generateFileCacheKey()` / `generateQueryCacheKey()`
-
-#### Parallel Mode (`ParallelParsingProcessor`):
-- ✅ **FIXED**: Now checks cache before worker processing
-- ✅ File caching: Same as single-threaded
-- ✅ Worker result caching: Results cached after processing
-- ✅ Cache statistics: `lruCache.getStats()` / `getCacheHitRate()`
-
-#### Expected Console Output:
-```
-ParallelParsingProcessor: Cache hits: X, Files to process: Y
-ParallelParsingProcessor: Cache hit for /path/to/file.ts
-ParallelParsingProcessor: Total results: Z (X cached, Y processed)
-```
-
-### 2. ✅ Memory Management & Cleanup
-**Status: VERIFIED & ROBUST**
-
-#### Memory Monitoring:
-- ✅ **30-second interval monitoring** in parallel mode
-- ✅ **Memory threshold triggers** (500MB → cleanup, 800MB → aggressive cleanup)
-- ✅ **AST map size limits** (1000 entries max with cleanup)
-- ✅ **LRU cache statistics** logging
-
-#### Cleanup Mechanisms:
-- ✅ **Memory Manager**: `memoryManager.clearCache()`
-- ✅ **LRU Cache**: `lruCache.clearAll()` / `clearFileCache()` / `clearQueryCache()`
-- ✅ **AST Map**: `cleanupASTMap()` with LRU-based eviction
-- ✅ **Duplicate Detector**: `duplicateDetector.clear()`
-
-#### Expected Console Output:
-```
-ParallelParsingProcessor Memory Stats:
-  - Memory Manager: XXXmb used, YYY files cached
-  - LRU File Cache: A/200 entries, B.XMB
-  - LRU Query Cache: C/100 entries, D.XMB
-  - Cache Hit Rates: File XX.X%, Query YY.Y%
-  - AST Map Size: ZZZ entries
-```
-
-### 3. ✅ Worker Pool Lifecycle & Cleanup
-**Status: VERIFIED & SECURE**
-
-#### Worker Pool Management:
-- ✅ **Proper initialization** with CPU-optimized settings
-- ✅ **Event listener cleanup** on task completion/error
-- ✅ **Worker termination** with Promise.all for parallel shutdown
-- ✅ **Singleton cleanup** via `FileProcessingPool.shutdownInstance()`
-
-#### Global Cleanup Handlers:
-- ✅ **Page unload**: `beforeunload` event → `cleanupAllPools()`
-- ✅ **Page hidden**: `visibilitychange` event → cleanup when hidden
-- ✅ **Memory pressure**: Automatic cleanup at 80% memory usage
-- ✅ **Manual cleanup**: `WebWorkerPoolUtils.cleanupAllPools()`
-
-#### Shutdown Sequence:
-```typescript
-// ParallelParsingProcessor.shutdown()
-1. Clear memory monitor interval
-2. Clear AST map & processed files
-3. Shutdown worker pool (terminate all workers)
-4. Clear LRU caches
-5. Clear language parsers
-```
-
-### 4. ✅ Cache Consistency Between Modes
-**Status: VERIFIED & IDENTICAL**
-
-#### Consistent Cache Key Generation:
-- ✅ **Same hash algorithm**: Both use identical `generateContentHash()`
-- ✅ **Same cache keys**: `lruCache.generateFileCacheKey(filePath, contentHash)`
-- ✅ **Same cache structure**: Identical cache data format
-- ✅ **Same LRU service**: Both use `LRUCacheService.getInstance()`
-
-#### Cache Data Format (Both Modes):
-```typescript
-{
-  ast: Parser.Tree,
-  definitions: ParsedDefinition[],
-  language: string,
-  lastModified: number,
-  fileSize: number
-}
-```
-
-### 5. ✅ Performance Monitoring & Logging
-**Status: VERIFIED & COMPREHENSIVE**
-
-#### Parallel Mode Logging:
-- ✅ **Cache hit rates**: Shows cached vs processed files
-- ✅ **Worker pool stats**: Active workers, completed tasks, errors
-- ✅ **Memory statistics**: Real-time memory usage monitoring
-- ✅ **Processing times**: Per-file and total processing duration
-- ✅ **Progress tracking**: Real-time progress updates
-
-#### Single-threaded Mode Logging:
-- ✅ **Memory statistics**: Memory manager stats
-- ✅ **Cache statistics**: LRU cache hit rates
-- ✅ **Processing stats**: File counts and definitions extracted
-
----
-
-## 🎯 Performance Improvements Expected
-
-### First Run (Cold Cache):
-- **Single-threaded**: Baseline performance
-- **Parallel**: Faster due to worker parallelization + caching setup
-
-### Subsequent Runs (Warm Cache):
-- **Both modes**: **Dramatically faster** due to cache hits
-- **Cache hit ratio**: Should be 80-95% for unchanged files
-- **Memory usage**: Stable and controlled via cleanup mechanisms
-
-### Memory Behavior:
-- **Before fix**: Unlimited growth → sluggishness
-- **After fix**: Controlled growth with automatic cleanup
-
----
-
-## 🔧 Verification Commands
-
-To verify the fixes are working, look for these console outputs:
-
-### Cache Verification:
-```bash
-# Should see cache hits on subsequent runs
-ParallelParsingProcessor: Cache hits: 150, Files to process: 50
-```
-
-### Memory Monitoring:
-```bash
-# Should see regular memory stats
-ParallelParsingProcessor Memory Stats:
-  - Memory Manager: 245MB used, 1250 files cached
-  - Cache Hit Rates: File 87.5%, Query 92.3%
-```
-
-### Worker Pool Stats:
-```bash
-# Should see worker efficiency
-ParallelParsingProcessor: Worker pool stats: {
-  activeWorkers: 4,
-  completedTasks: 200,
-  failedTasks: 0
-}
-```
-
----
-
-## ✅ Conclusion
-
-**ALL CRITICAL ISSUES RESOLVED:**
-
-1. **🚨 LRU Cache Bypass** → ✅ **Cache-first processing implemented**
-2. **🚨 Memory Leaks** → ✅ **Comprehensive cleanup mechanisms**
-3. **🚨 Worker Pool Leaks** → ✅ **Proper lifecycle management**
-4. **🚨 Inconsistent Caching** → ✅ **Identical cache behavior**
-5. **🚨 Poor Monitoring** → ✅ **Comprehensive performance logging**
-
-**The sluggishness should be significantly reduced** because:
-- ✅ **First run**: Files get cached after processing
-- ✅ **Subsequent runs**: Most files served from cache (near-instant)
-- ✅ **Memory management**: Automatic cleanup prevents bloat
-- ✅ **Worker efficiency**: Only uncached files sent to workers
-
-**🚀 Ready for production use with optimal performance!**

CONFIG.md

@@ -1,75 +0,0 @@
-# GitNexus Configuration
-
-## Feature Flags
-
-GitNexus uses feature flags to control the visibility of experimental and advanced features. By default, the UI is kept clean and simple for end users.
-
-### Available Feature Flags
-
-- `showEngineSelector` - Show engine selection dropdown
-- `showEnginePerformanceInfo` - Display performance comparison data
-- `showEngineCapabilities` - Show engine capabilities grid
-- `enableNextGenEngine` - Enable next-generation processing engine
-- `enableEngineComparison` - Run performance comparisons between engines
-- `enableDebugMode` - Show debugging information
-- `showProcessingDetails` - Display detailed processing information
-
-### Enabling Features for Development
-
-To enable advanced features during development, modify `/src/config/feature-flags.ts`:
-
-```typescript
-export const getFeatureFlags = (): FeatureFlags => {
-  if (import.meta.env.DEV) {
-    return {
-      ...defaultFeatureFlags,
-      // Enable engine features for development
-      showEngineSelector: true,
-      showEnginePerformanceInfo: true,
-      showEngineCapabilities: true,
-      enableDebugMode: true,
-      showProcessingDetails: true,
-    };
-  }
-  
-  return defaultFeatureFlags;
-};
-```
-
-### Production Configuration
-
-For production builds, keep feature flags disabled to maintain a clean user interface:
-
-```typescript
-export const defaultFeatureFlags: FeatureFlags = {
-  showEngineSelector: false,        // Hidden from end users
-  showEnginePerformanceInfo: false, // Hidden from end users
-  showEngineCapabilities: false,    // Hidden from end users
-  enableNextGenEngine: true,        // Enabled behind the scenes
-  enableEngineComparison: false,    // Disabled to save resources
-  enableDebugMode: false,
-  showProcessingDetails: false,
-};
-```
-
-### Environment Variables
-
-You can also control features via environment variables:
-
-```bash
-# Enable engine selector in development
-VITE_SHOW_ENGINE_SELECTOR=true npm run dev
-
-# Enable all debug features
-VITE_DEBUG_MODE=true npm run dev
-```
-
-## Layout Configuration
-
-The new layout prioritizes the graph visualization:
-
-- **Left Sidebar (400px)**: Processing status, chat interface, and actions
-- **Right Side (flex)**: Full graph visualization
-- **Mobile**: Responsive single-column layout
-
-This provides maximum space for the graph while keeping the chat interface easily accessible.

FINAL_VERIFICATION_REPORT.md

@@ -1,148 +0,0 @@
-# 🔍 FINAL COMPREHENSIVE VERIFICATION REPORT
-
-## ✅ **VERIFICATION COMPLETE - ALL CRITICAL ISSUES RESOLVED**
-
-After an extremely thorough examination, both single-threaded and parallel processing modes are now **fully synchronized** and **memory-optimized**.
-
----
-
-## 🚨 **CRITICAL ISSUES FOUND AND FIXED**
-
-### **Issue #1: Wrong Pipeline Selection in Worker** 🔥 **CRITICAL**
-**Problem**: Worker was always using `GraphPipeline` instead of checking the feature flag.
-**Impact**: "Parallel processing" was actually running single-threaded code.
-**Fix**: ✅ Worker now correctly selects `ParallelGraphPipeline` when parallel mode is enabled.
-
-### **Issue #2: LRU Cache Completely Disabled in Single-Threaded Mode** 🔥 **CRITICAL**
-**Problem**: Single-threaded processor had all LRU caching commented out as "TEMPORARILY DISABLED FOR DEBUGGING".
-**Impact**: Single-threaded mode had no caching, parallel mode did - major performance inconsistency.
-**Fix**: ✅ Re-enabled all LRU cache operations in single-threaded processor.
-
-### **Issue #3: Incorrect Duplicate Detection** 🔥 **CRITICAL**
-**Problem**: 
-- Single-threaded: `checkAndMark()` (correct)
-- Parallel: `isDuplicate()` (wrong - doesn't mark as processed)
-**Fix**: ✅ Changed parallel processor to use `checkAndMark()`.
-
-### **Issue #4: Property Format Inconsistency** 🔶 **MEDIUM**
-**Problem**: Parallel processor stored arrays as comma-separated strings.
-**Fix**: ✅ Made both processors store identical array formats.
-
-### **Issue #5: Memory Leak Prevention** 🔶 **MEDIUM**
-**Problem**: Worker pools, event listeners, and AST maps could accumulate without cleanup.
-**Fix**: ✅ Comprehensive memory management implemented.
-
----
-
-## 📊 **FINAL VERIFICATION CHECKLIST**
-
-### **✅ Pipeline Architecture**
-- [x] Worker correctly selects `GraphPipeline` vs `ParallelGraphPipeline` based on feature flag
-- [x] Both pipelines use identical 4-pass structure (Structure → Parsing → Import → Call)
-- [x] Both pipelines use same processors (except parsing processor)
-- [x] Progress callbacks properly integrated
-
-### **✅ LRU Cache Consistency**
-- [x] Both modes use `LRUCacheService.getInstance()`
-- [x] File caching enabled in both modes (200 max, 1 hour TTL)
-- [x] Query caching enabled in both modes (1000 max, 15 min TTL)
-- [x] Parser caching enabled in both modes (10 max, 24 hours TTL)
-- [x] Cache hit rate tracking in both modes
-
-### **✅ Data Processing Consistency**
-- [x] Identical duplicate detection logic (`checkAndMark()`)
-- [x] Identical node ID generation
-- [x] Identical node label mapping
-- [x] Identical property formats (arrays as arrays, not strings)
-- [x] Identical relationship creation
-
-### **✅ Memory Management**
-- [x] Worker pools properly terminated with event listener cleanup
-- [x] AST maps size-limited (1000 entries) with automatic cleanup
-- [x] LRU caches automatically manage memory (100MB total limit)
-- [x] Singleton instances properly cleaned up
-- [x] Memory monitoring with automatic triggers (500MB threshold)
-- [x] Global cleanup handlers for page unload/visibility changes
-
-### **✅ Error Handling**
-- [x] Graceful worker termination on errors
-- [x] Proper resource cleanup in finally blocks
-- [x] Error recovery without resource leaks
-
----
-
-## 🎯 **EXPECTED BEHAVIOR AFTER FIXES**
-
-### **Single-Threaded Mode (`isParallelParsingEnabled() = false`)**:
-- Uses `GraphPipeline` with `ParsingProcessor`
-- Sequential file processing on main thread
-- Full LRU caching enabled
-- Direct Tree-sitter AST parsing
-
-### **Parallel Mode (`isParallelParsingEnabled() = true`)**:
-- Uses `ParallelGraphPipeline` with `ParallelParsingProcessor`  
-- Worker pool parallel processing (2-8 workers based on CPU cores)
-- Full LRU caching enabled
-- Worker-based parsing + main thread AST recreation
-
-### **Identical Output Guaranteed**:
-Both modes will now produce:
-- ✅ **Same node counts** by type (Function, Class, Variable, etc.)
-- ✅ **Same relationship counts** by type (CONTAINS, DEFINES, IMPORTS, CALLS)
-- ✅ **Same import relationships** - no more "missing import relationships"
-- ✅ **Same function call relationships** - no more "missing call relationships"
-- ✅ **Same graph connectivity** - proper relationships between files and definitions
-
----
-
-## 🚀 **PERFORMANCE IMPROVEMENTS**
-
-### **Memory Usage**:
-- **LRU Cache**: Automatic memory management with 100MB limit
-- **AST Maps**: Size-limited to 1000 entries with cleanup
-- **Worker Pools**: Proper termination prevents accumulation
-- **Global Monitoring**: Memory usage tracked every 30 seconds
-
-### **Processing Speed**:
-- **Single-threaded**: Now benefits from LRU caching (was disabled)
-- **Parallel**: 2-8x speedup on large codebases + LRU caching benefits
-- **Cache Hit Rates**: Both modes show file/query cache performance
-
-### **Resource Management**:
-- **No Memory Leaks**: All resources properly cleaned up
-- **Automatic Cleanup**: Triggers at 80% memory usage
-- **Graceful Shutdown**: Proper cleanup on page close/tab switch
-
----
-
-## 🧪 **TESTING VERIFICATION**
-
-To verify the fixes work:
-
-1. **Process the same codebase** with both modes
-2. **Compare console output** - should show identical relationship counts
-3. **Check for these success indicators**:
-   ```
-   ✅ Relationships by type: {CONTAINS: X, DEFINES: Y, IMPORTS: Z, CALLS: W}
-   ✅ No warnings about "missing import relationships"
-   ✅ No warnings about "missing function call relationships"
-   ✅ Memory usage stays stable during processing
-   ✅ LRU cache hit rates displayed in both modes
-   ```
-
-4. **Performance comparison**:
-   - Single-threaded: Should be faster than before (LRU cache now enabled)
-   - Parallel: Should be significantly faster on large codebases
-
----
-
-## 🎉 **CONCLUSION**
-
-The parallel processing implementation now produces **100% identical output** to single-threaded processing while maintaining all performance benefits:
-
-- **✅ Data Consistency**: Identical graph structure and relationships
-- **✅ Memory Efficiency**: Comprehensive leak prevention and monitoring  
-- **✅ Performance**: LRU caching enabled in both modes + parallel speedup
-- **✅ Reliability**: Proper error handling and resource cleanup
-
-**The system is now production-ready with both processing modes fully synchronized!** 🚀

KUZU_COPY_ENABLE_GUIDE.md

@@ -1,153 +0,0 @@
-# How to Enable KuzuDB COPY Feature
-
-## Quick Start
-
-To enable the new COPY-based bulk loading feature in GitNexus:
-
-### 1. Enable Feature Flag
-
-Edit your `gitnexus.config.ts` file and set:
-
-```typescript
-export default {
-  // ... other config
-  features: {
-    // ... other features
-    enableKuzuCopy: true,  // Enable COPY-based bulk loading
-    // ... other features
-  }
-}
-```
-
-### 2. Verify Configuration
-
-The feature flag can also be enabled via environment variables or runtime configuration. Check your current config with:
-
-```javascript
-// In browser console
-import { isKuzuCopyEnabled } from './src/config/features.ts';
-console.log('COPY enabled:', isKuzuCopyEnabled());
-```
-
-### 3. Monitor Performance
-
-Once enabled, you'll see different log messages in the browser console:
-
-**COPY Success:**
-```
-🚀 COPY: Starting COPY-based commit of 150 Function nodes
-📝 Written 12543 bytes to /temp_Function_nodes_1703123456789.csv
-✅ COPY: Successfully loaded 150 Function nodes via COPY
-```
-
-**COPY Fallback:**
-```
-⚠️ COPY failed for Function, falling back to MERGE: FS API not available
-🔄 BATCH: Committing 150 Function nodes in single query
-✅ BATCH: Successfully committed all nodes in batches
-```
-
-## Performance Expectations
-
-### Small Repositories (< 100 files)
-- **Improvement**: 2-3x faster
-- **COPY vs MERGE**: Minimal difference due to overhead
-
-### Medium Repositories (100-500 files)  
-- **Improvement**: 5-7x faster
-- **COPY vs MERGE**: Significant improvement in batch operations
-
-### Large Repositories (1000+ files)
-- **Improvement**: 10-15x faster
-- **COPY vs MERGE**: Dramatic improvement, especially for complex codebases
-
-## Troubleshooting
-
-### COPY Not Working
-
-1. **Check Feature Flag**: Ensure `enableKuzuCopy: true` in config
-2. **Browser Compatibility**: COPY requires Web Workers support
-3. **KuzuDB Version**: Ensure kuzu-wasm@0.11.1 or later
-4. **FS API**: Check browser console for FS API availability
-
-### Fallback to MERGE
-
-The system automatically falls back to MERGE if:
-- FS API is not available
-- COPY statement execution fails
-- CSV generation encounters errors
-- KuzuDB schema issues
-
-This ensures **zero downtime** and **no data loss**.
-
-### Common Error Messages
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `FS API not available` | Browser/environment limitation | Normal fallback, no action needed |
-| `COPY failed: Table X does not exist` | Schema not initialized | Check KuzuDB schema initialization |
-| `CSV generation failed` | Data format issue | Check node/relationship properties |
-
-## Monitoring & Metrics
-
-### Success Indicators
-- ✅ COPY success messages in console
-- 📊 Faster ingestion times
-- 💾 Lower memory usage during batch operations
-
-### Performance Comparison
-```javascript
-// Before (MERGE): ~30 seconds for 1000 nodes
-🔄 BATCH: Committing 1000 Function nodes in single query
-✅ BATCH: Successfully committed all nodes in batches (29.8s)
-
-// After (COPY): ~3 seconds for 1000 nodes  
-🚀 COPY: Starting COPY-based commit of 1000 Function nodes
-✅ COPY: Successfully loaded 1000 Function nodes via COPY (2.9s)
-```
-
-## Rollback Plan
-
-To disable COPY and revert to MERGE:
-
-```typescript
-export default {
-  features: {
-    enableKuzuCopy: false,  // Disable COPY feature
-  }
-}
-```
-
-Changes take effect immediately on next repository ingestion.
-
-## Advanced Configuration
-
-### Batch Size Optimization
-
-The system automatically calculates optimal batch sizes, but you can tune performance:
-
-```typescript
-// In KuzuKnowledgeGraph initialization
-const kuzuGraph = new KuzuKnowledgeGraph(queryEngine, {
-  batchSize: 200,        // Increase for better COPY performance
-  autoCommit: true,      // Keep enabled for COPY
-  enableCache: true      // Recommended for performance
-});
-```
-
-### Memory Management
-
-For very large repositories, the system uses chunked processing:
-- **< 1000 items**: Single CSV generation
-- **1000-5000 items**: 1000-item chunks  
-- **> 5000 items**: 1500-item chunks
-
-## Next Steps
-
-1. **Enable Feature**: Set `enableKuzuCopy: true`
-2. **Test Small Repository**: Verify functionality with a small codebase
-3. **Monitor Performance**: Check console logs for COPY success
-4. **Scale Up**: Test with larger repositories
-5. **Report Issues**: Document any fallback scenarios or performance issues
-
-The COPY feature is designed to be **safe**, **fast**, and **transparent** - it should work seamlessly with your existing GitNexus workflow while providing significant performance improvements.

KUZU_COPY_IMPLEMENTATION_GUIDE.md

@@ -1,392 +0,0 @@
-# KuzuDB COPY Implementation Guide for GitNexus
-
-## Executive Summary
-
-**Status**: ✅ **PROVEN WORKING** - COPY approach successfully tested and verified
-**Performance**: 5-10x faster than current MERGE batch operations
-**Recommendation**: Implement with fallback to current MERGE approach
-
-## Test Results Summary
-
-| Component         | Status     | Details                                         |
-| ----------------- | ---------- | ----------------------------------------------- |
-| KuzuDB WASM Init  | ✅ Working | Initializes successfully in browser environment |
-| FS.writeFile      | ✅ Working | Successfully writes CSV to WASM filesystem      |
-| FS.readFile       | ✅ Working | Reads back data (fixed data type handling)      |
-| COPY Statements   | ✅ Working | Bulk loads data from CSV files                  |
-| Data Verification | ✅ Working | All data queryable after COPY operations        |
-
-## Technical Implementation Details
-
-### 1. Environment Requirements
-
-**Working Environment**: Browser with Web Workers support
-**Failed Environment**: Node.js (Worker2 constructor not available)
-**KuzuDB Version**: kuzu-wasm@0.11.1
-
-```javascript
-// Confirmed working initialization
-await kuzu.init();
-const db = new kuzu.Database('');  // In-memory database
-const conn = new kuzu.Connection(db);
-```
-
-### 2. FS API Implementation
-
-**Key Finding**: FS API is available and functional in browser environment
-
-```javascript
-// Verified working pattern
-await kuzu.FS.writeFile('/path/file.csv', csvData);
-const readData = await kuzu.FS.readFile('/path/file.csv');
-```
-
-**Critical Issue Solved**: FS.readFile data type handling
-
-- **Problem**: `readData.substring is not a function`
-- **Cause**: FS.readFile returns Buffer/Uint8Array, not string
-- **Solution**: Proper data type conversion
-
-```javascript
-// Fixed data handling
-let dataStr;
-if (typeof readData === 'string') {
-    dataStr = readData;
-} else if (readData instanceof Uint8Array || readData instanceof ArrayBuffer) {
-    dataStr = new TextDecoder().decode(readData);
-} else if (readData && readData.toString) {
-    dataStr = readData.toString();
-} else {
-    dataStr = String(readData);
-}
-```
-
-### 3. COPY Statement Implementation
-
-**Verified Working Pattern**:
-
-```javascript
-// 1. Write CSV to WASM filesystem
-await kuzu.FS.writeFile('/users.csv', csvData);
-
-// 2. Execute COPY statement
-const result = await conn.query("COPY User FROM '/users.csv'");
-await result.close();
-
-// 3. Data is immediately available for queries
-const verifyResult = await conn.query('MATCH (u:User) RETURN count(u)');
-```
-
-**CSV Format Requirements**:
-
-- Standard CSV format (comma-separated)
-- Header row with column names matching schema
-- Proper escaping for special characters
-- No additional formatting needed
-
-### 4. Schema Management
-
-**Critical Issue Solved**: Table existence conflicts
-
-- **Problem**: `Binder exception: User already exists in catalog`
-- **Cause**: Multiple test runs without cleanup
-- **Solution**: Drop tables before creation
-
-```javascript
-// Required cleanup pattern
-try {
-    await conn.query('DROP TABLE User IF EXISTS');
-    await conn.query('DROP TABLE City IF EXISTS');
-} catch (cleanupError) {
-    // Tables might not exist, ignore errors
-}
-
-// Then create fresh schema
-await conn.query('CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))');
-```
-
-## GitNexus Integration Strategy
-
-### 1. CSV Generator Service
-
-**Location**: `src/core/kuzu/csv-generator.ts`
-
-```typescript
-export class GitNexusCSVGenerator {
-    static generateNodeCSV(nodes: GraphNode[], label: string): string {
-        const filteredNodes = nodes.filter(node => node.label === label);
-        if (filteredNodes.length === 0) return '';
-      
-        // Get all unique properties for schema
-        const allProps = new Set(['id']);
-        filteredNodes.forEach(node => {
-            Object.keys(node.properties).forEach(key => allProps.add(key));
-        });
-      
-        const columns = Array.from(allProps);
-        const header = columns.join(',');
-      
-        const rows = filteredNodes.map(node => {
-            return columns.map(col => {
-                if (col === 'id') return this.escapeCSV(node.id);
-                const value = node.properties[col];
-                return value !== undefined ? this.escapeCSV(value) : '';
-            }).join(',');
-        });
-      
-        return [header, ...rows].join('\n');
-    }
-  
-    static generateRelationshipCSV(relationships: GraphRelationship[], type: string): string {
-        // Similar implementation for relationships
-        // Include source, target, and properties
-    }
-  
-    static escapeCSV(value: any): string {
-        if (value === null || value === undefined) return '';
-        const str = String(value);
-      
-        if (str.includes(',') || str.includes('"') || str.includes('\n')) {
-            return '"' + str.replace(/"/g, '""') + '"';
-        }
-        return str;
-    }
-}
-```
-
-### 2. Enhanced KuzuKnowledgeGraph
-
-**Location**: `src/core/graph/kuzu-knowledge-graph.ts`
-
-**Replace current batch methods**:
-
-```typescript
-// Current method (keep as fallback)
-private async commitNodesBatchWithMERGE(label: string, nodes: GraphNode[]): Promise<void> {
-    // Existing MERGE implementation
-}
-
-// New COPY method
-private async commitNodesBatchWithCOPY(label: string, nodes: GraphNode[]): Promise<void> {
-    try {
-        // Generate CSV
-        const csvData = GitNexusCSVGenerator.generateNodeCSV(nodes, label);
-      
-        // Write to WASM filesystem
-        const csvPath = `/temp_${label}_${Date.now()}.csv`;
-        await this.kuzuModule.FS.writeFile(csvPath, csvData);
-      
-        // Execute COPY statement
-        const result = await this.queryEngine.executeQuery(`COPY ${label} FROM '${csvPath}'`);
-        await result.close();
-      
-        console.log(`✅ COPY: Successfully loaded ${nodes.length} ${label} nodes`);
-      
-    } catch (error) {
-        console.error(`❌ COPY failed for ${label}:`, error);
-        throw error;
-    }
-}
-
-// Main batch method with fallback
-private async commitNodesBatch(label: string, nodes: GraphNode[]): Promise<void> {
-    try {
-        await this.commitNodesBatchWithCOPY(label, nodes);
-    } catch (copyError) {
-        console.warn(`⚠️ COPY failed, falling back to MERGE for ${label}:`, copyError.message);
-        await this.commitNodesBatchWithMERGE(label, nodes);
-    }
-}
-```
-
-### 3. KuzuDB Module Access
-
-**Location**: `src/core/kuzu/kuzu-npm-integration.ts`
-
-**Add FS API access**:
-
-```typescript
-// Expose FS API in KuzuInstance interface
-export interface KuzuInstance {
-    // ... existing methods
-    getFS(): any; // Access to FS API
-}
-
-// In createKuzuInstance()
-return {
-    // ... existing methods
-    getFS(): any {
-        return kuzuModule.default.FS;
-    }
-};
-```
-
-### 4. Integration Points
-
-**Files to modify**:
-
-1. `src/core/graph/kuzu-knowledge-graph.ts` - Add COPY batch methods
-2. `src/core/kuzu/kuzu-npm-integration.ts` - Expose FS API
-3. `src/core/kuzu/csv-generator.ts` - New CSV generation service
-4. `src/config/features.ts` - Add COPY feature flag
-
-**Feature Flag**:
-
-```typescript
-export function isKuzuCopyEnabled(): boolean {
-    return cachedConfig?.features.enableKuzuCopy ?? false;
-}
-```
-
-## Performance Characteristics
-
-### Current MERGE Approach
-
-- **Operations**: N individual MERGE statements per batch
-- **Memory**: String concatenation for large queries
-- **Database Load**: N query parsing operations
-- **Scalability**: Linear degradation with batch size
-
-### COPY Approach
-
-- **Operations**: 1 FS write + 1 COPY statement per batch
-- **Memory**: Streaming CSV generation
-- **Database Load**: 1 optimized bulk operation
-- **Scalability**: Constant time regardless of batch size
-
-### Expected Performance Gains
-
-- **Small batches (10-50 items)**: 2-3x improvement
-- **Medium batches (100-500 items)**: 5-7x improvement
-- **Large batches (1000+ items)**: 10-15x improvement
-
-## Error Handling Strategy
-
-### 1. Environment Detection
-
-```typescript
-function isCopySupported(): boolean {
-    return !!(kuzu.FS && kuzu.FS.writeFile && typeof kuzu.FS.writeFile === 'function');
-}
-```
-
-### 2. Graceful Degradation
-
-```typescript
-if (isCopySupported() && isKuzuCopyEnabled()) {
-    try {
-        await commitNodesBatchWithCOPY(label, nodes);
-    } catch (copyError) {
-        await commitNodesBatchWithMERGE(label, nodes);
-    }
-} else {
-    await commitNodesBatchWithMERGE(label, nodes);
-}
-```
-
-### 3. Error Categories
-
-- **FS Errors**: File system operations (writeFile/readFile)
-- **COPY Errors**: SQL execution errors (syntax, schema mismatch)
-- **Data Errors**: CSV format or encoding issues
-
-## Testing Strategy
-
-### 1. Unit Tests
-
-- CSV generation with various data types
-- Error handling for malformed data
-- Schema compatibility validation
-
-### 2. Integration Tests
-
-- End-to-end COPY workflow
-- Fallback mechanism verification
-- Performance benchmarking
-
-### 3. Browser Compatibility
-
-- Test across different browsers
-- Verify Web Worker support
-- Memory usage monitoring
-
-## Deployment Considerations
-
-### 1. Feature Flag Rollout
-
-- **Phase 1**: Internal testing with feature flag disabled
-- **Phase 2**: Gradual rollout to subset of users
-- **Phase 3**: Full deployment with monitoring
-
-### 2. Monitoring Metrics
-
-- COPY success/failure rates
-- Performance improvement measurements
-- Memory usage comparison
-- Error frequency and types
-
-### 3. Rollback Strategy
-
-- Feature flag can instantly disable COPY approach
-- Automatic fallback ensures no service disruption
-- Existing MERGE approach remains fully functional
-
-## Known Limitations
-
-### 1. Environment Constraints
-
-- **Browser Only**: COPY approach requires browser environment
-- **Web Workers**: Depends on Web Worker support
-- **Memory**: WASM filesystem is in-memory only
-
-### 2. Data Constraints
-
-- **CSV Format**: Data must be CSV-compatible
-- **File Paths**: Limited to WASM filesystem paths
-- **Encoding**: UTF-8 encoding required
-
-### 3. Schema Constraints
-
-- **Table Existence**: Tables must exist before COPY
-- **Column Matching**: CSV columns must match schema
-- **Data Types**: Proper type conversion required
-
-## Future Enhancements
-
-### 1. Streaming CSV Generation
-
-- Process large datasets without loading into memory
-- Incremental file writing for very large batches
-
-### 2. Parallel COPY Operations
-
-- Multiple concurrent COPY statements
-- Batch processing optimization
-
-### 3. Advanced Error Recovery
-
-- Partial batch recovery on COPY failures
-- Detailed error reporting and diagnostics
-
-## Implementation Checklist
-
-- [ ] Create CSV generator service
-- [ ] Implement COPY-based bulk loader
-- [ ] Add FS API access to KuzuInstance
-- [ ] Implement fallback strategy
-- [ ] Add feature flag support
-- [ ] Create comprehensive tests
-- [ ] Performance benchmarking
-- [ ] Documentation updates
-- [ ] Gradual rollout plan
-- [ ] Monitoring and alerting setup
-
-## Conclusion
-
-The COPY approach has been **proven to work** through comprehensive testing. Implementation should proceed with:
-
-1. **Immediate**: CSV generator and COPY bulk loader
-2. **Short-term**: Feature flag and fallback mechanism
-3. **Long-term**: Performance optimization and monitoring
-
-This implementation will provide significant performance improvements for GitNexus, especially for large repository ingestion scenarios.

KUZU_DB_INTEGRATION_STATUS.md

@@ -1,213 +0,0 @@
-# KuzuDB Integration Status Report
-
-## 🎉 **IMPLEMENTATION COMPLETE!**
-
-The full KuzuDB integration has been successfully implemented according to the implementation plan. The system now supports **dual-write functionality** where data is written to both JSON (primary) and KuzuDB (secondary) storage systems simultaneously.
-
----
-
-## ✅ **What's Been Implemented**
-
-### **Phase 1: Foundation Setup - COMPLETE**
-- ✅ **KuzuDB WASM Loader** (`src/core/kuzu/kuzu-loader.ts`) - Full implementation
-- ✅ **KuzuDB Query Engine** (`src/core/graph/kuzu-query-engine.ts`) - Complete with caching, transactions, performance monitoring
-- ✅ **KuzuDB Knowledge Graph** (`src/core/graph/kuzu-knowledge-graph.ts`) - Full implementation with batching and caching
-- ✅ **KuzuDB Schema Manager** (`src/core/kuzu/kuzu-schema.ts`) - Complete schema definitions for all node and relationship types
-- ✅ **Feature Flag Integration** - Full KuzuDB feature flag support
-
-### **Phase 2: Parallel Storage Implementation - COMPLETE**
-- ✅ **KuzuProcessorBase** - Abstract base class with dual-write pattern, transaction management, and statistics
-- ✅ **Enhanced StructureProcessor** - Dual-write support for Project, Folder, File nodes and CONTAINS relationships
-- ✅ **Enhanced ParsingProcessor** - Dual-write support for all definition nodes and relationships
-- ✅ **Enhanced ImportProcessor** - Dual-write support for IMPORTS relationships
-- ✅ **Enhanced CallProcessor** - Dual-write support for CALLS relationships
-
-### **Core Features Implemented**
-- ✅ **Dual-Write Pattern** - Data written to both JSON and KuzuDB simultaneously
-- ✅ **Transaction Management** - Begin, commit, rollback support
-- ✅ **Error Handling** - Graceful degradation to JSON-only mode
-- ✅ **Performance Monitoring** - Comprehensive statistics and timing metrics
-- ✅ **Batch Processing** - Optimized batch operations for better performance
-- ✅ **Caching System** - LRU cache for improved query performance
-- ✅ **Schema Validation** - Complete schema definitions for all node and relationship types
-
----
-
-## 🏗️ **Architecture Overview**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    GitNexus KuzuDB Integration                  │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐ │
-│  │ JSON Storage    │    │ KuzuDB Storage  │    │ Feature Flags│ │
-│  │ (Primary)       │    │ (Secondary)     │    │ (Control)    │ │
-│  └─────────────────┘    └─────────────────┘    └──────────────┘ │
-│           │                       │                      │      │
-│           └───────────────────────┼──────────────────────┘      │
-│                                   │                             │
-│  ┌─────────────────────────────────────────────────────────────┐ │
-│  │              KuzuProcessorBase                              │ │
-│  │   • Dual-write pattern                                     │ │
-│  │   • Transaction management                                 │ │
-│  │   • Error handling & graceful degradation                 │ │
-│  │   • Performance monitoring & statistics                   │ │
-│  └─────────────────────────────────────────────────────────────┘ │
-│           │              │              │              │        │
-│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
-│  │ Structure    │ │ Parsing      │ │ Import       │ │ Call     │ │
-│  │ Processor    │ │ Processor    │ │ Processor    │ │Processor │ │
-│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 🚀 **How to Use KuzuDB Integration**
-
-### **1. Enable KuzuDB (Currently Disabled by Default)**
-
-```typescript
-import { featureFlags } from './src/config/feature-flags';
-
-// Enable KuzuDB integration
-featureFlags.enableKuzuDB();
-
-// Check status
-console.log('KuzuDB enabled:', featureFlags.getFlag('enableKuzuDB'));
-```
-
-### **2. Current Storage Behavior**
-
-**With KuzuDB Disabled (Default):**
-- ✅ Data stored in JSON format (existing functionality)
-- ✅ All processors work as before
-- ✅ No performance impact
-
-**With KuzuDB Enabled:**
-- ✅ Data written to **both** JSON and KuzuDB simultaneously
-- ✅ JSON remains primary storage (no breaking changes)
-- ✅ KuzuDB failures gracefully degrade to JSON-only mode
-- ✅ Enhanced logging and statistics available
-
-### **3. Enhanced Console Output**
-
-When KuzuDB is enabled, you'll see enhanced logging:
-
-```
-📁 Processing structure for MyProject with 150 paths...
-🚀 Initializing KuzuDB integration...
-✅ KuzuDB integration initialized successfully.
-✅ Structure processing completed. Hidden 45 items from display.
-
-📊 StructureProcessor Statistics:
-  Total Nodes Processed: 105
-  Total Relationships Processed: 104
-  KuzuDB Nodes Written: 105
-  KuzuDB Relationships Written: 104
-  KuzuDB Errors: 0
-  Processing Time: 1,234.56ms
-```
-
----
-
-## 📊 **Current Status**
-
-| Component | Status | Notes |
-|-----------|--------|-------|
-| **KuzuDB WASM Loader** | ✅ Complete | Ready for WASM binary integration |
-| **Query Engine** | ✅ Complete | Full Cypher query support, caching, transactions |
-| **Knowledge Graph** | ✅ Complete | Drop-in replacement for SimpleKnowledgeGraph |
-| **Schema Manager** | ✅ Complete | All node and relationship types defined |
-| **Dual-Write Pattern** | ✅ Complete | All 4 processors support dual-write |
-| **Feature Flags** | ✅ Complete | Full control over KuzuDB integration |
-| **Error Handling** | ✅ Complete | Graceful degradation to JSON-only mode |
-| **Performance Monitoring** | ✅ Complete | Comprehensive statistics and timing |
-| **Transaction Management** | ✅ Complete | ACID compliance with rollback support |
-
----
-
-## 🔧 **What's Missing (Optional Enhancements)**
-
-1. **KuzuDB WASM Binary**: Need to add the actual KuzuDB WASM file to `public/kuzu/`
-2. **Query Migration**: Phase 3 implementation (read operations from KuzuDB)
-3. **UI Integration**: Update UI components to use KuzuDB queries
-4. **Advanced Analytics**: Graph algorithms and complex queries
-
----
-
-## 🎯 **Key Benefits Achieved**
-
-### **1. Zero Breaking Changes**
-- All existing functionality preserved
-- JSON storage remains primary
-- Backward compatibility maintained
-
-### **2. Production-Ready Error Handling**
-- KuzuDB failures don't break the system
-- Graceful degradation to JSON-only mode
-- Comprehensive error logging
-
-### **3. Performance & Monitoring**
-- Detailed statistics for all operations
-- Performance timing and success rates
-- Transaction management with rollback
-
-### **4. Scalable Architecture**
-- Dual-write pattern supports gradual migration
-- Feature flags enable controlled rollout
-- Extensible base classes for future enhancements
-
----
-
-## 🧪 **Testing the Integration**
-
-### **Current Compilation Status**
-- ✅ **Core KuzuDB components compile successfully**
-- ✅ **All processors extend KuzuProcessorBase properly**
-- ✅ **Feature flags work correctly**
-- ⚠️ **Some test files need updates** (non-critical)
-- ⚠️ **Some UI components need interface updates** (non-critical)
-
-### **What You Can Test Now**
-1. **Enable KuzuDB via feature flags**
-2. **Run the ingestion pipeline** - it will attempt dual-write
-3. **Observe enhanced logging and statistics**
-4. **Verify graceful degradation** when KuzuDB WASM is not available
-
----
-
-## 📋 **Next Steps (Optional)**
-
-### **Phase 3: Query Migration** (Future Enhancement)
-1. Replace `graph.nodes.filter()` with KuzuDB queries
-2. Update UI components to use KuzuDB query results
-3. Implement query performance comparisons
-
-### **Phase 4: JSON Deprecation** (Future Enhancement)
-1. Remove dual-write pattern
-2. Make KuzuDB the primary storage
-3. Implement advanced graph analytics
-
----
-
-## 🎉 **Conclusion**
-
-**The KuzuDB integration is FULLY IMPLEMENTED and ready for use!** 
-
-The system now supports:
-- ✅ **Dual-write functionality** (JSON + KuzuDB)
-- ✅ **Complete error handling** and graceful degradation
-- ✅ **Production-ready architecture** with monitoring and statistics
-- ✅ **Feature flag control** for safe deployment
-- ✅ **Zero breaking changes** to existing functionality
-
-You can now:
-1. **Enable KuzuDB** via feature flags
-2. **Test the dual-write system** with any repository
-3. **Observe enhanced logging** and performance metrics
-4. **Add the KuzuDB WASM binary** when ready for full functionality
-
-The foundation is solid and ready for the next phases of the migration plan! 🚀

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.

MEMORY_LEAK_FIXES.md

@@ -1,163 +0,0 @@
-# Memory Leak Fixes for Worker Pool Parallel Processing
-
-## Issues Identified and Fixed
-
-### 1. **Event Listener Memory Leaks** ✅ FIXED
-**Problem**: WebWorkerPool wasn't properly cleaning up event listeners during shutdown, causing memory leaks.
-
-**Fix Applied**:
-- Added proper event listener cleanup in `shutdown()` method
-- Set `worker.onmessage = null`, `worker.onerror = null`, `worker.onmessageerror = null` before terminating workers
-- Clear the `eventListeners` Map during shutdown
-
-**Files Modified**: `src/lib/web-worker-pool.ts`
-
-### 2. **Singleton Worker Pool Issues** ✅ FIXED  
-**Problem**: FileProcessingPool singleton instances were never cleaned up, accumulating memory over time.
-
-**Fix Applied**:
-- Added `shutdownInstance()` static method to properly cleanup singleton instances
-- Added `hasInstance()` method to check if instance exists
-- Added `cleanupAllPools()` utility method in WebWorkerPoolUtils
-
-**Files Modified**: `src/lib/web-worker-pool.ts`
-
-### 3. **Worker Error Handling** ✅ FIXED
-**Problem**: Errors in worker termination could leave resources hanging.
-
-**Fix Applied**:
-- Improved `handleWorkerError()` method to properly cleanup worker event listeners
-- Added try-catch around worker termination
-- Ensure workers are removed from pools even on errors
-
-**Files Modified**: `src/lib/web-worker-pool.ts`
-
-### 4. **Missing Memory Monitoring** ✅ FIXED
-**Problem**: No memory usage tracking or automatic cleanup triggers.
-
-**Fix Applied**:
-- Added `monitorMemoryUsage()` method with automatic cleanup triggers
-- Added memory usage estimation in `getStats()` method
-- Created periodic memory monitoring in ParallelParsingProcessor
-- Added global cleanup handlers for page unload and visibility changes
-
-**Files Modified**: `src/lib/web-worker-pool.ts`, `src/core/ingestion/parallel-parsing-processor.ts`
-
-### 5. **AST Map Accumulation** ✅ FIXED
-**Problem**: Large AST maps and function tries were kept in memory without limits.
-
-**Fix Applied**:
-- Added `MAX_AST_MAP_SIZE` constant (1000 entries)
-- Implemented `cleanupASTMap()` method to remove old entries when limit is exceeded
-- Added proper cleanup of AST maps, processed files, and function tries in shutdown
-- Added Tree-sitter parser cleanup with `parser.delete()`
-
-**Files Modified**: `src/core/ingestion/parallel-parsing-processor.ts`
-
-### 6. **Pipeline Cleanup Issues** ✅ FIXED
-**Problem**: Parallel pipeline wasn't ensuring proper cleanup on errors.
-
-**Fix Applied**:
-- Enhanced cleanup method to call `WebWorkerPoolUtils.cleanupAllPools()`
-- Added cleanup in both error and finally blocks
-- Ensured cleanup happens even when errors occur
-
-**Files Modified**: `src/core/ingestion/parallel-pipeline.ts`
-
-## New Features Added
-
-### Memory Monitoring System
-- **Automatic Memory Monitoring**: Checks memory usage every 30 seconds
-- **Threshold-based Cleanup**: Triggers cleanup when memory usage exceeds 500MB
-- **AST Map Size Limiting**: Automatically cleans up old AST entries when limit exceeded
-- **Global Memory Monitoring**: Monitors overall browser memory usage
-
-### Global Cleanup Handlers
-- **Page Unload Cleanup**: Automatically cleans up when user closes/refreshes page
-- **Tab Visibility Cleanup**: Cleans up when user switches tabs (page becomes hidden)
-- **Manual Cleanup Functions**: Utilities for forcing cleanup when needed
-
-### Enhanced Error Handling
-- **Graceful Worker Termination**: Proper cleanup even when workers fail
-- **Resource Leak Prevention**: Ensures all event listeners and references are cleared
-- **Error Recovery**: System continues working even if some workers fail
-
-## Usage Instructions
-
-### 1. Initialize Cleanup Handlers (RECOMMENDED)
-```typescript
-import { initializeWorkerPoolCleanup } from './src/lib/worker-pool-init.js';
-
-// Call this once when your app starts
-initializeWorkerPoolCleanup();
-```
-
-### 2. Manual Cleanup (if needed)
-```typescript
-import { cleanupWorkerPools } from './src/lib/worker-pool-init.js';
-
-// Force cleanup when needed
-await cleanupWorkerPools();
-```
-
-### 3. Monitor Memory Usage
-```typescript
-import { getMemoryInfo } from './src/lib/worker-pool-init.js';
-
-const memInfo = getMemoryInfo();
-if (memInfo) {
-  console.log(`Memory: ${memInfo.usedMB}MB / ${memInfo.totalMB}MB (${memInfo.percentage}%)`);
-}
-```
-
-## Performance Improvements
-
-### Before Fixes:
-- Worker pools accumulated without cleanup
-- Event listeners remained attached after worker termination
-- AST maps grew unbounded causing memory bloat
-- No automatic memory management
-
-### After Fixes:
-- **Automatic Resource Cleanup**: All resources properly cleaned up
-- **Memory Usage Monitoring**: Real-time monitoring with automatic cleanup triggers
-- **Bounded Memory Growth**: AST maps and other data structures have size limits
-- **Graceful Shutdown**: Proper cleanup on app/tab close
-
-## Monitoring and Debugging
-
-The system now provides detailed logging for:
-- Memory usage statistics
-- Worker pool status
-- Cleanup operations
-- Error conditions
-
-Check browser console for messages like:
-```
-ParallelParsingProcessor Memory Stats:
-- Memory Manager: 245.67MB used, 150 files cached
-- AST Map: 750 entries
-- Processed Files: 890 entries
-
-Memory usage: 245.67MB / 512.00MB (47.98%)
-```
-
-## Files Created/Modified
-
-### Modified Files:
-- `src/lib/web-worker-pool.ts` - Enhanced with memory leak fixes
-- `src/core/ingestion/parallel-parsing-processor.ts` - Added memory monitoring and cleanup
-- `src/core/ingestion/parallel-pipeline.ts` - Enhanced cleanup handling
-
-### New Files:
-- `src/lib/worker-pool-init.ts` - Initialization and utility functions
-- `MEMORY_LEAK_FIXES.md` - This documentation
-
-## Testing Recommendations
-
-1. **Monitor Memory Usage**: Watch browser's Task Manager during large codebase processing
-2. **Test Tab Switching**: Switch tabs during processing to verify cleanup triggers
-3. **Test Page Refresh**: Refresh page during processing to ensure proper cleanup
-4. **Long-running Tests**: Process multiple large codebases to verify no memory accumulation
-
-The system should now maintain stable memory usage even during intensive parallel processing operations.

PARALLEL_PROCESSING_VERIFICATION.md

@@ -1,154 +0,0 @@
-# Parallel Processing Verification & Fixes
-
-## 🎯 **Goal: Ensure Parallel Processing Produces Identical Output to Single-Threaded**
-
-## ❌ **Critical Issues Found and Fixed**
-
-### **Issue #1: Wrong Pipeline Class in Worker** 🚨 **CRITICAL**
-**Problem**: The `IngestionWorker` was always using `GraphPipeline` (single-threaded) instead of `ParallelGraphPipeline` when parallel processing was enabled.
-
-**Impact**: Even when "parallel processing" was enabled, it was actually running single-threaded processing in the worker, just with the parallel flag set.
-
-**Fix Applied**:
-```typescript
-// BEFORE (BROKEN)
-export class IngestionWorker {
-  private pipeline: GraphPipeline; // Always single-threaded!
-  constructor() {
-    this.pipeline = new GraphPipeline(); // Wrong!
-  }
-}
-
-// AFTER (FIXED)
-export class IngestionWorker {
-  private pipeline: GraphPipeline | ParallelGraphPipeline;
-  constructor() {
-    if (isParallelParsingEnabled()) {
-      this.pipeline = new ParallelGraphPipeline(); // Correct!
-    } else {
-      this.pipeline = new GraphPipeline();
-    }
-  }
-}
-```
-
-### **Issue #2: Incorrect Duplicate Detection** 🚨 **CRITICAL**
-**Problem**: Different duplicate detection logic between processors.
-
-**Single-threaded (CORRECT)**:
-```typescript
-if (this.duplicateDetector.checkAndMark(nodeId)) continue; // ✅ Checks AND marks
-```
-
-**Parallel (BROKEN)**:
-```typescript
-if (this.duplicateDetector.isDuplicate(nodeId)) return; // ❌ Only checks, doesn't mark
-```
-
-**Impact**: Parallel processor could create duplicate nodes because it wasn't marking them as processed.
-
-**Fix Applied**: Changed parallel processor to use `checkAndMark()`.
-
-### **Issue #3: Property Format Inconsistency** 🚨 **MEDIUM**
-**Problem**: Node properties stored in different formats.
-
-**Single-threaded**:
-```typescript
-decorators: def.decorators,        // Array format
-extends: def.extends,              // Array format  
-implements: def.implements,        // Array format
-```
-
-**Parallel (BROKEN)**:
-```typescript
-decorators: definition.decorators?.join(', '),   // String format ❌
-extends: definition.extends?.join(', '),         // String format ❌
-implements: definition.implements?.join(', '),   // String format ❌
-```
-
-**Impact**: Import/call processors expecting arrays would fail or produce different results.
-
-**Fix Applied**: Made parallel processor store arrays to match single-threaded.
-
-### **Issue #4: Progress Callback Integration** ✅ **ENHANCEMENT**
-**Problem**: Worker wasn't properly forwarding progress updates from `ParallelGraphPipeline`.
-
-**Fix Applied**: Added proper progress callback integration.
-
-## ✅ **Verification Checklist**
-
-### **Pipeline Selection** ✅
-- [x] Worker uses correct pipeline class based on feature flag
-- [x] `ParallelGraphPipeline` used when `isParallelParsingEnabled() === true`
-- [x] `GraphPipeline` used when `isParallelParsingEnabled() === false`
-
-### **Data Processing** ✅
-- [x] Duplicate detection logic identical (`checkAndMark()`)
-- [x] Node property formats identical (arrays not strings)
-- [x] Node ID generation identical
-- [x] Node label mapping identical
-
-### **Graph Structure** ✅
-- [x] Same 4-pass pipeline structure
-- [x] Same processor sequence (Structure → Parsing → Import → Call)
-- [x] Same AST map and function registry handling
-- [x] Same relationship creation logic
-
-### **Memory Management** ✅
-- [x] Both use LRU cache service
-- [x] Both maintain AST maps for compatibility
-- [x] Proper cleanup in both modes
-
-## 🔍 **Expected Behavior After Fixes**
-
-### **Single-threaded Mode**:
-- Uses `GraphPipeline` 
-- Uses `ParsingProcessor`
-- Sequential file processing
-- Direct definition extraction
-
-### **Parallel Mode**:
-- Uses `ParallelGraphPipeline`
-- Uses `ParallelParsingProcessor` 
-- Worker pool parallel processing
-- Worker-extracted definitions + main thread AST recreation
-
-### **Identical Output**:
-Both modes should now produce:
-- ✅ Same node counts by type
-- ✅ Same relationship counts by type  
-- ✅ Same import relationships (IMPORTS, DEPENDS_ON)
-- ✅ Same function call relationships (CALLS)
-- ✅ Same definition nodes with identical properties
-- ✅ Same graph connectivity
-
-## 🧪 **Testing Recommendations**
-
-1. **Process the same codebase** with both modes enabled/disabled
-2. **Compare graph statistics** - nodes by type, relationships by type
-3. **Verify specific relationships** - check for import and call relationships
-4. **Check isolated nodes** - should be minimal in both modes
-5. **Performance comparison** - parallel should be faster on large codebases
-
-## 📊 **Success Metrics**
-
-The parallel processing should now show:
-```
-✅ Relationships by type: {CONTAINS: X, DEFINES: Y, IMPORTS: Z, CALLS: W}
-✅ No "missing import relationships" warnings
-✅ No "missing function call relationships" warnings  
-✅ Same graph node/relationship counts as single-threaded
-```
-
-Instead of the previous broken output:
-```
-❌ Relationships by type: {CONTAINS: 103, DEFINES: 1971} // Missing IMPORTS/CALLS!
-❌ "No import relationships found between files"
-❌ "No function call relationships found"
-```
-
-## 🎯 **Conclusion**
-
-The parallel processing implementation now uses the correct pipeline classes and processing logic to produce **identical output** to single-threaded mode, while maintaining the performance benefits of parallel worker pool processing.
-
-**The root cause was using the wrong pipeline class in the worker** - a simple but critical configuration issue that made "parallel processing" actually run single-threaded code with inconsistent data structures.

PARSING_AND_STORAGE_TECHNICAL_DOCUMENTATION.md

@@ -1,623 +0,0 @@
-# GitNexus Parsing and Storage Technical Documentation
-## Complete Data Flow Analysis for Kuzu DB Migration
-
-> **Purpose**: This document provides an extremely detailed, line-by-line analysis of GitNexus's current parsing and storage implementation to facilitate the migration from JSON-based storage to Kuzu DB.
-
----
-
-## Executive Summary
-
-GitNexus uses a **4-pass ingestion pipeline** that processes code repositories into a knowledge graph stored in JSON format. The system employs in-memory data structures (`SimpleKnowledgeGraph`) with JSON serialization for persistence. This document traces every step of the data transformation process to enable precise Kuzu DB migration.
-
-### Key Storage Points Identified:
-1. **In-Memory Graph Storage**: `SimpleKnowledgeGraph` class with arrays
-2. **JSON Export/Import**: Via `src/lib/export.ts` functions
-3. **LRU Cache Storage**: For AST and parsing results
-4. **LocalStorage**: For settings, feature flags, and chat history
-5. **IndexedDB**: Planned for KuzuDB persistence (WIP)
-
----
-
-## 1. Core Data Structures
-
-### 1.1 Knowledge Graph Structure
-
-**File**: `src/core/graph/types.ts`
-
-```typescript
-// Primary graph interface - this is what gets stored
-export interface KnowledgeGraph {
-  nodes: GraphNode[];           // Array of all nodes
-  relationships: GraphRelationship[];  // Array of all relationships
-}
-
-// Node structure - every entity in the system
-export interface GraphNode {
-  id: string;                   // Unique identifier (generated)
-  label: NodeLabel;             // Type classification
-  properties: NodeProperties;   // All metadata as key-value pairs
-}
-
-// Relationship structure - connections between nodes
-export interface GraphRelationship {
-  id: string;                   // Unique identifier (generated)
-  type: RelationshipType;       // Relationship classification
-  source: string;               // Source node ID
-  target: string;               // Target node ID  
-  properties: RelationshipProperties; // Metadata as key-value pairs
-}
-```
-
-**Node Types** (`NodeLabel`):
-- `'Project'` - Repository root
-- `'Folder'` - Directory nodes
-- `'File'` - Source files
-- `'Function'` - Function definitions
-- `'Class'` - Class definitions
-- `'Method'` - Class methods
-- `'Variable'` - Variable declarations
-- `'Interface'` - TypeScript interfaces
-- `'Decorator'` - Python/TS decorators
-- `'Import'` - Import statements
-- `'Type'` - Type definitions
-- `'CodeElement'` - Generic code elements
-
-**Relationship Types** (`RelationshipType`):
-- `'CONTAINS'` - Hierarchical containment (folder → file, file → function)
-- `'CALLS'` - Function/method calls
-- `'INHERITS'` - Class inheritance
-- `'OVERRIDES'` - Method overrides
-- `'IMPORTS'` - Module imports
-- `'IMPLEMENTS'` - Interface implementations
-- `'DECORATES'` - Decorator applications
-
-### 1.2 Implementation Class
-
-**File**: `src/core/graph/graph.ts`
-
-```typescript
-export class SimpleKnowledgeGraph implements KnowledgeGraph {
-  nodes: GraphNode[] = [];              // Simple array storage
-  relationships: GraphRelationship[] = []; // Simple array storage
-
-  addNode(node: GraphNode): void {
-    this.nodes.push(node);              // Direct array append
-  }
-
-  addRelationship(relationship: GraphRelationship): void {
-    this.relationships.push(relationship); // Direct array append
-  }
-}
-```
-
-**Critical Storage Characteristics**:
-- **No indexing**: Linear search for node/relationship lookups
-- **No constraints**: No validation of referential integrity
-- **Memory-only**: No built-in persistence
-- **Simple append**: No deduplication or conflict resolution
-
----
-
-## 2. Four-Pass Ingestion Pipeline
-
-The pipeline transforms raw repository data through four distinct phases, each building upon the previous:
-
-### Pass 1: Structure Analysis (`StructureProcessor`)
-
-**File**: `src/core/ingestion/structure-processor.ts`
-
-**Input**: 
-- `projectRoot: string` - Repository path
-- `projectName: string` - Repository name  
-- `filePaths: string[]` - All discovered file paths
-
-**Process**:
-1. **Project Node Creation** (Lines 58-61):
-   ```typescript
-   const projectNode = this.createProjectNode(projectName, projectRoot);
-   graph.addNode(projectNode);  // STORAGE POINT 1
-   ```
-
-2. **Path Categorization** (Lines 87-127):
-   ```typescript
-   const { directories, files } = this.categorizePaths(filePaths);
-   // Separates files from directories using path analysis
-   ```
-
-3. **Directory Node Creation** (Lines 147-174):
-   ```typescript
-   const directoryNodes = this.createDirectoryNodes(visibleDirectories);
-   directoryNodes.forEach(node => graph.addNode(node)); // STORAGE POINT 2
-   ```
-
-4. **File Node Creation** (Lines 179-208):
-   ```typescript
-   const fileNodes = this.createFileNodes(visibleFiles);
-   fileNodes.forEach(node => graph.addNode(node)); // STORAGE POINT 3
-   ```
-
-5. **CONTAINS Relationship Creation** (Lines 213-255):
-   ```typescript
-   this.createContainsRelationships(graph, projectNode.id, visibleDirectories, visibleFiles);
-   // Creates hierarchical relationships - STORAGE POINT 4
-   ```
-
-**Storage Pattern**: Direct `graph.addNode()` and `graph.addRelationship()` calls append to arrays.
-
-### Pass 2: Code Parsing (`ParsingProcessor` / `ParallelParsingProcessor`)
-
-**Files**: 
-- `src/core/ingestion/parsing-processor.ts`
-- `src/core/ingestion/parallel-parsing-processor.ts`
-
-**Input**:
-- `filePaths: string[]` - Files to parse
-- `fileContents: Map<string, string>` - File content mapping
-- `options?: ParsingOptions` - Filtering options
-
-**Critical Data Structures**:
-
-1. **AST Storage** (Line 55 in `parsing-processor.ts`):
-   ```typescript
-   private astMap: Map<string, ParsedAST> = new Map();
-   // STORAGE POINT 5 - AST trees indexed by file path
-   ```
-
-2. **Function Registry** (Line 56):
-   ```typescript
-   private functionTrie: FunctionRegistryTrie = new FunctionRegistryTrie();
-   // STORAGE POINT 6 - Searchable function definitions
-   ```
-
-**Process Flow**:
-
-1. **File Filtering** (Lines 116-152):
-   ```typescript
-   const filteredFiles = this.applyFiltering(filePaths, fileContents, options);
-   // Applies directory and extension filters
-   ```
-
-2. **Tree-sitter Initialization** (Lines 84, 245):
-   ```typescript
-   await this.initializeParser();
-   // Loads WASM parsers for each language
-   ```
-
-3. **Batch Processing** (Lines 86-108):
-   ```typescript
-   const batchProcessor = new BatchProcessor<string, void>(BATCH_SIZE, async (filePaths: string[]) => {
-     for (const filePath of filePaths) {
-       await this.parseFile(graph, filePath, content); // CRITICAL PARSING
-       this.processedFiles.add(filePath);
-     }
-   });
-   ```
-
-4. **Definition Extraction** (`parseFile` method):
-   ```typescript
-   // Extracts: functions, classes, methods, variables, interfaces, types
-   // Each creates nodes via: graph.addNode(definitionNode) - STORAGE POINT 7
-   ```
-
-**Parallel Processing Variant**:
-- Uses Web Workers for CPU-intensive parsing
-- Results aggregated in main thread
-- Same storage patterns but with worker coordination
-
-### Pass 3: Import Resolution (`ImportProcessor`)
-
-**File**: `src/core/ingestion/import-processor.ts`
-
-**Input**:
-- `graph: KnowledgeGraph` - Current graph state
-- `astMap: Map<string, ParsedAST>` - Parsed ASTs
-- `fileContents: Map<string, string>` - File contents
-
-**Critical Data Structure**:
-```typescript
-interface ImportMap {
-  [importingFile: string]: {
-    [localName: string]: {
-      targetFile: string;
-      exportedName: string;
-      importType: 'default' | 'named' | 'namespace' | 'dynamic';
-    }
-  }
-}
-private importMap: ImportMap = {}; // STORAGE POINT 8
-```
-
-**Process Flow**:
-
-1. **Import Extraction** (Lines 84-88):
-   ```typescript
-   for (const [filePath, ast] of astMap) {
-     const fileImports = await this.processFileImports(filePath, ast, graph);
-     // Extracts import statements from AST
-   }
-   ```
-
-2. **Language-Specific Processing**:
-   - **JavaScript/TypeScript** (Lines 231-324): Handles ES6 imports, CommonJS requires
-   - **Python** (Lines 160-226): Handles `import` and `from...import` statements
-
-3. **Module Path Resolution** (Lines 522-606):
-   ```typescript
-   private resolveModulePath(moduleName: string, importingFile: string, language: string): string
-   // Resolves relative and absolute imports to actual file paths
-   ```
-
-4. **Relationship Creation** (Lines 611-645):
-   ```typescript
-   private createImportRelationship(graph: KnowledgeGraph, importInfo: ImportInfo): void {
-     // Creates IMPORTS relationships - STORAGE POINT 9
-     graph.relationships.push(relationship);
-   }
-   ```
-
-### Pass 4: Call Resolution (`CallProcessor`)
-
-**File**: `src/core/ingestion/call-processor.ts`
-
-**Input**:
-- `graph: KnowledgeGraph` - Current graph
-- `astMap: Map<string, ParsedAST>` - ASTs for call extraction
-- `importMap: ImportMap` - Import resolution data
-
-**Process Flow**:
-
-1. **Call Extraction** (Lines 86-120):
-   ```typescript
-   private async processFileCalls(filePath: string, ast: ParsedAST, graph: KnowledgeGraph) {
-     const calls = this.extractFunctionCalls(ast.tree!.rootNode, filePath);
-     // Extracts function/method call sites from AST
-   }
-   ```
-
-2. **3-Stage Resolution Strategy** (Lines 146-162):
-   ```typescript
-   // Stage 1: Exact Match using ImportMap (High Confidence)
-   // Stage 2: Same-Module Match (Medium Confidence)  
-   // Stage 3: Heuristic Fallback (Low Confidence)
-   ```
-
-3. **Call Relationship Creation** (Lines 99-101):
-   ```typescript
-   if (resolution.success && resolution.targetNodeId) {
-     this.createCallRelationship(graph, call, resolution.targetNodeId);
-     // Creates CALLS relationships - STORAGE POINT 10
-   }
-   ```
-
----
-
-## 3. JSON Storage Implementation
-
-### 3.1 Export Functions
-
-**File**: `src/lib/export.ts`
-
-**Primary Export Function** (Lines 34-68):
-```typescript
-export function exportGraphToJSON(
-  graph: KnowledgeGraph,
-  options: ExportOptions = {},
-  fileContents?: Map<string, string>,
-  processingStats?: { duration: number }
-): string {
-  
-  // Metadata wrapper structure
-  if (includeMetadata) {
-    const metadata: ExportMetadata = {
-      exportedAt: includeTimestamp ? new Date().toISOString() : '',
-      version: '1.0.0',
-      nodeCount: graph.nodes.length,
-      relationshipCount: graph.relationships.length,
-      fileCount: fileContents?.size,
-      processingDuration: processingStats?.duration
-    };
-
-    exportData = {
-      metadata,
-      graph,  // CRITICAL: Raw graph object serialization
-      ...(fileContents && { fileContents: Object.fromEntries(fileContents) })
-    };
-  } else {
-    exportData = graph; // Direct graph serialization
-  }
-
-  return JSON.stringify(exportData, null, prettyPrint ? 2 : 0);
-  // STORAGE POINT 11 - JSON string generation
-}
-```
-
-**JSON Structure**:
-```json
-{
-  "metadata": {
-    "exportedAt": "2024-01-01T00:00:00.000Z",
-    "version": "1.0.0", 
-    "nodeCount": 1250,
-    "relationshipCount": 3400,
-    "fileCount": 45,
-    "processingDuration": 2500
-  },
-  "graph": {
-    "nodes": [
-      {
-        "id": "node_project_abc123",
-        "label": "Project",
-        "properties": {
-          "name": "MyProject",
-          "path": "/path/to/project",
-          "createdAt": "2024-01-01T00:00:00.000Z"
-        }
-      }
-      // ... more nodes
-    ],
-    "relationships": [
-      {
-        "id": "rel_contains_def456", 
-        "type": "CONTAINS",
-        "source": "node_project_abc123",
-        "target": "node_folder_ghi789",
-        "properties": {}
-      }
-      // ... more relationships
-    ]
-  },
-  "fileContents": {
-    "src/main.ts": "export function main() { ... }",
-    // ... more file contents
-  }
-}
-```
-
-### 3.2 Import Functions
-
-**Import Function** (Lines 411-443):
-```typescript
-export function importGraphFromJSON(jsonString: string): {
-  graph: KnowledgeGraph;
-  metadata?: ExportMetadata;
-  fileContents?: Map<string, string>;
-} {
-  try {
-    const parsed = JSON.parse(jsonString); // DESERIALIZATION POINT
-    
-    if (parsed.metadata && parsed.graph) {
-      // Handle wrapped format
-      const result = {
-        graph: parsed.graph, // Direct object assignment
-        metadata: parsed.metadata
-      };
-      
-      if (parsed.fileContents) {
-        result.fileContents = new Map(Object.entries(parsed.fileContents));
-        // Convert plain object back to Map
-      }
-      
-      return result;
-    }
-    
-    return { graph: parsed }; // Direct graph object
-  } catch (error) {
-    throw new Error(`Failed to import graph: ${error.message}`);
-  }
-}
-```
-
-### 3.3 Download Implementation
-
-**File Download** (Lines 182-207):
-```typescript
-export function downloadJSON(content: string, filename: string): void {
-  // Create blob with JSON content
-  const blob = new Blob([content], { type: 'application/json' });
-  
-  // Browser download mechanism
-  const url = URL.createObjectURL(blob);
-  const link = document.createElement('a');
-  link.href = url;
-  link.download = filename;
-  link.click(); // Triggers download - PERSISTENCE POINT
-}
-```
-
----
-
-## 4. Additional Storage Mechanisms
-
-### 4.1 LRU Cache Storage
-
-**Files**: 
-- `src/services/memory-manager.ts` (Memory management)
-- Various processor classes (Cache usage)
-
-**Purpose**: Caches parsed ASTs and query results for performance
-
-**Implementation Pattern**:
-```typescript
-// Cache key generation
-const cacheKey = this.lruCache.generateFileCacheKey(filePath, contentHash);
-
-// Cache retrieval
-const cachedResult = this.lruCache.getParsedFile(cacheKey);
-
-// Cache storage  
-this.lruCache.setParsedFile(cacheKey, parseResult); // STORAGE POINT 12
-```
-
-### 4.2 LocalStorage Usage
-
-**Settings Storage** (`src/config/feature-flags.ts`, Lines 104-110):
-```typescript
-private saveFlags(): void {
-  try {
-    localStorage.setItem('gitnexus_feature_flags', JSON.stringify(this.flags));
-    // STORAGE POINT 13 - Browser localStorage
-  } catch (error) {
-    console.warn('Failed to save feature flags to localStorage:', error);
-  }
-}
-```
-
-**Chat History** (`src/lib/chat-history.ts`, Lines 275-291):
-```typescript
-private saveSession(session: ChatSession): void {
-  try {
-    localStorage.setItem(this.storageKey, JSON.stringify(session));
-    // STORAGE POINT 14 - Chat persistence
-  } catch (error) {
-    // Handle quota exceeded errors
-  }
-}
-```
-
-### 4.3 IndexedDB (Planned for KuzuDB)
-
-**Current Status**: Implementation exists but not fully integrated
-**Files**: `src/core/kuzu/` directory contains KuzuDB integration code
-**Purpose**: Will replace JSON storage with embedded graph database
-
----
-
-## 5. Data Flow Summary
-
-```mermaid
-flowchart TD
-    START([Repository Input]) --> STRUCT[Structure Processor]
-    
-    STRUCT --> |Creates nodes/relationships| GRAPH1[In-Memory Graph]
-    
-    GRAPH1 --> PARSE[Parsing Processor]
-    PARSE --> |AST Storage| AST_MAP[AST Map]
-    PARSE --> |Function Registry| FUNC_TRIE[Function Trie]
-    PARSE --> |Adds definition nodes| GRAPH2[Enhanced Graph]
-    
-    GRAPH2 --> IMPORT[Import Processor]
-    AST_MAP --> IMPORT
-    IMPORT --> |Import Map| IMP_MAP[Import Map]
-    IMPORT --> |Adds IMPORTS relationships| GRAPH3[Graph + Imports]
-    
-    GRAPH3 --> CALLS[Call Processor]
-    AST_MAP --> CALLS
-    IMP_MAP --> CALLS
-    FUNC_TRIE --> CALLS
-    CALLS --> |Adds CALLS relationships| FINAL_GRAPH[Final Knowledge Graph]
-    
-    FINAL_GRAPH --> JSON_EXPORT[JSON Export]
-    JSON_EXPORT --> |JSON.stringify| JSON_STRING[JSON String]
-    JSON_STRING --> |Browser Download| FILE_SYSTEM[File System]
-    
-    FINAL_GRAPH --> |Direct object reference| UI[UI Components]
-    
-    subgraph "Storage Points"
-        GRAPH1
-        GRAPH2  
-        GRAPH3
-        FINAL_GRAPH
-        AST_MAP
-        FUNC_TRIE
-        IMP_MAP
-        JSON_STRING
-    end
-    
-    subgraph "Cache Layer"
-        LRU_CACHE[LRU Cache]
-        LOCAL_STORAGE[LocalStorage]
-    end
-    
-    PARSE -.-> LRU_CACHE
-    LOCAL_STORAGE -.-> SETTINGS[Settings/Flags]
-```
-
----
-
-## 6. Critical Migration Points for Kuzu DB
-
-### 6.1 Schema Mapping Requirements
-
-**Current JSON Structure → Kuzu Schema**:
-
-1. **Nodes Table**:
-   ```sql
-   CREATE NODE TABLE IF NOT EXISTS nodes (
-     id STRING PRIMARY KEY,
-     label STRING NOT NULL,
-     properties MAP(STRING, STRING)
-   );
-   ```
-
-2. **Relationships Table**:
-   ```sql
-   CREATE REL TABLE IF NOT EXISTS relationships (
-     FROM nodes TO nodes,
-     id STRING,
-     type STRING NOT NULL, 
-     properties MAP(STRING, STRING)
-   );
-   ```
-
-### 6.2 Data Transformation Points
-
-**Every `graph.addNode()` call** → **Kuzu INSERT statement**
-**Every `graph.addRelationship()` call** → **Kuzu MATCH/CREATE statement**
-
-### 6.3 Query Transformation Requirements
-
-**Current**: Linear array searches in `SimpleKnowledgeGraph`
-**Target**: Cypher queries in KuzuDB
-
-**Example Transformations**:
-```typescript
-// Current: Find nodes by label
-graph.nodes.filter(n => n.label === 'Function')
-
-// Target: Cypher query
-MATCH (n:Function) RETURN n
-```
-
-### 6.4 Persistence Layer Changes
-
-**Current Flow**:
-1. Build `SimpleKnowledgeGraph` in memory
-2. Export to JSON string
-3. Download as file
-
-**Target Flow**:
-1. Stream data directly to KuzuDB during processing
-2. Persist to IndexedDB automatically
-3. Export via Cypher queries
-
----
-
-## 7. Implementation Recommendations
-
-### 7.1 Migration Strategy
-
-1. **Phase 1**: Create parallel KuzuDB storage alongside existing JSON
-2. **Phase 2**: Implement streaming ingestion (write to Kuzu during pipeline)
-3. **Phase 3**: Replace SimpleKnowledgeGraph with KuzuDB queries
-4. **Phase 4**: Remove JSON export/import (keep as backup option)
-
-### 7.2 Critical Considerations
-
-1. **Referential Integrity**: Kuzu enforces relationships, JSON doesn't
-2. **Transaction Boundaries**: Kuzu needs explicit transactions
-3. **Query Performance**: Index strategy for common access patterns
-4. **Memory Management**: Kuzu handles memory, current system uses manual arrays
-5. **Concurrent Access**: Kuzu supports concurrent reads, current system is single-threaded
-
-### 7.3 Testing Strategy
-
-1. **Data Integrity**: Compare JSON export with Kuzu export for identical results
-2. **Performance**: Benchmark ingestion and query performance
-3. **Memory Usage**: Monitor memory consumption during large repository processing
-4. **Error Handling**: Test transaction rollback and recovery scenarios
-
----
-
-## Conclusion
-
-This document provides the complete technical foundation for migrating GitNexus from JSON-based storage to KuzuDB. Every storage point, data transformation, and persistence mechanism has been identified and documented. The migration should focus on replacing the `SimpleKnowledgeGraph` implementation while maintaining the exact same data structures and relationships in the new KuzuDB schema.

PHASE_2_IMPLEMENTATION_SUMMARY.md

@@ -1,253 +0,0 @@
-# Phase 2: Parallel Storage Implementation - Complete! 🎉
-
-## Overview
-
-Successfully implemented the **Parallel Storage** phase of the KuzuDB migration plan, enabling dual-write functionality where data is written to both JSON (primary) and KuzuDB (secondary) storage systems simultaneously.
-
-## ✅ **Components Implemented**
-
-### 1. **KuzuProcessorBase** (`src/core/ingestion/kuzu-processor-base.ts`)
-
-**Core Features:**
-- **Dual-Write Pattern**: Seamless writes to both JSON and KuzuDB
-- **Transaction Management**: Begin, commit, and rollback transaction support
-- **Error Handling**: Graceful degradation when KuzuDB fails
-- **Performance Monitoring**: Detailed statistics and timing metrics
-- **Data Validation**: Consistency checks between storage systems
-- **Feature Flag Integration**: Respects `isKuzuDBEnabled()` settings
-
-**Key Methods:**
-- `addNodeDualWrite()` - Writes nodes to both storages
-- `addRelationshipDualWrite()` - Writes relationships to both storages
-- `beginTransaction()` / `commitTransaction()` / `rollbackTransaction()`
-- `initializeKuzuDB()` - Sets up KuzuDB connection
-- `validateNodeConsistency()` / `validateRelationshipConsistency()`
-
-### 2. **Enhanced StructureProcessor** 
-
-**Modifications:**
-- ✅ Extends `KuzuProcessorBase` for dual-write capability
-- ✅ Async `process()` method with KuzuDB initialization
-- ✅ Dual-write support for Project, Folder, and File nodes
-- ✅ Dual-write support for CONTAINS relationships
-- ✅ Transaction boundaries with commit/rollback
-- ✅ Comprehensive error handling and statistics
-
-**Dual-Write Flow:**
-1. Initialize KuzuDB connection
-2. Create project node → write to JSON + KuzuDB
-3. Create directory nodes → write to JSON + KuzuDB  
-4. Create file nodes → write to JSON + KuzuDB
-5. Create CONTAINS relationships → write to JSON + KuzuDB
-6. Commit KuzuDB transaction
-7. Log detailed statistics
-
-### 3. **Enhanced ParsingProcessor**
-
-**Modifications:**
-- ✅ Extends `KuzuProcessorBase` for dual-write capability
-- ✅ Async definition processing with KuzuDB writes
-- ✅ Dual-write support for Function, Class, Method, Variable, Interface, Type nodes
-- ✅ Dual-write support for INHERITS, IMPLEMENTS, IMPORTS relationships
-- ✅ Transaction boundaries with automatic commit
-- ✅ Batch processing optimization
-
-**Dual-Write Flow:**
-1. Initialize KuzuDB connection
-2. Process each file's definitions
-3. Create definition nodes → write to JSON + KuzuDB
-4. Create containment relationships → write to JSON + KuzuDB
-5. Create inheritance/implementation relationships → write to JSON + KuzuDB
-6. Commit KuzuDB transaction
-7. Log processing statistics
-
-### 4. **Enhanced ImportProcessor**
-
-**Modifications:**
-- ✅ Extends `KuzuProcessorBase` for dual-write capability
-- ✅ Async import relationship creation
-- ✅ Dual-write support for IMPORTS relationships
-- ✅ Transaction management with rollback support
-- ✅ Enhanced error handling and progress tracking
-
-**Dual-Write Flow:**
-1. Initialize KuzuDB connection
-2. Process imports for each file
-3. Create IMPORTS relationships → write to JSON + KuzuDB
-4. Commit KuzuDB transaction
-5. Log import resolution statistics
-
-### 5. **Enhanced CallProcessor**
-
-**Modifications:**
-- ✅ Extends `KuzuProcessorBase` for dual-write capability
-- ✅ Async call relationship creation
-- ✅ Dual-write support for CALLS relationships
-- ✅ 3-stage resolution strategy maintained
-- ✅ Transaction boundaries and error handling
-
-**Dual-Write Flow:**
-1. Initialize KuzuDB connection
-2. Extract function calls from AST
-3. Resolve calls using 3-stage strategy
-4. Create CALLS relationships → write to JSON + KuzuDB
-5. Commit KuzuDB transaction
-6. Log call resolution statistics
-
-## 🏗️ **Architecture Highlights**
-
-### **Dual-Write Pattern Implementation**
-```typescript
-// JSON write (primary - always succeeds)
-jsonGraph.addNode(node);
-
-// KuzuDB write (secondary - graceful failure)
-if (this.kuzuGraph) {
-  try {
-    this.kuzuGraph.addNode(node);
-  } catch (kuzuError) {
-    console.warn('KuzuDB write failed:', kuzuError);
-    // Continue processing - JSON is primary storage
-  }
-}
-```
-
-### **Transaction Management**
-```typescript
-// Begin transaction
-await this.beginTransaction();
-
-try {
-  // Perform operations
-  await this.addNodeDualWrite(graph, node);
-  await this.addRelationshipDualWrite(graph, relationship);
-  
-  // Commit transaction
-  await this.commitTransaction();
-} catch (error) {
-  // Rollback on failure
-  await this.rollbackTransaction();
-  throw error;
-}
-```
-
-### **Statistics and Monitoring**
-- **Nodes processed**: Total nodes written to JSON
-- **KuzuDB nodes written**: Successful KuzuDB writes
-- **KuzuDB errors**: Failed KuzuDB operations
-- **Success rate**: Percentage of successful dual-writes
-- **Processing time**: Total time spent on operations
-- **Validation errors**: Data consistency issues detected
-
-## 📊 **Key Benefits Achieved**
-
-### **1. Zero Breaking Changes**
-- All existing processors maintain their original interfaces
-- JSON storage remains primary - system continues working even if KuzuDB fails
-- Backward compatibility with all existing code
-
-### **2. Production-Ready Error Handling**
-- KuzuDB failures don't break the ingestion pipeline
-- Graceful degradation to JSON-only mode
-- Comprehensive error logging and categorization
-- Transaction rollback on critical failures
-
-### **3. Performance Optimization**
-- Batch processing for optimal KuzuDB performance
-- Async operations with proper error boundaries
-- Transaction boundaries reduce database overhead
-- Detailed performance monitoring and statistics
-
-### **4. Data Consistency**
-- Dual-write ensures both storages have the same data
-- Transaction management prevents partial writes
-- Validation hooks for consistency checking
-- Rollback capabilities for data integrity
-
-### **5. Feature Flag Integration**
-- Respects `isKuzuDBEnabled()` configuration
-- Can be enabled/disabled without code changes
-- Gradual rollout capabilities
-- A/B testing support
-
-## 🔄 **Integration Points**
-
-### **Pipeline Integration**
-All processors now support the enhanced dual-write pattern:
-
-```typescript
-// Structure Phase
-const structureProcessor = new StructureProcessor({ enableKuzuDB: true });
-await structureProcessor.process(graph, structureInput);
-
-// Parsing Phase  
-const parsingProcessor = new ParsingProcessor({ enableKuzuDB: true });
-await parsingProcessor.process(graph, parsingInput);
-
-// Import Phase
-const importProcessor = new ImportProcessor({ enableKuzuDB: true });
-await importProcessor.process(graph, astMap, fileContents);
-
-// Call Phase
-const callProcessor = new CallProcessor(functionTrie, { enableKuzuDB: true });
-await callProcessor.process(graph, astMap, importMap);
-```
-
-### **Configuration Options**
-```typescript
-interface KuzuProcessorOptions {
-  enableKuzuDB?: boolean;        // Enable/disable KuzuDB integration
-  batchSize?: number;            // Batch size for optimal performance
-  autoCommit?: boolean;          // Automatic transaction commits
-  enableValidation?: boolean;    // Data consistency validation
-}
-```
-
-## 📈 **Performance Expectations**
-
-### **Memory Usage**
-- Minimal additional memory overhead (~5-10%)
-- Transaction batching prevents memory bloat
-- Graceful handling of large codebases
-
-### **Processing Time**
-- Expected 10-20% increase in processing time
-- Batch operations optimize KuzuDB performance
-- Async operations prevent blocking
-
-### **Error Resilience**
-- 100% reliability for JSON storage (primary)
-- Graceful degradation for KuzuDB failures
-- No data loss even with KuzuDB issues
-
-## 🚀 **Ready for Phase 3**
-
-The parallel storage implementation provides a solid foundation for **Phase 3: Query Migration**, where we'll:
-
-1. **Implement Query Abstraction Layer**: Create unified query interface
-2. **Add Query Routing Logic**: Route queries to appropriate storage
-3. **Performance Comparison Tools**: A/B test JSON vs KuzuDB queries
-4. **Query Result Validation**: Ensure consistent results between storages
-
-## 📁 **Files Modified/Created**
-
-### **New Files**
-- `src/core/ingestion/kuzu-processor-base.ts` - Base class for dual-write pattern
-
-### **Modified Files**
-- `src/core/ingestion/structure-processor.ts` - Added KuzuDB dual-write support
-- `src/core/ingestion/parsing-processor.ts` - Added KuzuDB dual-write support  
-- `src/core/ingestion/import-processor.ts` - Added KuzuDB dual-write support
-- `src/core/ingestion/call-processor.ts` - Added KuzuDB dual-write support
-
-## 🎯 **Success Metrics**
-
-- ✅ **100% Backward Compatibility**: All existing functionality preserved
-- ✅ **Graceful Error Handling**: KuzuDB failures don't break the system
-- ✅ **Transaction Safety**: Data integrity maintained with rollback support
-- ✅ **Performance Monitoring**: Comprehensive statistics and metrics
-- ✅ **Feature Flag Ready**: Can be enabled/disabled via configuration
-- ✅ **Production Quality**: Error handling, logging, and monitoring
-
-The dual-write pattern is now fully implemented and ready for production deployment! 🚀
-

README.md

@@ -1,359 +1,539 @@
-# GitNexus - Fully Client sided Knowledge Graph Generator and Graph RAG Agent
+# 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.
+
+<div align="center">
+
+  <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>
+
+  <h2>Join the official Discord to discuss ideas, issues etc!</h2>
+
+  <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>
+
+</div>
+
+**Building nervous system for agent context.**
+
+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.
 
 
-GitNexus is a privacy-focused, zero-server knowledge graph generator that runs entirely in your browser. It transforms codebases into interactive knowledge graphs using advanced AST parsing, multi-threaded Web Workers, and an embedded KuzuDB WASM database. Features a Graph RAG agent for intelligent code exploration through natural language queries using cypher queries executed directly against the in-browser graph database.
-
-https://github.com/user-attachments/assets/6f13bd45-d6e9-4f4e-a360-ceb66f41c741
-
-## Current Work in Progress:
-
-- Ollama support
-- Export as csv ( for both node and relation table )
 
 
-## Features
+https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
-**Code Analysis**
 
-- Analyze GitHub repositories or ZIP files
-- Support for TypeScript, JavaScript, Python
-- Interactive graph visualization with D3.js
-- File filtering and directory selection
-- Export results as JSON/CSV
 
-**AI Chat**
+> *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
 
-- Multiple LLM providers (OpenAI, Anthropic, Gemini, Azure)
-- Query code structure and relationships
-- Context-aware conversations
-- Graph-based code search
+**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.
 
-**Processing**
+---
 
-- Four-pass analysis: structure → parsing → imports → calls
-- Parallel processing with Web Workers
-- AST-based code extraction using Tree-sitter
-- Memory-efficient caching
+## Star History
 
-## Architecture
+[![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)
 
-```mermaid
-graph TB
-    UI[React UI Layer] --> EM[Engine Manager]
-    EM --> LEG[Legacy Engine]
-    EM --> NG[Next-Gen Engine - WIP]
-  
-    subgraph "Legacy Engine (Production Ready)"
-        LEG --> GP[Sequential Pipeline]
-        GP --> SP[Single-threaded Parser]
-        GP --> MEM[In-Memory Graph Store]
-        MEM --> JSON[JSON Export]
-    end
-  
-    subgraph "Next-Gen Engine (Work in Progress)"
-        NG --> PP[Parallel Pipeline]
-        PP --> WP[Web Worker Pool]
-        PP --> KDB[KuzuDB WASM]
-        KDB --> CYP[Cypher Queries]
-        CYP --> RAG[Graph RAG Agent - WIP]
-    end
-  
-    subgraph "Core Technologies"
-        TS[Tree-sitter WASM]
-        D3[D3.js Force Simulation]
-        LC[LangChain ReAct Agents]
-        IDB[IndexedDB Persistence]
-    end
+
+## 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, Codex | 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** | LadybugDB native (fast, persistent)                               | LadybugDB 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
 ```
 
-**Tech Stack**:
+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.
 
-- **Frontend**: React 18 + TypeScript + Vite + D3.js force simulation
-- **Parsing**: Tree-sitter WASM parsers (TypeScript, JavaScript, Python)
-- **Concurrency**: Web Worker Pool with Comlink for thread-safe communication
-- **Caching**: LRU-based AST cache with memory management and eviction policies
-- **AI**: LangChain.js ReAct agents with tool-augmented reasoning
-- **Database**: KuzuDB WASM integration (WIP) + IndexedDB persistence
-- **Graph RAG**: Cypher query generation for knowledge graph reasoning (WIP)
+To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-## Four-Pass Ingestion Pipeline
+### 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   |
+| **Codex**       | Yes | —     | —                   | MCP            |
+
+> **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"]
+    }
+  }
+}
+```
+
+**Codex** (`~/.codex/config.toml` for system scope, or `.codex/config.toml` for project scope):
+
+```toml
+[mcp_servers.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 --skills         # Generate repo-specific skill files from detected communities
+gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
+gitnexus analyze --embeddings     # Enable embedding generation (slower, better search)
+gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start local HTTP server (multi-repo) for web UI 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
+
+**Repo-specific skills** generated with `--skills`:
+
+When you run `gitnexus analyze --skills`, GitNexus detects the functional areas of your codebase (via Leiden community detection) and generates a `SKILL.md` file for each one under `.claude/skills/generated/`. Each skill describes a module's key files, entry points, execution flows, and cross-area connections — so your AI agent gets targeted context for the exact area of code you're working in. Skills are regenerated on each `--skills` run to stay current with the codebase.
+
+---
+
+## 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
-    START([Repository Input]) --> PASS1
-  
-    subgraph PASS1 ["Pass 1: Structure Analysis"]
-        P1A[Recursive Directory Traversal] --> P1B[File Type Classification]
-        P1B --> P1C[Project/Folder/File Nodes]
-        P1C --> P1D[CONTAINS Relationships]
+    subgraph CLI [CLI Commands]
+        Setup["gitnexus setup"]
+        Analyze["gitnexus analyze"]
+        Clean["gitnexus clean"]
+        List["gitnexus list"]
     end
-  
-    subgraph PASS2 ["Pass 2: Code Parsing & AST"]
-        P2A[Tree-sitter WASM Init] --> P2B[Grammar Loading]
-        P2B --> P2C[AST Generation]
-        P2C --> P2D[Symbol Extraction]
-        P2D --> P2E[LRU Cache Storage]
+
+    subgraph Registry ["~/.gitnexus/"]
+        RegFile["registry.json"]
     end
-  
-    subgraph PASS3 ["Pass 3: Import Resolution"]
-        P3A[Import Statement Extraction] --> P3B[Module Path Resolution]
-        P3B --> P3C[Cross-Reference Tables]
-        P3C --> P3D[IMPORTS Relationships]
+
+    subgraph Repos [Project Repos]
+        RepoA[".gitnexus/ in repo A"]
+        RepoB[".gitnexus/ in repo B"]
     end
-  
-    subgraph PASS4 ["Pass 4: Call Graph Analysis"]
-        P4A[Function Call Pattern Matching] --> P4B[Exact Match via Import Map]
-        P4B --> P4C[Fuzzy Match + Levenshtein]
-        P4C --> P4D[CALLS Relationships]
+
+    subgraph MCP [MCP Server]
+        Server["server.ts"]
+        Backend["LocalBackend"]
+        Pool["Connection Pool"]
+        ConnA["LadybugDB conn A"]
+        ConnB["LadybugDB conn B"]
     end
-  
-    PASS1 --> PASS2
-    PASS2 --> PASS3
-    PASS3 --> PASS4
-    PASS4 --> END([Knowledge Graph])
-  
-    classDef passBox fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
-    classDef startEnd fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px,color:#000
-    classDef step fill:#fff3e0,stroke:#ef6c00,stroke-width:1px,color:#000
-  
-    class PASS1,PASS2,PASS3,PASS4 passBox
-    class START,END startEnd
-    class P1A,P1B,P1C,P1D,P2A,P2B,P2C,P2D,P2E,P3A,P3B,P3C,P3D,P4A,P4B,P4C,P4D step
+
+    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
 ```
 
-### Data Flow & Storage Architecture
+**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. LadybugDB 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.
 
-```mermaid
-flowchart TD
-    START([Repository Input]) --> STRUCT[Structure Processor]
-    
-    STRUCT --> |Creates nodes/relationships| GRAPH1[In-Memory Graph]
-    
-    GRAPH1 --> PARSE[Parsing Processor]
-    PARSE --> |AST Storage| AST_MAP[AST Map]
-    PARSE --> |Function Registry| FUNC_TRIE[Function Trie]
-    PARSE --> |Adds definition nodes| GRAPH2[Enhanced Graph]
-    
-    GRAPH2 --> IMPORT[Import Processor]
-    AST_MAP --> IMPORT
-    IMPORT --> |Import Map| IMP_MAP[Import Map]
-    IMPORT --> |Adds IMPORTS relationships| GRAPH3[Graph + Imports]
-    
-    GRAPH3 --> CALLS[Call Processor]
-    AST_MAP --> CALLS
-    IMP_MAP --> CALLS
-    FUNC_TRIE --> CALLS
-    CALLS --> |Adds CALLS relationships| FINAL_GRAPH[Final Knowledge Graph]
-    
-    FINAL_GRAPH --> JSON_EXPORT[JSON Export]
-    JSON_EXPORT --> |JSON.stringify| JSON_STRING[JSON String]
-    JSON_STRING --> |Browser Download| FILE_SYSTEM[File System]
-    
-    FINAL_GRAPH --> |Direct object reference| UI[UI Components]
-    
-    subgraph "Storage Points"
-        GRAPH1
-        GRAPH2  
-        GRAPH3
-        FINAL_GRAPH
-        AST_MAP
-        FUNC_TRIE
-        IMP_MAP
-        JSON_STRING
-    end
-    
-    subgraph "Cache Layer"
-        LRU_CACHE[LRU Cache]
-        LOCAL_STORAGE[LocalStorage]
-    end
-    
-    PARSE -.-> LRU_CACHE
-    LOCAL_STORAGE -.-> SETTINGS[Settings/Flags]
-```
+---
 
-### Technical Implementation Details
+## Web UI (browser-based)
 
-**Pass 1: Structure Analysis**
+A fully client-side graph explorer and AI chat. No server, no install — your code never leaves the browser.
 
-- Implements recursive directory traversal with configurable depth limits
-- File type detection using MIME types and extension mapping
-- Creates hierarchical node structure with parent-child relationships
-- Establishes CONTAINS relationships for project organization
+**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — drag & drop a ZIP and start exploring.
 
-**Pass 2: Code Parsing & AST Extraction**
+<img width="2550" height="1343" alt="gitnexus_img" src="https://github.com/user-attachments/assets/cc5d637d-e0e5-48e6-93ff-5bcfdb929285" />
 
-- Initializes Tree-sitter WASM parsers with language-specific grammars
-- Generates Abstract Syntax Trees for each source file
-- Implements AST traversal algorithms to extract code symbols
-- **LRU Cache System**: Memory-efficient AST storage with configurable eviction policies
-- **Parallel Processing**: Web Worker Pool distributes parsing across multiple threads
-- **Memory Management**: Automatic cleanup and garbage collection for large codebases
-
-**Pass 3: Import Resolution**
-
-- Extracts import/require statements using AST pattern matching
-- Implements module resolution algorithms (Node.js, ES6, Python)
-- Builds cross-reference tables for dependency mapping
-- Handles relative/absolute path resolution with fallback strategies
-
-**Pass 4: Call Graph Analysis**
-
-- **Stage 1**: Exact function call matching using import resolution data
-- **Stage 2**: Fuzzy matching with Levenshtein distance for unresolved calls
-- **Stage 3**: Heuristic-based matching for dynamic calls and method chaining
-- Creates CALLS relationships with confidence scoring
-
-## Getting Started
-
-**Prerequisites**: Node.js 18+, API keys for AI features
+Or run locally:
 
 ```bash
-   git clone <repository-url>
-   cd gitnexus
-   npm install
-   npm run dev
+git clone https://github.com/abhigyanpatwari/gitnexus.git
+cd gitnexus/gitnexus-web
+npm install
+npm run dev
 ```
 
-Open http://localhost:5173
+The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.
 
-**Configuration**
+**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.
 
-- GitHub token (optional): Increases rate limit to 5,000/hour
-- AI API keys: OpenAI, Anthropic, Gemini, or Azure OpenAI
-- Performance: Set file limits and directory filters
+---
 
-## Usage
+## The Problem GitNexus Solves
 
-**Analyze Repository**
+Tools like **Cursor**, **Claude Code**, **Cline**, **Roo Code**, and **Windsurf** are powerful — but they don't truly know your codebase structure.
 
-1. Enter GitHub URL or upload ZIP file
-2. Set filters (optional): directories, file patterns, size limits
-3. Click "Analyze" and wait for processing
-4. Explore the interactive graph
+**What happens:**
 
-**AI Chat**
+1. AI edits `UserService.validate()`
+2. Doesn't know 47 functions depend on its return type
+3. **Breaking changes ship**
 
-1. Configure API key in settings
-2. Ask questions about the codebase:
-   - "What functions are in main.py?"
-   - "Show classes that inherit from BaseClass"
-   - "How does authentication work?"
+### Traditional Graph RAG vs GitNexus
 
-**Export Data**
-
-- Click Export button to download graph as JSON/CSV
-
-## Advanced Features & Work in Progress
-
-### Web Worker Pool Architecture
+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
-graph LR
-    MT[Main Thread] --> WM[Worker Manager]
-    WM --> W1[Worker 1<br/>Tree-sitter Parser]
-    WM --> W2[Worker 2<br/>Tree-sitter Parser]
-    WM --> W3[Worker N<br/>Tree-sitter Parser]
-  
-    W1 --> AST1[AST Cache]
-    W2 --> AST2[AST Cache]
-    W3 --> AST3[AST Cache]
-  
-    AST1 --> LRU[LRU Eviction Policy]
-    AST2 --> LRU
-    AST3 --> LRU
-```
+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
 
-### LRU Cache Implementation
-
-- **Memory-bounded AST storage** with configurable size limits (default: 1000 entries)
-- **Automatic eviction policies** based on access patterns and memory pressure
-- **Thread-safe operations** across Web Worker boundaries using Comlink
-- **Cache hit optimization** for repeated file analysis and import resolution
-- **Garbage collection integration** with browser memory management APIs
-
-### KuzuDB Integration Status (Work in Progress)
-
-```mermaid
-graph TD
-    APP[Application Layer] --> RAG[Graph RAG Agent]
-    RAG --> CYP[Cypher Query Generator]
-    CYP --> KDB[KuzuDB WASM Engine]
-    KDB --> IDB[IndexedDB Persistence]
-  
-    subgraph STATUS ["Current Status"]
-        IMPL[KuzuDB WASM Integration - Complete]
-        PERS[IndexedDB Persistence - Complete]
-        SCHEMA[Graph Schema Definition - Complete]
-        QUERY[Cypher Query Execution - WIP]
-        AGENT[Graph RAG Agent - WIP]
+    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
-  
-    classDef complete fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
-    classDef wip fill:#fff3e0,stroke:#f57c00,stroke-width:2px
-    classDef main fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
-  
-    class IMPL,PERS,SCHEMA complete
-    class QUERY,AGENT wip
-    class APP,RAG,CYP,KDB,IDB main
 ```
 
-**Implementation Status**:
+**Core innovation: Precomputed Relational Intelligence**
 
-- ✅ **KuzuDB WASM Engine**: Fully integrated embedded graph database
-- ✅ **Graph Schema**: Node and relationship type definitions implemented
-- ✅ **Data Ingestion**: Knowledge graph storage in KuzuDB format
-- 🚧 **Cypher Query Engine**: Query execution layer under development
-- 🚧 **Graph RAG Agent**: AI agent with graph querying capabilities (blocked by Cypher integration)
+- **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
 
-**Current Limitation**: The Graph RAG agent cannot execute sophisticated graph queries because the Cypher query execution layer is still being implemented. Basic AI chat works with in-memory graph traversal, but advanced graph reasoning requires the KuzuDB Cypher integration to be completed.
+---
 
-### Dual-Engine Architecture
+## How It Works
 
-- **Legacy Engine**: Production-ready single-threaded processing with JSON storage
-- **Next-Gen Engine**: Parallel processing with KuzuDB persistence (4-8x performance improvement)
-- **Automatic Fallback**: System gracefully degrades to legacy engine if next-gen fails
-- **Runtime Switching**: Users can toggle between engines without data loss
+GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
 
-## Deployment
+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, function calls, heritage, constructor inference, and `self`/`this` receiver types 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
+
+### Supported Languages
+
+| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
+|----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------|
+| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
+| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
+| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
+| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+
+**Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics
+
+---
+
+## Tool Examples
+
+### Impact Analysis
+
+```
+impact({target: "UserService", direction: "upstream", minConfidence: 0.8})
+
+TARGET: Class UserService (src/services/user.ts)
+
+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
+```
+
+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
+```
+
+### Context (360-degree Symbol View)
+
+```
+context({name: "validateUser"})
+
+symbol:
+  uid: "Function:validateUser"
+  kind: Function
+  filePath: src/auth/validate.ts
+  startLine: 15
+
+incoming:
+  calls: [handleLogin, handleRegister, UserController]
+  imports: [authRouter]
+
+outgoing:
+  calls: [checkPassword, createSession]
+
+processes:
+  - name: LoginFlow (step 2/7)
+  - name: RegistrationFlow (step 3/5)
+```
+
+### 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, ...]
+```
+
+### Rename (Multi-File)
+
+```
+rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})
+
+status: success
+files_affected: 5
+total_edits: 8
+graph_edits: 6     (high confidence)
+text_search_edits: 2  (review carefully)
+changes: [...]
+```
+
+### Cypher Queries
+
+```cypher
+-- 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
+```
+
+---
+
+## Wiki Generation
+
+Generate LLM-powered documentation from your knowledge graph:
 
 ```bash
-npm run build
-npm run preview
+# 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
 ```
 
-**Environment Variables**
+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.
 
-```env
-VITE_OPENAI_API_KEY=sk-...
-VITE_DEFAULT_MAX_FILES=500
-VITE_ENABLE_DEBUG_LOGGING=false
-```
+---
+
+## Tech Stack
+
+| Layer                     | CLI                                   | Web                                     |
+| ------------------------- | ------------------------------------- | --------------------------------------- |
+| **Runtime**         | Node.js (native)                      | Browser (WASM)                          |
+| **Parsing**         | Tree-sitter native bindings           | Tree-sitter WASM                        |
+| **Database**        | LadybugDB native                         | LadybugDB 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
+
+### Actively Building
+
+- [ ] **LLM Cluster Enrichment** — Semantic cluster names via LLM API
+- [ ] **AST Decorator Detection** — Parse @Controller, @Get, etc.
+- [ ] **Incremental Indexing** — Only re-index changed files
+
+### Recently Completed
+
+- [X] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
+- [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, 13 Language Support
+- [X] Community Detection, Process Detection, Confidence Scoring
+- [X] Hybrid Search, Vector Index
+
+---
 
 ## Security & Privacy
 
-- All processing happens in your browser
-- API keys stored locally, never transmitted
-- No code or results stored remotely
-- Uses GitHub public API only
+- **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.
 
-## Contributing
-
-1. Fork the repository
-2. Create feature branch: `git checkout -b feature/name`
-3. Make changes and test
-4. Commit: `git commit -m 'Add feature'`
-5. Push and open Pull Request
-
-**Code Style**: TypeScript strict mode, ESLint rules, minimal comments
-
-## License
-
-MIT License - see [LICENSE](LICENSE) file
+---
 
 ## Acknowledgments
 
-- Tree-sitter for syntax parsing
-- LangChain.js for AI agents
-- D3.js for graph visualization
-- KuzuDB for embedded database
-- [code-graph-rag](https://github.com/vitali87/code-graph-rag) for reference implementation
+- [Tree-sitter](https://tree-sitter.github.io/) — AST parsing
+- [LadybugDB](https://ladybugdb.com/) — Embedded graph database with vector support (formerly KuzuDB)
+- [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

WORKER_POOL_IMPLEMENTATION_SUMMARY.md

@@ -1,375 +0,0 @@
-# Worker Pool Implementation Summary for Byterover
-
-## 🎯 Project Context
-**Project**: GitNexus - Client-side, edge-based code knowledge graph generator
-**Implementation Date**: December 2024
-**Primary Goal**: Massive performance improvement for large codebases through parallel processing
-
-## 🚀 Performance Benefits Achieved
-
-### **Expected Speedup by Codebase Size:**
-- **Small codebases (< 100 files)**: 1.5-2x speedup
-- **Medium codebases (100-1000 files)**: 2-4x speedup  
-- **Large codebases (1000+ files)**: 4-8x speedup
-
-### **Key Performance Improvements:**
-- **Parallel file parsing** - Multiple files processed simultaneously
-- **Concurrent Tree-sitter operations** - AST generation in parallel
-- **Better CPU utilization** - Leverages all available cores
-- **Improved UI responsiveness** - Main thread freed up
-
-## 📁 Files Created/Modified
-
-### **Core Implementation Files:**
-
-#### 1. `src/lib/web-worker-pool.ts` (NEW)
-**Purpose**: Browser-compatible Web Worker Pool implementation
-**Key Features**:
-- Replaces Node.js `worker_threads` with standard Web Workers
-- Manages worker lifecycle, task queuing, and error handling
-- Supports progress tracking and batch processing
-- Includes `FileProcessingPool` and `WebWorkerPoolUtils`
-
-**Critical Code Patterns**:
-```typescript
-export class WebWorkerPool {
-  private workers: Worker[] = [];
-  private availableWorkers: Worker[] = [];
-  private taskQueue: WorkerTask<unknown, unknown>[] = [];
-  private activeTasks: Map<string, WorkerTask<unknown, unknown>> = new Map();
-  
-  async execute<TInput, TOutput>(input: TInput): Promise<TOutput>
-  async executeWithProgress<TInput, TOutput>(inputs: TInput[], onProgress?: (completed: number, total: number) => void): Promise<TOutput[]>
-  async shutdown(): Promise<void>
-}
-```
-
-#### 2. `src/core/ingestion/parallel-parsing-processor.ts` (NEW)
-**Purpose**: Parallel file parsing using worker pool
-**Key Features**:
-- Replaces sequential `ParsingProcessor`
-- Uses `tree-sitter-worker.js` for parallel AST parsing
-- Integrates with `FunctionRegistryTrie` for optimized lookups
-- Handles worker pool initialization and cleanup
-
-**Critical Code Patterns**:
-```typescript
-export class ParallelParsingProcessor implements GraphProcessor<ParsingInput> {
-  private workerPool: WebWorkerPool;
-  
-  async process(graph: KnowledgeGraph, input: ParsingInput): Promise<void>
-  private async processFilesInParallel(filePaths: string[], fileContents: Map<string, string>): Promise<ParallelParsingResult[]>
-  private async processResults(results: ParallelParsingResult[], graph: KnowledgeGraph): Promise<void>
-}
-```
-
-#### 3. `src/core/ingestion/parallel-pipeline.ts` (NEW)
-**Purpose**: Parallel 4-pass ingestion pipeline
-**Key Features**:
-- Replaces original `GraphPipeline`
-- Integrates `ParallelParsingProcessor` for Pass 2
-- Provides progress callbacks and performance logging
-- Ensures proper worker resource cleanup
-
-**Critical Code Patterns**:
-```typescript
-export class ParallelGraphPipeline {
-  private parsingProcessor: ParallelParsingProcessor;
-  
-  public async run(input: PipelineInput): Promise<KnowledgeGraph>
-  public static isParallelProcessingSupported(): boolean
-  public static getOptimalWorkerCount(): number
-}
-```
-
-### **Worker Scripts:**
-
-#### 4. `public/workers/tree-sitter-worker.js` (NEW)
-**Purpose**: Dedicated Tree-sitter parsing worker
-**Key Features**:
-- Initializes Tree-sitter and language parsers in worker context
-- Supports TypeScript, JavaScript, Python parsing
-- Extracts definitions using Tree-sitter queries
-- Communicates results back to main thread
-
-#### 5. `public/workers/generic-worker.js` (NEW)
-**Purpose**: General-purpose processing worker
-**Key Features**:
-- Text analysis (word count, identifier extraction)
-- File analysis (basic stats, language detection)
-- Data processing (deduplication, filtering, transformation)
-- Pattern matching and statistical analysis
-
-#### 6. `public/workers/file-processing-worker.js` (NEW)
-**Purpose**: Specialized file processing worker
-**Key Features**:
-- Leverages tree-sitter worker for parsing
-- File structure analysis
-- Dependency extraction (ES6 imports, CommonJS requires)
-- Code complexity analysis
-
-### **Configuration & Testing:**
-
-#### 7. `src/config/feature-flags.ts` (MODIFIED)
-**Changes**: Added worker pool feature flags
-```typescript
-// New flags added:
-enableWorkerPool: boolean;
-enableParallelParsing: boolean;
-enableParallelProcessing: boolean;
-
-// New methods:
-enableWorkerPool(): void
-disableWorkerPool(): void
-```
-
-#### 8. `src/lib/worker-pool-test.ts` (NEW)
-**Purpose**: Comprehensive test suite
-**Key Features**:
-- Basic functionality tests
-- File processing tests
-- Performance benchmarking
-- Error handling tests
-- Browser console testing support
-
-#### 9. `WORKER_POOL_IMPLEMENTATION_GUIDE.md` (NEW)
-**Purpose**: Complete documentation
-**Contents**:
-- Performance benefits and benchmarks
-- File structure and architecture
-- Usage examples and configuration
-- Testing instructions
-- Migration guide from sequential to parallel
-
-## 🔧 Technical Architecture
-
-### **Worker Pool Design Pattern:**
-```typescript
-// Worker Pool Lifecycle
-1. Initialize pool with optimal worker count
-2. Queue tasks for processing
-3. Distribute tasks to available workers
-4. Collect results and handle errors
-5. Recycle workers for next tasks
-6. Shutdown and cleanup resources
-```
-
-### **Parallel Processing Flow:**
-```typescript
-// 4-Pass Pipeline with Parallel Pass 2
-Pass 1: Structure Analysis (Sequential - lightweight)
-Pass 2: Code Parsing (Parallel - CPU intensive) ← NEW
-Pass 3: Import Resolution (Sequential - depends on Pass 2)
-Pass 4: Call Resolution (Sequential - depends on Pass 3)
-```
-
-### **Worker Communication Pattern:**
-```typescript
-// Main Thread → Worker
-worker.postMessage({
-  taskId: string,
-  input: TaskInput
-});
-
-// Worker → Main Thread
-self.postMessage({
-  taskId: string,
-  result: TaskOutput | error: string
-});
-```
-
-## 🎯 Integration Points
-
-### **Feature Flag Integration:**
-```typescript
-// Check if worker pool is enabled
-if (isWorkerPoolEnabled()) {
-  // Use parallel processing
-  const pipeline = new ParallelGraphPipeline();
-} else {
-  // Fallback to sequential processing
-  const pipeline = new GraphPipeline();
-}
-```
-
-### **Performance Monitoring:**
-```typescript
-// Worker pool statistics
-const stats = workerPool.getStats();
-console.log('Worker Pool Stats:', {
-  totalWorkers: stats.totalWorkers,
-  availableWorkers: stats.availableWorkers,
-  activeTasks: stats.activeTasks,
-  queuedTasks: stats.queuedTasks
-});
-```
-
-## 🚨 Error Handling & Fallbacks
-
-### **Worker Pool Error Handling:**
-- Worker crashes are handled gracefully
-- Failed workers are replaced automatically
-- Task timeouts prevent hanging operations
-- Fallback to sequential processing if workers fail
-
-### **Browser Compatibility:**
-- Checks for Web Worker support
-- Graceful degradation for unsupported browsers
-- Hardware concurrency detection
-- Memory usage monitoring
-
-## 📊 Performance Metrics
-
-### **Benchmark Results:**
-- **File Processing**: 4-8x faster for large codebases
-- **Memory Usage**: Efficient worker recycling
-- **CPU Utilization**: Near 100% on multi-core systems
-- **UI Responsiveness**: Main thread remains responsive
-
-### **Scalability:**
-- **Worker Count**: Automatically optimized based on hardware
-- **Task Distribution**: Intelligent load balancing
-- **Memory Management**: Automatic cleanup and recycling
-- **Error Recovery**: Robust error handling and recovery
-
-## 🔄 Migration Strategy
-
-### **From Sequential to Parallel:**
-1. **Feature Flag**: Enable `enableWorkerPool` flag
-2. **Pipeline Switch**: Replace `GraphPipeline` with `ParallelGraphPipeline`
-3. **Processor Update**: Use `ParallelParsingProcessor` for Pass 2
-4. **Testing**: Run comprehensive test suite
-5. **Monitoring**: Track performance improvements
-
-### **Backward Compatibility:**
-- All existing APIs remain unchanged
-- Feature flags control behavior
-- Graceful fallback to sequential processing
-- No breaking changes to existing code
-
-## 🎯 Future Enhancements
-
-### **Planned Improvements:**
-1. **Dynamic Worker Scaling**: Adjust worker count based on load
-2. **Advanced Caching**: Cache parsed ASTs for repeated processing
-3. **Streaming Processing**: Process files as they're uploaded
-4. **Priority Queuing**: Prioritize critical files for processing
-5. **Distributed Processing**: Support for multiple browser tabs/workers
-
-### **Performance Optimizations:**
-1. **Worker Pool Pooling**: Reuse worker pools across sessions
-2. **Memory Optimization**: Better memory management for large files
-3. **Load Balancing**: Intelligent task distribution
-4. **Preemptive Processing**: Start processing before all files are loaded
-
-## 📝 Critical Implementation Details
-
-### **Worker Script Loading:**
-- Worker scripts are served from `/public/workers/`
-- ES6 modules are used for better code organization
-- Tree-sitter WASM files are loaded dynamically
-- Error handling for missing worker scripts
-
-### **Task Serialization:**
-- Tasks are serialized for worker communication
-- Complex objects are simplified for transfer
-- Function references are converted to strings
-- Results are deserialized on main thread
-
-### **Memory Management:**
-- Workers are recycled after task completion
-- Large objects are transferred, not copied
-- Memory usage is monitored and logged
-- Automatic cleanup on pipeline shutdown
-
-## 🔍 Testing Strategy
-
-### **Test Coverage:**
-- **Unit Tests**: Individual worker pool functions
-- **Integration Tests**: End-to-end pipeline testing
-- **Performance Tests**: Benchmarking with various file sizes
-- **Error Tests**: Worker failure and recovery scenarios
-- **Browser Tests**: Cross-browser compatibility
-
-### **Test Commands:**
-```typescript
-// Browser console testing
-window.testWorkerPoolBasic()
-window.testFileProcessingPool()
-window.testWorkerPoolPerformance()
-window.runWorkerPoolTests()
-```
-
-## 📚 Documentation & Resources
-
-### **Key Documentation Files:**
-- `WORKER_POOL_IMPLEMENTATION_GUIDE.md` - Complete implementation guide
-- `src/lib/worker-pool-test.ts` - Test suite with examples
-- `public/workers/*.js` - Worker script documentation
-
-### **Architecture Diagrams:**
-- Worker Pool Lifecycle
-- Parallel Processing Flow
-- Error Handling Flow
-- Performance Monitoring
-
-## 🎯 Success Metrics
-
-### **Performance Improvements:**
-- ✅ 4-8x speedup for large codebases
-- ✅ Improved UI responsiveness
-- ✅ Better CPU utilization
-- ✅ Reduced memory pressure
-
-### **Code Quality:**
-- ✅ Comprehensive error handling
-- ✅ Extensive test coverage
-- ✅ Clear documentation
-- ✅ Backward compatibility
-
-### **User Experience:**
-- ✅ Progress tracking and feedback
-- ✅ Graceful error recovery
-- ✅ Automatic optimization
-- ✅ Feature flag control
-
-## 🔧 Configuration Options
-
-### **Worker Pool Configuration:**
-```typescript
-const workerPool = new WebWorkerPool({
-  maxWorkers: navigator.hardwareConcurrency || 4,
-  workerScript: '/workers/tree-sitter-worker.js',
-  timeout: 60000, // 60 seconds
-  name: 'ParallelParsingPool'
-});
-```
-
-### **Feature Flags:**
-```typescript
-// Enable all worker pool features
-featureFlags.enableWorkerPool();
-
-// Disable worker pool features
-featureFlags.disableWorkerPool();
-
-// Check worker pool status
-const isEnabled = isWorkerPoolEnabled();
-```
-
-## 🚀 Deployment Notes
-
-### **Production Considerations:**
-- Worker scripts must be served from public directory
-- Tree-sitter WASM files must be available
-- Feature flags control rollout
-- Performance monitoring is essential
-- Error logging for debugging
-
-### **Browser Support:**
-- Modern browsers with Web Worker support
-- ES6 module support required
-- WASM support for Tree-sitter
-- Hardware concurrency detection
-
-This implementation represents a significant architectural improvement to GitNexus, providing massive performance benefits for large codebases while maintaining backward compatibility and robust error handling.

compound-engineering.local.md

@@ -0,0 +1,57 @@
+---
+review_agents: [kieran-typescript-reviewer, pattern-recognition-specialist, architecture-strategist, data-integrity-guardian, security-sentinel, performance-oracle, code-simplicity-reviewer]
+plan_review_agents: [kieran-typescript-reviewer, architecture-strategist, code-simplicity-reviewer]
+voltagent_agents: [voltagent-lang:typescript-pro, voltagent-qa-sec:security-auditor, voltagent-data-ai:database-optimizer]
+---
+
+# Review Context
+
+## Project Overview
+GitNexus is a code intelligence tool that builds a knowledge graph from source code using tree-sitter AST parsing across 12 languages and KuzuDB for graph storage. Two packages: `gitnexus/` (CLI/MCP, TypeScript) and `gitnexus-web/` (browser).
+
+## Cross-Language Pattern Consistency (pattern-recognition-specialist)
+- 12 language-specific type extractors in `gitnexus/src/core/ingestion/type-extractors/` must follow identical patterns for: async unwrapping, constructor binding, namespace handling, nullable type stripping, for-loop element typing.
+- Past bugs: C#/Rust missing `await_expression` unwrapping that TypeScript handled correctly; PHP backslash namespace splitting inconsistent with other languages' `::` / `.` splitting.
+- When reviewing type extractor changes, verify the same pattern exists in ALL applicable language files — asymmetry is the #1 source of bugs.
+
+## Data Integrity (data-integrity-guardian)
+- KuzuDB graph operations: schema in `gitnexus/src/core/kuzu/schema.ts`, adapter in `kuzu-adapter.ts`.
+- The ingestion pipeline writes symbols and relationships to the graph — changes to node/relation schemas or the ingestion pipeline can corrupt the index.
+- Known issue: KuzuDB `close()` hangs on Linux due to C++ destructor — use `detachKuzu()` pattern.
+- `lbug-adapter.ts` fallback path needs quote/newline escaping for Cypher injection prevention.
+
+## Security (security-sentinel)
+- Cypher query construction in `lbug-adapter.ts` and `kuzu-adapter.ts` — watch for injection via unescaped user-provided symbol names.
+- CLI accepts `--repo` parameter and file paths — validate against path traversal.
+- MCP server exposes tools to external AI agents — all tool inputs are untrusted.
+
+## Performance (performance-oracle)
+- Tree-sitter buffer size is adaptive (512KB–32MB) via `getTreeSitterBufferSize()` in `constants.ts`.
+- The ingestion pipeline processes entire repositories — O(n) per file with potential O(n²) in cross-file resolution.
+- KuzuDB batch inserts vs individual inserts matter for large repos.
+
+## Architecture (architecture-strategist)
+- Ingestion pipeline phases: structure → parsing → imports → calls → heritage → processes → type resolution.
+- Shared modules: `export-detection.ts`, `constants.ts`, `utils.ts` — changes here have wide blast radius.
+- `gitnexus-web` package drifts behind CLI — flag if a change should be mirrored.
+
+## Voltagent Supplementary Agents
+
+Invoke these via the Agent tool alongside `/ce:review` for deeper specialist analysis. These cover gaps that compound-engineering agents don't:
+
+### voltagent-lang:typescript-pro
+**When:** Changes touch type-resolution logic, generics, conditional types, or complex type-level programming in `type-env.ts`, `type-extractors/*.ts`, or `types.ts`.
+**Why:** The type resolution system uses advanced TypeScript patterns (discriminated unions, mapped types, recursive generics) that benefit from deep TS type-system review beyond what kieran-typescript-reviewer covers.
+
+### voltagent-qa-sec:security-auditor
+**When:** Changes touch MCP tool handlers, Cypher query construction, CLI argument parsing, or any code that processes external input.
+**Why:** GitNexus is an MCP server — all tool inputs come from untrusted AI agents. Systematic OWASP-level audit catches injection vectors that spot-checking misses. Past finding: `lbug-adapter.ts` fallback path had unescaped newlines in Cypher queries.
+
+### voltagent-data-ai:database-optimizer
+**When:** Changes touch `kuzu-adapter.ts`, `schema.ts`, `lbug-adapter.ts`, or any Cypher query construction/execution.
+**Why:** No CE agent specializes in graph database optimization. KuzuDB batch insert patterns, index usage, and query planning directly affect analysis speed on large repos.
+
+## Review Tooling
+- Use `gitnexus_impact()` before approving changes to any symbol — check d=1 (WILL BREAK) callers.
+- Use `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` to map PR diffs to affected execution flows.
+- Use claude-mem to surface past architectural decisions relevant to the code under review.

debug-csv-issue.js

@@ -1 +0,0 @@
- 

debug-csv-line.js

@@ -1 +0,0 @@
- 

eslint.config.js

@@ -1,28 +0,0 @@
-import js from '@eslint/js'
-import globals from 'globals'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import tseslint from 'typescript-eslint'
-
-export default tseslint.config(
-  { ignores: ['dist'] },
-  {
-    extends: [js.configs.recommended, ...tseslint.configs.recommended],
-    files: ['**/*.{ts,tsx}'],
-    languageOptions: {
-      ecmaVersion: 2020,
-      globals: globals.browser,
-    },
-    plugins: {
-      'react-hooks': reactHooks,
-      'react-refresh': reactRefresh,
-    },
-    rules: {
-      ...reactHooks.configs.recommended.rules,
-      'react-refresh/only-export-components': [
-        'warn',
-        { allowConstantExport: true },
-      ],
-    },
-  },
-)

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 LadybugDB 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 LadybugDB 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/deepseek-chat.yaml

@@ -0,0 +1,13 @@
+model: deepseek-ai/deepseek-chat
+provider: openrouter
+cost:
+  input: 0.14  # per 1M tokens
+  output: 0.28  # per 1M tokens
+  
+# Native DeepSeek API (direct)
+api_key: null
+base_url: null
+
+# For OpenRouter, uncomment below and comment out direct config above
+# api_key: \${OPENROUTER_API_KEY}
+# base_url: https://openrouter.ai/api/v1

eval/configs/models/deepseek-v3.yaml

@@ -0,0 +1,15 @@
+model: deepseek-ai/DeepSeek-V3
+provider: openrouter
+cost:
+  input: 0.27  # per 1M tokens
+  output: 1.10  # per 1M tokens
+  
+# Native DeepSeek API (direct)
+# Get your API key at: https://platform.deepseek.com/
+# Or use OpenRouter with: OPENROUTER_API_KEY
+api_key: null
+base_url: null
+
+# For OpenRouter, uncomment below and comment out direct config above
+# api_key: \${OPENROUTER_API_KEY}
+# base_url: https://openrouter.ai/api/v1

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 LadybugDB 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
+```