diff --git a/gitnexus-mcp/package-lock.json b/gitnexus-mcp/package-lock.json
index 41fd58235..9798a4729 100644
--- a/gitnexus-mcp/package-lock.json
+++ b/gitnexus-mcp/package-lock.json
@@ -1,17 +1,16 @@
 {
     "name": "gitnexus-mcp",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "gitnexus-mcp",
-            "version": "0.1.0",
+            "version": "0.1.1",
+            "license": "MIT",
             "dependencies": {
                 "@modelcontextprotocol/sdk": "^1.0.0",
-                "chalk": "^5.3.0",
-                "commander": "^12.0.0",
-                "ora": "^8.0.0",
+                "uuid": "^13.0.0",
                 "ws": "^8.16.0"
             },
             "bin": {
@@ -19,6 +18,7 @@
             },
             "devDependencies": {
                 "@types/node": "^20.0.0",
+                "@types/uuid": "^10.0.0",
                 "@types/ws": "^8.5.10",
                 "tsx": "^4.0.0",
                 "typescript": "^5.4.0"
@@ -530,6 +530,13 @@
                 "undici-types": "~6.21.0"
             }
         },
+        "node_modules/@types/uuid": {
+            "version": "10.0.0",
+            "resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-10.0.0.tgz",
+            "integrity": "sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/@types/ws": {
             "version": "8.18.1",
             "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
@@ -586,18 +593,6 @@
                 }
             }
         },
-        "node_modules/ansi-regex": {
-            "version": "6.2.2",
-            "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
-            "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=12"
-            },
-            "funding": {
-                "url": "https://github.com/chalk/ansi-regex?sponsor=1"
-            }
-        },
         "node_modules/body-parser": {
             "version": "2.2.2",
             "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -660,54 +655,6 @@
                 "url": "https://github.com/sponsors/ljharb"
             }
         },
-        "node_modules/chalk": {
-            "version": "5.6.2",
-            "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz",
-            "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==",
-            "license": "MIT",
-            "engines": {
-                "node": "^12.17.0 || ^14.13 || >=16.0.0"
-            },
-            "funding": {
-                "url": "https://github.com/chalk/chalk?sponsor=1"
-            }
-        },
-        "node_modules/cli-cursor": {
-            "version": "5.0.0",
-            "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz",
-            "integrity": "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==",
-            "license": "MIT",
-            "dependencies": {
-                "restore-cursor": "^5.0.0"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
-        "node_modules/cli-spinners": {
-            "version": "2.9.2",
-            "resolved": "https://registry.npmjs.org/cli-spinners/-/cli-spinners-2.9.2.tgz",
-            "integrity": "sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=6"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
-        "node_modules/commander": {
-            "version": "12.1.0",
-            "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
-            "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=18"
-            }
-        },
         "node_modules/content-disposition": {
             "version": "1.0.1",
             "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.0.1.tgz",
@@ -821,12 +768,6 @@
             "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
             "license": "MIT"
         },
-        "node_modules/emoji-regex": {
-            "version": "10.6.0",
-            "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
-            "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
-            "license": "MIT"
-        },
         "node_modules/encodeurl": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
@@ -1087,18 +1028,6 @@
                 "url": "https://github.com/sponsors/ljharb"
             }
         },
-        "node_modules/get-east-asian-width": {
-            "version": "1.4.0",
-            "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz",
-            "integrity": "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/get-intrinsic": {
             "version": "1.3.0",
             "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
@@ -1246,36 +1175,12 @@
                 "node": ">= 0.10"
             }
         },
-        "node_modules/is-interactive": {
-            "version": "2.0.0",
-            "resolved": "https://registry.npmjs.org/is-interactive/-/is-interactive-2.0.0.tgz",
-            "integrity": "sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=12"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/is-promise": {
             "version": "4.0.0",
             "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
             "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==",
             "license": "MIT"
         },
-        "node_modules/is-unicode-supported": {
-            "version": "2.1.0",
-            "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-2.1.0.tgz",
-            "integrity": "sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/isexe": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
@@ -1303,34 +1208,6 @@
             "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
             "license": "BSD-2-Clause"
         },
-        "node_modules/log-symbols": {
-            "version": "6.0.0",
-            "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-6.0.0.tgz",
-            "integrity": "sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==",
-            "license": "MIT",
-            "dependencies": {
-                "chalk": "^5.3.0",
-                "is-unicode-supported": "^1.3.0"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
-        "node_modules/log-symbols/node_modules/is-unicode-supported": {
-            "version": "1.3.0",
-            "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-1.3.0.tgz",
-            "integrity": "sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=12"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/math-intrinsics": {
             "version": "1.1.0",
             "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -1386,18 +1263,6 @@
                 "url": "https://opencollective.com/express"
             }
         },
-        "node_modules/mimic-function": {
-            "version": "5.0.1",
-            "resolved": "https://registry.npmjs.org/mimic-function/-/mimic-function-5.0.1.tgz",
-            "integrity": "sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/ms": {
             "version": "2.1.3",
             "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -1455,44 +1320,6 @@
                 "wrappy": "1"
             }
         },
-        "node_modules/onetime": {
-            "version": "7.0.0",
-            "resolved": "https://registry.npmjs.org/onetime/-/onetime-7.0.0.tgz",
-            "integrity": "sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==",
-            "license": "MIT",
-            "dependencies": {
-                "mimic-function": "^5.0.0"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
-        "node_modules/ora": {
-            "version": "8.2.0",
-            "resolved": "https://registry.npmjs.org/ora/-/ora-8.2.0.tgz",
-            "integrity": "sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==",
-            "license": "MIT",
-            "dependencies": {
-                "chalk": "^5.3.0",
-                "cli-cursor": "^5.0.0",
-                "cli-spinners": "^2.9.2",
-                "is-interactive": "^2.0.0",
-                "is-unicode-supported": "^2.0.0",
-                "log-symbols": "^6.0.0",
-                "stdin-discarder": "^0.2.2",
-                "string-width": "^7.2.0",
-                "strip-ansi": "^7.1.0"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/parseurl": {
             "version": "1.3.3",
             "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
@@ -1601,22 +1428,6 @@
                 "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
             }
         },
-        "node_modules/restore-cursor": {
-            "version": "5.1.0",
-            "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-5.1.0.tgz",
-            "integrity": "sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==",
-            "license": "MIT",
-            "dependencies": {
-                "onetime": "^7.0.0",
-                "signal-exit": "^4.1.0"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/router": {
             "version": "2.2.0",
             "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
@@ -1783,18 +1594,6 @@
                 "url": "https://github.com/sponsors/ljharb"
             }
         },
-        "node_modules/signal-exit": {
-            "version": "4.1.0",
-            "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
-            "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
-            "license": "ISC",
-            "engines": {
-                "node": ">=14"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/isaacs"
-            }
-        },
         "node_modules/statuses": {
             "version": "2.0.2",
             "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
@@ -1804,50 +1603,6 @@
                 "node": ">= 0.8"
             }
         },
-        "node_modules/stdin-discarder": {
-            "version": "0.2.2",
-            "resolved": "https://registry.npmjs.org/stdin-discarder/-/stdin-discarder-0.2.2.tgz",
-            "integrity": "sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
-        "node_modules/string-width": {
-            "version": "7.2.0",
-            "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
-            "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
-            "license": "MIT",
-            "dependencies": {
-                "emoji-regex": "^10.3.0",
-                "get-east-asian-width": "^1.0.0",
-                "strip-ansi": "^7.1.0"
-            },
-            "engines": {
-                "node": ">=18"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
-        "node_modules/strip-ansi": {
-            "version": "7.1.2",
-            "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz",
-            "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==",
-            "license": "MIT",
-            "dependencies": {
-                "ansi-regex": "^6.0.1"
-            },
-            "engines": {
-                "node": ">=12"
-            },
-            "funding": {
-                "url": "https://github.com/chalk/strip-ansi?sponsor=1"
-            }
-        },
         "node_modules/toidentifier": {
             "version": "1.0.1",
             "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -1921,6 +1676,19 @@
                 "node": ">= 0.8"
             }
         },
+        "node_modules/uuid": {
+            "version": "13.0.0",
+            "resolved": "https://registry.npmjs.org/uuid/-/uuid-13.0.0.tgz",
+            "integrity": "sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==",
+            "funding": [
+                "https://github.com/sponsors/broofa",
+                "https://github.com/sponsors/ctavan"
+            ],
+            "license": "MIT",
+            "bin": {
+                "uuid": "dist-node/bin/uuid"
+            }
+        },
         "node_modules/vary": {
             "version": "1.1.2",
             "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
diff --git a/gitnexus/TODO.md b/gitnexus/TODO.md
index 0842fc03d..4ffce6f43 100644
--- a/gitnexus/TODO.md
+++ b/gitnexus/TODO.md
@@ -1,151 +1,372 @@
-# GitNexus V2 Strategic Roadmap: The "Semantic Understanding" Upgrade
+# GitNexus V2: Semantic Code Intelligence Roadmap
 
-> **Context for Models:** This document contains a comprehensive analysis of a competitor tool ("Noodlbox") and a detailed roadmap for integrating its best features into GitNexus. GitNexus is a browser-native (WASM) code analysis tool using KuzuDB and Tree-sitter. This roadmap aims to elevate GitNexus from a "Code Graph" to a "Semantic Code Understanding" platform.
+> **Last Updated:** January 2026  
+> **Vision:** Transform GitNexus from a "Code Graph" into a "Semantic Code Understanding" platform that rivals and surpasses tools like Noodlbox and DeepWiki.
 
 ---
 
-## 1. Competitive Analysis: GitNexus vs. Noodlbox
+## Executive Summary
 
-### Core Architecture
-| Feature | GitNexus (Current) | Noodlbox (Competitor) | Advantage |
-|---------|-------------------|-----------------------|-----------|
-| **Runtime** | **100% Browser (WASM)**. Zero setup. Privacy-first. | **CLI + Local Server**. Requires installation/daemon. | **GitNexus** (UX/Privacy) |
-| **Storage** | **KuzuDB (WASM)**. Graph + Vector. | **LanceDB**. Graph + Vector. | Tied (Both robust) |
-| **Extraction** | Tree-sitter (WASM). | Tree-sitter. | Tied |
-| **Integration** | Custom MCP Bridge (Browser ↔ Local). | Direct CLI MCP Server. | Noodlbox (Simpler setup) |
+### Current State
+- ✅ Tree-sitter parsing → AST extraction
+- ✅ KuzuDB (WASM) → Graph + Vector storage
+- ✅ Hybrid search (BM25 + Semantic)
+- ✅ LangChain Agent with tools (search, cypher, grep, read, blastRadius, highlight)
+- ✅ MCP integration for external AI tools
 
-### Conceptual Model (The Gap)
-| Feature | GitNexus | Noodlbox | Analysis |
-|---------|----------|----------|----------|
-| **Grouping** | File-based (Folders). | **Communities**. Algorithmic clustering of related code. | **Noodlbox**. Reveals logical architecture vs physical. |
-| **Flows** | Raw `CALLS` edges. | **Processes**. Named execution paths (Entry → End). | **Noodlbox**. "How it works" vs "What calls what". |
-| **Search** | Hybrid (BM25 + Vec). | Context Search. | Tied, but Noodlbox returns Processes. |
-| **Impact** | Node Blast Radius. | **Git Diff Impact**. Unstaged/Staged analysis. | **Noodlbox**. Much better DevEx. |
-| **UX** | Raw IDs/Filenames. | **Labels**. Human-readable names ("Auth System"). | **Noodlbox**. Cognitive load reduction. |
+### Target State
+- 🎯 **Communities:** Auto-detected code clusters (Leiden algorithm)
+- 🎯 **Processes:** Named execution flows with ordered steps
+- 🎯 **Hierarchical Navigation:** Codebase → Community → Process → Symbol
+- 🎯 **Auto-Documentation:** Generate ARCHITECTURE/ docs from graph
+- 🎯 **Incremental Updates:** File watch + delta graph updates
+- 🎯 **Git Diff Impact:** Pre-commit blast radius on uncommitted changes
 
 ---
 
-## 2. Strategic Goal: "The Graph of Meaning"
-We need to move GitNexus beyond just mapping *files and functions* to mapping *concepts and flows*.
-**Shift:** `Files -> Communities`, `Functions -> Processes`, `Edges -> Flows`.
+## Competitive Analysis
+
+### vs Noodlbox
+| Feature | Noodlbox | GitNexus (Current) | GitNexus (Planned) |
+|---------|----------|-------------------|-------------------|
+| Runtime | CLI + Server | Browser (WASM) ✅ | Browser (WASM) ✅ |
+| Communities | Leiden clusters ✅ | ❌ | ✅ Planned |
+| Processes | Named flows ✅ | ❌ | ✅ Planned |
+| Git Diff Impact | ✅ | ❌ | ✅ Planned |
+| Privacy | Local server | 100% Browser ✅ | 100% Browser ✅ |
+
+### vs OpenDeepWiki
+| Feature | OpenDeepWiki | GitNexus (Planned) |
+|---------|--------------|-------------------|
+| Structure Discovery | LLM guesses from files | Leiden from actual relationships ✅ |
+| Process Understanding | None (file-by-file) | Static analysis traces ✅ |
+| Grounding | File references only | Graph edges + files ✅ |
+| "What breaks if X changes" | Cannot answer | blastRadius ✅ |
+
+**Our Advantage:** Real graph-based understanding vs LLM inference.
 
 ---
 
-## 3. Implementation Roadmap
-
-### 🔥 PHASE 1: The Semantic Layer (High Priority)
-*Transform the raw KuzuDB graph into high-level concepts.*
-
-#### 1.1 Communities (Code Clusters)
-**Concept:** Use modularity optimization to group tightly coupled symbols into "Communities" (e.g., "Auth System", "Payment Processing") regardless of folder structure.
-*   **Algorithm:** Implement **Leiden Algorithm** (superior to Louvain for refined clusters) or **Louvain** in WASM (or pure JS if graph small enough).
-*   **Trigger:** Run post-ingestion.
-*   **Schema Update:**
-    *   New Node: `Community { id, label, cohesionScore }`
-    *   New Edge: `MEMBER_OF` (Symbol -> Community)
-*   **Metrics:** Calculate **Cohesion Score** (internal edges / total edges) to rate cluster quality (0-1).
-*   **Key Symbols:** Identify diverse "Entry Points" (called from outside) and "Central Hubs" (high internal degree).
-
-#### 1.2 Processes (Execution Flows)
-**Concept:** Trace and name execution paths often hidden in call graphs.
-*   **Detection Heuristic:**
-    1.  Find **Entry Points**: Functions called by Frameworks (e.g., `handleRequest`) or with 0 internal callers.
-    2.  Trace forward `CALLS` edges (limit depth/branching).
-    3.  Group linear paths.
-*   **Schema Update:**
-    *   New Node: `Process { id, label, process_type: 'intra'|'cross' }`
-    *   New Edge: `STEP_IN_PROCESS { step_number }` (Symbol -> Process)
-*   **Process Labeling:** Heuristic naming (e.g., `[EntryFn]_[Action]`).
-
-#### 1.3 Git Diff Impact Detection
-**Concept:** Analyze *work-in-progress* code, not just the committed graph.
-*   **MCP Tool:** `detect_impact(scope: 'unstaged' | 'staged')`
-*   **Workflow:**
-    1.  MCP Client reads `git diff`.
-    2.  Parse diff to find changed symbols (e.g., `src/auth.ts: function login`).
-    3.  Query Graph for `potentially_affected` (Downstream callers).
-    4.  **Crucial:** Map affected symbols to **Processes** and **Communities**.
-    5.  Output: "Changing `login` affects 'Checkout Flow' and 'User Onboarding Process'".
+## Phase-Wise Implementation Plan
 
 ---
 
-### 🟡 PHASE 2: Cognitive UX (Medium Priority)
-*Make the complex graph human-readable.*
+## PHASE 1: Community Detection (Leiden Algorithm)
+**Goal:** Group related code into named clusters.
 
-#### 2.1 Smart Labeling
-**Concept:** Replacing IDs with meaningful names.
-*   **Generator:** Simple LLM pass or rule-based heuristic.
-    *   Input: Top file paths in Community (e.g., `src/auth/*`, `src/login/*`).
-    *   Output: Label "Authentication".
-*   **Storage:** `.gitnexus/labels.json`.
-*   **Usage:** UI & MCP tools display "Auth System" instead of "Community #12".
+### 1.1 Research & Setup
+- [ ] Research JS/WASM implementations of Leiden algorithm
+  - Options: `graphology-communities-louvain`, custom WASM port
+  - Constraint: Must run in browser
+- [ ] Benchmark on sample codebases (100, 1K, 10K nodes)
 
-#### 2.2 Architecture Generation (`generate_map`)
-**Concept:** Auto-generated documentation that stays up to date.
-*   **MCP Tool:** `gitnexus_generate_architecture`
-*   **Output:** `ARCHITECTURE/` folder.
-    *   `README.md`: Mermaid Diagram of Communities + Cross-community data flow.
-    *   `{process_name}.md`: Sequence diagrams of key processes.
-*   **Value:** Instant "Onboarding Docs" for any repo.
+### 1.2 Schema Updates
+- [ ] Add `Community` node table to KuzuDB schema:
+  ```typescript
+  interface Community {
+    id: string;           // "comm_a7f3x2"
+    label: string;        // "Authentication" (heuristic or LLM)
+    cohesion: number;     // 0.0 - 1.0
+    symbolCount: number;  // Count of symbols in community
+  }
+  ```
+- [ ] Add `MEMBER_OF` relationship type to `CodeRelation`:
+  ```typescript
+  // Symbol -> Community
+  { type: 'MEMBER_OF', source: symbolId, target: communityId }
+  ```
 
-#### 2.3 Centrality & Importance
-**Concept:** Not all nodes are equal.
-*   **Algorithm:** **PageRank** or **Betweenness Centrality**.
-*   **Use Case:** Search results ranking. When searching "Auth", show the `AuthService` class before a random utility function used by it.
+### 1.3 Ingestion Pipeline Update
+- [ ] Create `community-processor.ts` in `src/core/ingestion/`
+- [ ] Add Phase 6 to pipeline (after heritage processing):
+  ```typescript
+  // pipeline.ts
+  await processCommunities(graph, onProgress);
+  ```
+- [ ] Implement Leiden on the CALLS + IMPORTS adjacency matrix
+- [ ] Generate heuristic labels (folder name majority)
+
+### 1.4 Agent Integration
+- [ ] Add `listCommunities` tool or resource
+- [ ] Update system prompt to teach agent about communities
+- [ ] Update `search` tool to return community context
+
+### 1.5 UI Updates
+- [ ] Color nodes by community in graph visualization
+- [ ] Add community filter/legend panel
+
+**Estimated Effort:** 2-3 weeks
 
 ---
 
-### 🟢 PHASE 3: Agentic Workflows (Low Priority)
-*Standardized "Thinking Patterns" for the LLM.*
+## PHASE 2: Process Detection (Execution Flows)
+**Goal:** Trace and name execution paths.
 
-#### 3.1 "Skills" (Structured Prompts)
-Define rigid workflows for the Agent to prevent "wandering":
-*   **Exploration Skill:** `Read Map -> Pick Community -> List Key Processes -> Drill Down`.
-*   **Debugging Skill:** `Error Msg -> Search Context -> Trace Backwards (Callers) -> Check Recent Changes`.
-*   **Refactoring Skill:** `Select Symbol -> Blast Radius -> Dependencies (In/Out) -> Plan Split`.
+### 2.1 Schema Updates
+- [ ] Add `Process` node table to KuzuDB schema:
+  ```typescript
+  interface Process {
+    id: string;           // "proc_login_flow"
+    label: string;        // "User Login Flow"
+    type: 'intra_community' | 'cross_community';
+    stepCount: number;
+  }
+  ```
+- [ ] Add `STEP_IN_PROCESS` relationship type:
+  ```typescript
+  // Symbol -> Process (with step property)
+  { type: 'STEP_IN_PROCESS', source: symbolId, target: processId, step: number }
+  ```
 
-#### 3.2 Hooks
-*   **Session Hook:** auto-inject `database-schema` and high-level `codebase-map` at chat start.
-*   **Search Hook:** Intercept `grep` in IDE to attach semantic context ("This match is part of 'Payment Process'").
+### 2.2 Process Detection Algorithm
+- [ ] Create `process-processor.ts` in `src/core/ingestion/`
+- [ ] Implement entry point detection:
+  ```typescript
+  // Functions with no internal callers
+  MATCH (f:Function) 
+  WHERE NOT (:Function)-[:CALLS]->(f) 
+  RETURN f
+  ```
+- [ ] Implement forward tracing (BFS/DFS from entry points)
+- [ ] Limit depth (e.g., 10) and branching (e.g., 3)
+- [ ] Deduplicate overlapping paths
+- [ ] Label processes (heuristic: `{entry}_to_{terminal}`)
+
+### 2.3 Community Integration
+- [ ] Track which communities each process touches
+- [ ] Mark `type` as `cross_community` if > 1 community
+
+### 2.4 Agent Integration
+- [ ] Add `listProcesses(communityId?)` tool
+- [ ] Add `traceProcess(processId)` tool
+- [ ] Update system prompt with process navigation
+
+### 2.5 UI Updates
+- [ ] Visualize processes as highlighted paths
+- [ ] Add process list panel
+- [ ] Click process → animate the flow
+
+**Estimated Effort:** 2 weeks
 
 ---
 
-## 4. Technical Specs & Schema Changes
+## PHASE 3: Smart Labeling (LLM Enhancement)
+**Goal:** Human-readable names for Communities and Processes.
 
-### Proposed KuzuDB Schema V2
+### 3.1 Heuristic Labeling (Default)
+- [ ] Community: Most common folder prefix
+- [ ] Process: `{entryFunction}_to_{terminalFunction}`
 
+### 3.2 LLM Labeling (Optional Enhancement)
+- [ ] Create `labeling-service.ts`
+- [ ] Batch communities/processes for LLM naming
+- [ ] Prompt template:
+  ```
+  Given these functions: login, validateToken, checkExpiry, refreshSession
+  All in folder: src/auth/
+  Generate a 2-3 word label for this code cluster.
+  ```
+- [ ] Store both `heuristicLabel` and `llmLabel`
+- [ ] Use `llmLabel` if available, else `heuristicLabel`
+
+### 3.3 Labels File Export
+- [ ] Generate `.gitnexus/labels.json` on demand
+- [ ] Format matching Noodlbox for familiarity
+
+**Estimated Effort:** 1 week
+
+---
+
+## PHASE 4: Architecture Documentation Generation
+**Goal:** Auto-generate project documentation from graph.
+
+### 4.1 Documentation Structure
+- [ ] Output: `ARCHITECTURE/` folder
+  ```
+  ARCHITECTURE/
+  ├── README.md              # Overview + Mermaid diagram
+  ├── communities/
+  │   ├── authentication.md  # Community detail
+  │   └── payments.md
+  └── processes/
+      ├── user-login-flow.md # Process trace
+      └── checkout-flow.md
+  ```
+
+### 4.2 Implementation
+- [ ] Create `generate-docs.ts` in `src/core/docs/`
+- [ ] README.md generation:
+  - Codebase stats (files, symbols, communities, processes)
+  - Mermaid diagram of community relationships
+  - List of key processes
+- [ ] Community doc generation:
+  - Key symbols (highest centrality)
+  - Entry points
+  - Processes in this community
+- [ ] Process doc generation:
+  - Ordered step list with file paths
+  - Mermaid sequence diagram
+  - Cross-community markers
+
+### 4.3 MCP Tool
+- [ ] Add `generateArchitecture` tool to MCP
+- [ ] Returns generated markdown (or writes to files)
+
+**Estimated Effort:** 2 weeks
+
+---
+
+## PHASE 5: Git Diff Impact Detection
+**Goal:** Pre-commit blast radius analysis.
+
+### 5.1 MCP Server Updates
+- [ ] Add `detectImpact` tool to `gitnexus-mcp`
+- [ ] Parameters:
+  ```typescript
+  interface DetectImpactParams {
+    scope: 'unstaged' | 'staged' | 'all' | 'compare';
+    baseRef?: string;  // For 'compare' scope
+  }
+  ```
+
+### 5.2 Implementation
+- [ ] Run `git diff` (MCP server side)
+- [ ] Parse diff to extract changed file paths + line ranges
+- [ ] Map changes to symbols in graph
+- [ ] Run `blastRadius` on each changed symbol
+- [ ] Aggregate results by:
+  - Changed symbols
+  - Impacted processes
+  - Affected communities
+  - Risk level (low/medium/high)
+
+### 5.3 Response Format
 ```typescript
-// Nodes
-interface Community {
-  id: string; // "comm_1"
-  label: string; // "Authentication"
-  cohesion: number; // 0.85
+interface ImpactResult {
+  changedSymbols: { name: string; file: string; changeType: 'added' | 'modified' | 'deleted' }[];
+  impactedProcesses: { id: string; label: string; affectedSteps: number[] }[];
+  affectedCommunities: string[];
+  riskLevel: 'low' | 'medium' | 'high';
 }
-
-interface Process {
-  id: string; // "proc_login_flow"
-  label: string; // "Login Flow"
-  type: 'intra_community' | 'cross_community';
-}
-
-// Relationships
-// MEMBER_OF: Symbol -> Community
-// STEP_IN_PROCESS: Symbol -> Process (property: step_index)
 ```
 
-### Algorithm Reference
-*   **Leiden Algorithm:**
-    *   *Input:* Adjacency matrix of `CALLS` + `EXTENDS` edges.
-    *   *Output:* Partition assignment (NodeID -> CommunityID).
-    *   *Constraint:* Must run fast in JS/WASM.
-*   **Reciprocal Rank Fusion (RRF):**
-    *   Already used for Search. Can be refined to weight "Key Symbols" (Centrality) higher.
+**Estimated Effort:** 1-2 weeks
 
 ---
 
-## 5. Summary of Work to Be Done
-1.  **Ingestion:** Add `CommunityDetection` and `ProcessTracing` post-processors.
-2.  **Schema:** Add `Community` and `Process` tables.
-3.  **MCP:** Add `detect_impact` tool accepting git diffs.
-4.  **UI:** Visualize Communities (colored clusters) and Processes (animated paths).
-5.  **Docs:** Implement `generate_map` to export findings to Markdown.
+## PHASE 6: Incremental Updates (File Watch)
+**Goal:** Real-time graph updates on file changes.
+
+### 6.1 File Watching
+- [ ] Integrate file system watcher in MCP server
+- [ ] Detect: added, modified, deleted files
+- [ ] Debounce rapid changes (e.g., 500ms)
+
+### 6.2 Incremental Parsing
+- [ ] Hash-based cache: file path → content hash → AST
+- [ ] On change: re-parse only changed file
+- [ ] Compute delta: added/removed nodes and edges
+
+### 6.3 Graph Patching
+- [ ] Add `patchGraph` method to KuzuDB adapter
+- [ ] Operations: ADD_NODE, REMOVE_NODE, ADD_EDGE, REMOVE_EDGE
+- [ ] Update affected communities (optional: re-run Leiden locally)
+- [ ] Update affected processes (re-trace from changed symbols)
+
+### 6.4 Re-embedding
+- [ ] Re-embed changed symbols
+- [ ] Re-embed 1-hop neighbors (context changed)
+
+**Estimated Effort:** 2-3 weeks
+
+---
+
+## PHASE 7: Agent Prompt Refinement
+**Goal:** Teach agent to use hierarchical navigation.
+
+### 7.1 System Prompt Updates
+- [ ] Add "Hierarchical Navigation Protocol":
+  ```
+  1. Query codebase map (communities overview)
+  2. Identify relevant community
+  3. List processes in that community
+  4. Trace specific process
+  5. Read code for specific steps
+  ```
+- [ ] Add tool descriptions for new tools
+
+### 7.2 Skills (Optional)
+- [ ] Create structured prompts for common tasks:
+  - Exploration: "How does X work?"
+  - Debugging: "Why is X failing?"
+  - Refactoring: "What breaks if I change X?"
+  - Documentation: "Generate docs for X"
+
+**Estimated Effort:** 1 week
+
+---
+
+## Implementation Priority Order
+
+| Phase | Name | Priority | Effort | Dependency |
+|-------|------|----------|--------|------------|
+| 1 | Communities (Leiden) | 🔴 Critical | 2-3 weeks | None |
+| 2 | Processes | 🔴 Critical | 2 weeks | Phase 1 |
+| 3 | Smart Labeling | 🟡 Medium | 1 week | Phase 1, 2 |
+| 4 | Documentation | 🟡 Medium | 2 weeks | Phase 1, 2 |
+| 5 | Git Diff Impact | 🟡 Medium | 1-2 weeks | None (uses existing blastRadius) |
+| 6 | Incremental Updates | 🟢 Nice-to-have | 2-3 weeks | None |
+| 7 | Agent Prompt | 🟡 Medium | 1 week | Phase 1, 2 |
+
+**Recommended order:** 1 → 2 → 7 → 3 → 4 → 5 → 6
+
+---
+
+## Technical Notes
+
+### Leiden Algorithm Options
+1. **graphology-communities-louvain** (JS, works in browser)
+2. **Custom WASM port** (if performance needed)
+3. **Simple Louvain** might be sufficient for V1
+
+### Schema Summary (New Additions)
+```
+NEW NODES:
+  - Community { id, label, cohesion, symbolCount }
+  - Process { id, label, type, stepCount }
+
+NEW RELATIONSHIPS (in CodeRelation):
+  - MEMBER_OF: Symbol → Community
+  - STEP_IN_PROCESS: Symbol → Process (with step property)
+```
+
+### Graph Visualization Color Scheme
+```
+Community colors (auto-assigned):
+  - Auth: Blue
+  - Data: Green
+  - API: Orange
+  - Payment: Purple
+  - ... (cyclic palette)
+```
+
+---
+
+## Success Metrics
+
+| Metric | Current | Target |
+|--------|---------|--------|
+| Agent query accuracy | ~70% | 90%+ |
+| Context tokens per query | High (dump everything) | Low (hierarchical zoom) |
+| Documentation quality | N/A | Comparable to DeepWiki |
+| Update latency | Full re-ingest (minutes) | Incremental (seconds) |
+
+---
+
+## Next Steps
+
+1. **Immediate:** Research Leiden implementations for browser
+2. **Week 1-2:** Implement Phase 1 (Communities)
+3. **Week 3-4:** Implement Phase 2 (Processes)
+4. **Week 5:** Refine agent prompt (Phase 7)
+5. **Week 6+:** Documentation generation & polish
diff --git a/gitnexus/package-lock.json b/gitnexus/package-lock.json
index 69a5b8960..0bbe7d72a 100644
--- a/gitnexus/package-lock.json
+++ b/gitnexus/package-lock.json
@@ -23,6 +23,7 @@
         "comlink": "^4.4.2",
         "d3": "^7.9.0",
         "graphology": "^0.26.0",
+        "graphology-communities-louvain": "^2.0.2",
         "graphology-layout-force": "^0.2.4",
         "graphology-layout-forceatlas2": "^0.10.1",
         "graphology-layout-noverlap": "^0.4.2",
@@ -56,6 +57,7 @@
         "@types/react-syntax-highlighter": "^15.5.13",
         "@vercel/node": "^5.5.16",
         "@vitejs/plugin-react": "^5.1.0",
+        "tree-sitter-wasms": "^0.1.13",
         "typescript": "^5.4.5",
         "vite": "^5.2.0",
         "vite-plugin-static-copy": "^3.1.4"
@@ -5515,6 +5517,34 @@
         "graphology-types": ">=0.24.0"
       }
     },
+    "node_modules/graphology-communities-louvain": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/graphology-communities-louvain/-/graphology-communities-louvain-2.0.2.tgz",
+      "integrity": "sha512-zt+2hHVPYxjEquyecxWXoUoIuN/UvYzsvI7boDdMNz0rRvpESQ7+e+Ejv6wK7AThycbZXuQ6DkG8NPMCq6XwoA==",
+      "license": "MIT",
+      "dependencies": {
+        "graphology-indices": "^0.17.0",
+        "graphology-utils": "^2.4.4",
+        "mnemonist": "^0.39.0",
+        "pandemonium": "^2.4.1"
+      },
+      "peerDependencies": {
+        "graphology-types": ">=0.19.0"
+      }
+    },
+    "node_modules/graphology-indices": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/graphology-indices/-/graphology-indices-0.17.0.tgz",
+      "integrity": "sha512-A7RXuKQvdqSWOpn7ZVQo4S33O0vCfPBnUSf7FwE0zNCasqwZVUaCXePuWo5HBpWw68KJcwObZDHpFk6HKH6MYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "graphology-utils": "^2.4.2",
+        "mnemonist": "^0.39.0"
+      },
+      "peerDependencies": {
+        "graphology-types": ">=0.20.0"
+      }
+    },
     "node_modules/graphology-layout-force": {
       "version": "0.2.4",
       "resolved": "https://registry.npmjs.org/graphology-layout-force/-/graphology-layout-force-0.2.4.tgz",
@@ -7726,6 +7756,15 @@
         "ufo": "^1.6.1"
       }
     },
+    "node_modules/mnemonist": {
+      "version": "0.39.8",
+      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.39.8.tgz",
+      "integrity": "sha512-vyWo2K3fjrUw8YeeZ1zF0fy6Mu59RHokURlld8ymdUPjMlD9EC9ov1/YPqTgqRvUN9nTr3Gqfz29LYAmu0PHPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "obliterator": "^2.0.1"
+      }
+    },
     "node_modules/mri": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz",
@@ -7844,6 +7883,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/obliterator": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/obliterator/-/obliterator-2.0.5.tgz",
+      "integrity": "sha512-42CPE9AhahZRsMNslczq0ctAEtqk8Eka26QofnqC346BZdHDySk3LWka23LI7ULIw11NmltpiLagIq8gBozxTw==",
+      "license": "MIT"
+    },
     "node_modules/observable-fns": {
       "version": "0.6.1",
       "resolved": "https://registry.npmjs.org/observable-fns/-/observable-fns-0.6.1.tgz",
@@ -8009,6 +8054,15 @@
       "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
       "license": "(MIT AND Zlib)"
     },
+    "node_modules/pandemonium": {
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/pandemonium/-/pandemonium-2.4.1.tgz",
+      "integrity": "sha512-wRqjisUyiUfXowgm7MFH2rwJzKIr20rca5FsHXCMNm1W5YPP1hCtrZfgmQ62kP7OZ7Xt+cR858aB28lu5NX55g==",
+      "license": "MIT",
+      "dependencies": {
+        "mnemonist": "^0.39.2"
+      }
+    },
     "node_modules/parse-entities": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz",
@@ -9101,6 +9155,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/tree-sitter-wasms": {
+      "version": "0.1.13",
+      "resolved": "https://registry.npmjs.org/tree-sitter-wasms/-/tree-sitter-wasms-0.1.13.tgz",
+      "integrity": "sha512-wT+cR6DwaIz80/vho3AvSF0N4txuNx/5bcRKoXouOfClpxh/qqrF4URNLQXbbt8MaAxeksZcZd1j8gcGjc+QxQ==",
+      "dev": true,
+      "license": "Unlicense",
+      "dependencies": {
+        "tree-sitter-wasms": "^0.1.11"
+      }
+    },
     "node_modules/trim-lines": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",
diff --git a/gitnexus/package.json b/gitnexus/package.json
index 80e7b0189..76571053b 100644
--- a/gitnexus/package.json
+++ b/gitnexus/package.json
@@ -24,6 +24,7 @@
     "comlink": "^4.4.2",
     "d3": "^7.9.0",
     "graphology": "^0.26.0",
+    "graphology-communities-louvain": "^2.0.2",
     "graphology-layout-force": "^0.2.4",
     "graphology-layout-forceatlas2": "^0.10.1",
     "graphology-layout-noverlap": "^0.4.2",
@@ -57,8 +58,9 @@
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vercel/node": "^5.5.16",
     "@vitejs/plugin-react": "^5.1.0",
+    "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.4.5",
     "vite": "^5.2.0",
     "vite-plugin-static-copy": "^3.1.4"
   }
-}
\ No newline at end of file
+}
diff --git a/gitnexus/public/wasm/c/tree-sitter-c.wasm b/gitnexus/public/wasm/c/tree-sitter-c.wasm
new file mode 100644
index 000000000..ceda238dc
Binary files /dev/null and b/gitnexus/public/wasm/c/tree-sitter-c.wasm differ
diff --git a/gitnexus/public/wasm/cpp/tree-sitter-cpp.wasm b/gitnexus/public/wasm/cpp/tree-sitter-cpp.wasm
new file mode 100644
index 000000000..2d453db9d
Binary files /dev/null and b/gitnexus/public/wasm/cpp/tree-sitter-cpp.wasm differ
diff --git a/gitnexus/public/wasm/csharp/tree-sitter-csharp.wasm b/gitnexus/public/wasm/csharp/tree-sitter-csharp.wasm
new file mode 100644
index 000000000..5c11b4f34
Binary files /dev/null and b/gitnexus/public/wasm/csharp/tree-sitter-csharp.wasm differ
diff --git a/gitnexus/public/wasm/go/tree-sitter-go.wasm b/gitnexus/public/wasm/go/tree-sitter-go.wasm
new file mode 100644
index 000000000..a20aba8a9
Binary files /dev/null and b/gitnexus/public/wasm/go/tree-sitter-go.wasm differ
diff --git a/gitnexus/public/wasm/java/tree-sitter-java.wasm b/gitnexus/public/wasm/java/tree-sitter-java.wasm
new file mode 100644
index 000000000..45022a965
Binary files /dev/null and b/gitnexus/public/wasm/java/tree-sitter-java.wasm differ
diff --git a/gitnexus/public/wasm/rust/tree-sitter-rust.wasm b/gitnexus/public/wasm/rust/tree-sitter-rust.wasm
new file mode 100644
index 000000000..5b3b213d0
Binary files /dev/null and b/gitnexus/public/wasm/rust/tree-sitter-rust.wasm differ
diff --git a/gitnexus/src/App.tsx b/gitnexus/src/App.tsx
index c305a18a4..1288e502c 100644
--- a/gitnexus/src/App.tsx
+++ b/gitnexus/src/App.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useRef } from 'react';
+import { useCallback, useRef, useState, useEffect } from 'react';
 import { AppStateProvider, useAppState } from './hooks/useAppState';
 import { DropZone } from './components/DropZone';
 import { LoadingOverlay } from './components/LoadingOverlay';
@@ -11,6 +11,8 @@ import { FileTreePanel } from './components/FileTreePanel';
 import { CodeReferencesPanel } from './components/CodeReferencesPanel';
 import { FileEntry } from './services/zip';
 import { getActiveProviderConfig } from './core/llm/settings-service';
+import { ProviderConfig } from './core/llm/types';
+import { IntelligentClusteringModal } from './components/IntelligentClusteringModal';
 
 const AppContent = () => {
   const {
@@ -29,23 +31,68 @@ const AppContent = () => {
     refreshLLMSettings,
     initializeAgent,
     startEmbeddings,
+    startBackgroundEnrichment,
     embeddingStatus,
     codeReferences,
     selectedNode,
     isCodePanelOpen,
+    llmSettings,
+    updateLLMSettings,
+    runClusterEnrichment,
   } = useAppState();
 
+  const [showClusteringModal, setShowClusteringModal] = useState(false);
+
+  // Trigger clustering modal after ingestion if not seen yet
+  // DISABLED: Clustering is now in the upload flow
+  /*
+  useEffect(() => {
+    if (viewMode === 'exploring' && !llmSettings.hasSeenClusteringPrompt && !llmSettings.intelligentClustering) {
+      const timer = setTimeout(() => setShowClusteringModal(true), 2000);
+      return () => clearTimeout(timer);
+    }
+  }, [viewMode, llmSettings.hasSeenClusteringPrompt, llmSettings.intelligentClustering]);
+  */
+
+  const handleEnableClustering = useCallback(() => {
+    updateLLMSettings({
+      intelligentClustering: true,
+      hasSeenClusteringPrompt: true,
+      useSameModelForClustering: true // Default to simple path
+    });
+    setShowClusteringModal(false);
+    runClusterEnrichment().catch(console.error);
+  }, [updateLLMSettings, runClusterEnrichment]);
+
+  const handleConfigureClustering = useCallback(() => {
+    updateLLMSettings({ hasSeenClusteringPrompt: true });
+    setShowClusteringModal(false);
+    setSettingsPanelOpen(true);
+  }, [updateLLMSettings, setSettingsPanelOpen]);
+
+  const handleSkipClustering = useCallback(() => {
+    updateLLMSettings({ hasSeenClusteringPrompt: true });
+    setShowClusteringModal(false);
+  }, [updateLLMSettings]);
+
   const graphCanvasRef = useRef<GraphCanvasHandle>(null);
 
-  const handleFileSelect = useCallback(async (file: File) => {
+  const handleFileSelect = useCallback(async (file: File, enableSmartClustering?: boolean) => {
+    console.log('📥 App.handleFileSelect - param received:', enableSmartClustering, 'provider exists:', !!getActiveProviderConfig());
     const projectName = file.name.replace('.zip', '');
     setProjectName(projectName);
+    // Set initial progress BEFORE entering loading mode to prevent black screen
+    setProgress({ phase: 'extracting', percent: 0, message: 'Starting...', detail: 'Preparing to extract files' });
     setViewMode('loading');
 
     try {
+      // Prepare LLM config if clustering is enabled
+      const clusteringConfig = enableSmartClustering ? getActiveProviderConfig() ?? undefined : undefined;
+      console.log('✅ clusteringConfig:', !!clusteringConfig, clusteringConfig?.provider);
+
       const result = await runPipeline(file, (progress) => {
         setProgress(progress);
-      });
+      }, clusteringConfig || undefined);
 
       setGraph(result.graph);
       setFileContents(result.fileContents);
@@ -67,6 +114,9 @@ const AppContent = () => {
           console.warn('Embeddings auto-start failed:', err);
         }
       });
+
+      // Start background cluster enrichment (if toggle was enabled)
+      startBackgroundEnrichment().catch(console.warn);
     } catch (error) {
       console.error('Pipeline error:', error);
       setProgress({
@@ -80,20 +130,25 @@ const AppContent = () => {
         setProgress(null);
       }, 3000);
     }
-  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipeline, startEmbeddings, initializeAgent]);
+  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipeline, startEmbeddings, initializeAgent, llmSettings]);
 
-  const handleGitClone = useCallback(async (files: FileEntry[]) => {
+  const handleGitClone = useCallback(async (files: FileEntry[], enableSmartClustering?: boolean) => {
     // Extract project name from first file path (e.g., "owner-repo-123/src/..." -> "owner-repo")
     const firstPath = files[0]?.path || 'repository';
     const projectName = firstPath.split('/')[0].replace(/-\d+$/, '') || 'repository';
 
     setProjectName(projectName);
+    // Set initial progress BEFORE entering loading mode to prevent black screen
+    setProgress({ phase: 'extracting', percent: 0, message: 'Starting...', detail: 'Preparing to process files' });
     setViewMode('loading');
 
     try {
+      // Prepare LLM config if clustering is enabled
+      const clusteringConfig = enableSmartClustering ? getActiveProviderConfig() ?? undefined : undefined;
+
       const result = await runPipelineFromFiles(files, (progress) => {
         setProgress(progress);
-      });
+      }, clusteringConfig || undefined);
 
       setGraph(result.graph);
       setFileContents(result.fileContents);
@@ -115,6 +170,9 @@ const AppContent = () => {
           console.warn('Embeddings auto-start failed:', err);
         }
       });
+
+      // Start background cluster enrichment (if toggle was enabled)
+      startBackgroundEnrichment().catch(console.warn);
     } catch (error) {
       console.error('Pipeline error:', error);
       setProgress({
@@ -128,7 +186,7 @@ const AppContent = () => {
         setProgress(null);
       }, 3000);
     }
-  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipelineFromFiles, startEmbeddings, initializeAgent]);
+  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipelineFromFiles, startEmbeddings, initializeAgent, runClusterEnrichment]);
 
   const handleFocusNode = useCallback((nodeId: string) => {
     graphCanvasRef.current?.focusNode(nodeId);
@@ -183,6 +241,14 @@ const AppContent = () => {
         onClose={() => setSettingsPanelOpen(false)}
         onSettingsSaved={handleSettingsSaved}
       />
+
+      {/* Intelligent Clustering Modal */}
+      <IntelligentClusteringModal
+        isOpen={showClusteringModal}
+        onClose={handleSkipClustering}
+        onEnable={handleEnableClustering}
+        onConfigure={handleConfigureClustering}
+      />
     </div>
   );
 };
diff --git a/gitnexus/src/components/DropZone.tsx b/gitnexus/src/components/DropZone.tsx
index c2141f61a..0bce617a9 100644
--- a/gitnexus/src/components/DropZone.tsx
+++ b/gitnexus/src/components/DropZone.tsx
@@ -1,11 +1,12 @@
-import { useState, useCallback, DragEvent } from 'react';
-import { Upload, FileArchive, Github, Loader2, ArrowRight, Key, Eye, EyeOff } from 'lucide-react';
+import { useState, useCallback, DragEvent, useEffect } from 'react';
+import { Upload, FileArchive, Github, Loader2, ArrowRight, Key, Eye, EyeOff, Sparkles } from 'lucide-react';
 import { cloneRepository, parseGitHubUrl } from '../services/git-clone';
 import { FileEntry } from '../services/zip';
+import { getActiveProviderConfig } from '../core/llm/settings-service';
 
 interface DropZoneProps {
-  onFileSelect: (file: File) => void;
-  onGitClone?: (files: FileEntry[]) => void;
+  onFileSelect: (file: File, enableSmartClustering?: boolean) => void;
+  onGitClone?: (files: FileEntry[], enableSmartClustering?: boolean) => void;
 }
 
 export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
@@ -17,6 +18,15 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
   const [isCloning, setIsCloning] = useState(false);
   const [cloneProgress, setCloneProgress] = useState({ phase: '', percent: 0 });
   const [error, setError] = useState<string | null>(null);
+  const [enableSmartClustering, setEnableSmartClustering] = useState(false);
+  const [hasLLMProvider, setHasLLMProvider] = useState(false);
+
+  // Check if LLM provider is configured
+  useEffect(() => {
+    const config = getActiveProviderConfig();
+    setHasLLMProvider(!!config);
+    // Keep smart clustering OFF by default, user must opt-in
+  }, []);
 
   const handleDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
     e.preventDefault();
@@ -39,24 +49,25 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
     if (files.length > 0) {
       const file = files[0];
       if (file.name.endsWith('.zip')) {
-        onFileSelect(file);
+        onFileSelect(file, enableSmartClustering);
       } else {
         setError('Please drop a .zip file');
       }
     }
-  }, [onFileSelect]);
+  }, [onFileSelect, enableSmartClustering]);
 
   const handleFileInput = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
     const files = e.target.files;
     if (files && files.length > 0) {
       const file = files[0];
       if (file.name.endsWith('.zip')) {
-        onFileSelect(file);
+        console.log('🎯 DropZone: Calling onFileSelect with enableSmartClustering:', enableSmartClustering);
+        onFileSelect(file, enableSmartClustering);
       } else {
         setError('Please select a .zip file');
       }
     }
-  }, [onFileSelect]);
+  }, [onFileSelect, enableSmartClustering]);
 
   const handleGitClone = async () => {
     if (!githubUrl.trim()) {
@@ -76,16 +87,16 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
 
     try {
       const files = await cloneRepository(
-        githubUrl, 
+        githubUrl,
         (phase, percent) => setCloneProgress({ phase, percent }),
         githubToken || undefined // Pass token if provided
       );
 
       // Clear token from memory after successful clone
       setGithubToken('');
-      
+
       if (onGitClone) {
-        onGitClone(files);
+        onGitClone(files, enableSmartClustering);
       }
     } catch (err) {
       console.error('Clone failed:', err);
@@ -123,8 +134,8 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
             className={`
               flex-1 flex items-center justify-center gap-2 py-2.5 px-4 rounded-lg
               text-sm font-medium transition-all duration-200
-              ${activeTab === 'zip' 
-                ? 'bg-accent text-white shadow-md' 
+              ${activeTab === 'zip'
+                ? 'bg-accent text-white shadow-md'
                 : 'text-text-secondary hover:text-text-primary hover:bg-elevated'
               }
             `}
@@ -137,8 +148,8 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
             className={`
               flex-1 flex items-center justify-center gap-2 py-2.5 px-4 rounded-lg
               text-sm font-medium transition-all duration-200
-              ${activeTab === 'github' 
-                ? 'bg-accent text-white shadow-md' 
+              ${activeTab === 'github'
+                ? 'bg-accent text-white shadow-md'
                 : 'text-text-secondary hover:text-text-primary hover:bg-elevated'
               }
             `}
@@ -157,60 +168,98 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
 
         {/* ZIP Upload Tab */}
         {activeTab === 'zip' && (
-          <div
-            className={`
-              relative p-16 
-              bg-surface border-2 border-dashed rounded-3xl
-              transition-all duration-300 cursor-pointer
-              ${isDragging 
-                ? 'border-accent bg-elevated scale-105 shadow-glow' 
-                : 'border-border-default hover:border-accent/50 hover:bg-elevated/50 animate-breathe'
-              }
-            `}
-            onDragOver={handleDragOver}
-            onDragLeave={handleDragLeave}
-            onDrop={handleDrop}
-            onClick={() => document.getElementById('file-input')?.click()}
-          >
-            <input
-              id="file-input"
-              type="file"
-              accept=".zip"
-              className="hidden"
-              onChange={handleFileInput}
-            />
+          <>
+            <div
+              className={`
+                relative p-16 
+                bg-surface border-2 border-dashed rounded-3xl
+                transition-all duration-300 cursor-pointer
+                ${isDragging
+                  ? 'border-accent bg-elevated scale-105 shadow-glow'
+                  : 'border-border-default hover:border-accent/50 hover:bg-elevated/50 animate-breathe'
+                }
+              `}
+              onDragOver={handleDragOver}
+              onDragLeave={handleDragLeave}
+              onDrop={handleDrop}
+              onClick={() => document.getElementById('file-input')?.click()}
+            >
+              <input
+                id="file-input"
+                type="file"
+                accept=".zip"
+                className="hidden"
+                onChange={handleFileInput}
+              />
 
-            {/* Icon */}
-            <div className={`
-              mx-auto w-20 h-20 mb-6
-              flex items-center justify-center
-              bg-gradient-to-br from-accent to-node-interface
-              rounded-2xl shadow-glow
-              transition-transform duration-300
-              ${isDragging ? 'scale-110' : ''}
-            `}>
-              {isDragging ? (
-                <Upload className="w-10 h-10 text-white" />
-              ) : (
-                <FileArchive className="w-10 h-10 text-white" />
-              )}
+              {/* Icon */}
+              <div className={`
+                mx-auto w-20 h-20 mb-6
+                flex items-center justify-center
+                bg-gradient-to-br from-accent to-node-interface
+                rounded-2xl shadow-glow
+                transition-transform duration-300
+                ${isDragging ? 'scale-110' : ''}
+              `}>
+                {isDragging ? (
+                  <Upload className="w-10 h-10 text-white" />
+                ) : (
+                  <FileArchive className="w-10 h-10 text-white" />
+                )}
+              </div>
+
+              {/* Text */}
+              <h2 className="text-xl font-semibold text-text-primary text-center mb-2">
+                {isDragging ? 'Drop it here!' : 'Drop your codebase'}
+              </h2>
+              <p className="text-sm text-text-secondary text-center mb-6">
+                Drag & drop a .zip file to generate a knowledge graph
+              </p>
+
+              {/* Hints */}
+              <div className="flex items-center justify-center gap-3 text-xs text-text-muted">
+                <span className="px-3 py-1.5 bg-elevated border border-border-subtle rounded-md">
+                  .zip
+                </span>
+              </div>
             </div>
 
-            {/* Text */}
-            <h2 className="text-xl font-semibold text-text-primary text-center mb-2">
-              {isDragging ? 'Drop it here!' : 'Drop your codebase'}
-            </h2>
-            <p className="text-sm text-text-secondary text-center mb-6">
-              Drag & drop a .zip file to generate a knowledge graph
-            </p>
-
-            {/* Hints */}
-            <div className="flex items-center justify-center gap-3 text-xs text-text-muted">
-              <span className="px-3 py-1.5 bg-elevated border border-border-subtle rounded-md">
-                .zip
-              </span>
+            {/* Smart Clustering Toggle - Below drop zone */}
+            <div className="mt-4 p-4 bg-surface/50 border border-border-subtle rounded-xl">
+              <label className="flex items-center justify-between cursor-pointer group">
+                <div className="flex-1">
+                  <div className="flex items-center gap-2 mb-1">
+                    <Sparkles className="w-4 h-4 text-accent" />
+                    <span className="text-sm font-medium text-text-primary">Enable Smart Clustering</span>
+                  </div>
+                  <p className="text-xs text-text-muted leading-relaxed">
+                    Uses LLM to label processes and clusters for better detection. Don't worry, it consumes very less tokens one time.
+                  </p>
+                  {!hasLLMProvider && (
+                    <p className="text-xs text-amber-400 mt-2">
+                      ⚠️ Setup LLM provider to enable smart clustering
+                    </p>
+                  )}
+                </div>
+                <button
+                  type="button"
+                  onClick={() => hasLLMProvider && setEnableSmartClustering(!enableSmartClustering)}
+                  disabled={!hasLLMProvider}
+                  className={`
+                  relative inline-flex h-6 w-11 items-center rounded-full transition-colors ml-4
+                  ${enableSmartClustering && hasLLMProvider ? 'bg-accent' : 'bg-gray-700'}
+                  ${!hasLLMProvider ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}
+                `}>
+                  <span
+                    className={`
+                    inline-block h-4 w-4 transform rounded-full bg-white transition-transform
+                    ${enableSmartClustering && hasLLMProvider ? 'translate-x-6' : 'translate-x-1'}
+                  `}
+                  />
+                </button>
+              </label>
             </div>
-          </div>
+          </>
         )}
 
         {/* GitHub URL Tab */}
@@ -302,11 +351,11 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
                 {isCloning ? (
                   <>
                     <Loader2 className="w-5 h-5 animate-spin" />
-                    {cloneProgress.phase === 'cloning' 
+                    {cloneProgress.phase === 'cloning'
                       ? `Cloning... ${cloneProgress.percent}%`
                       : cloneProgress.phase === 'reading'
-                      ? 'Reading files...'
-                      : 'Starting...'
+                        ? 'Reading files...'
+                        : 'Starting...'
                     }
                   </>
                 ) : (
@@ -322,7 +371,7 @@ export const DropZone = ({ onFileSelect, onGitClone }: DropZoneProps) => {
             {isCloning && (
               <div className="mt-4">
                 <div className="h-2 bg-elevated rounded-full overflow-hidden">
-                  <div 
+                  <div
                     className="h-full bg-accent transition-all duration-300 ease-out"
                     style={{ width: `${cloneProgress.percent}%` }}
                   />
diff --git a/gitnexus/src/components/GraphCanvas.tsx b/gitnexus/src/components/GraphCanvas.tsx
index 2bf4f1e68..118d386f9 100644
--- a/gitnexus/src/components/GraphCanvas.tsx
+++ b/gitnexus/src/components/GraphCanvas.tsx
@@ -115,7 +115,23 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
   // Update Sigma graph when KnowledgeGraph changes
   useEffect(() => {
     if (!graph) return;
-    const sigmaGraph = knowledgeGraphToGraphology(graph);
+
+    // Build communityMemberships map from MEMBER_OF relationships
+    // MEMBER_OF edges: nodeId -> communityId (stored as targetId)
+    const communityMemberships = new Map<string, number>();
+    graph.relationships.forEach(rel => {
+      if (rel.type === 'MEMBER_OF') {
+        // Find the community node to get its index
+        const communityNode = graph.nodes.find(n => n.id === rel.targetId && n.label === 'Community');
+        if (communityNode) {
+          // Extract community index from id (e.g., "comm_5" -> 5)
+          const communityIdx = parseInt(rel.targetId.replace('comm_', ''), 10) || 0;
+          communityMemberships.set(rel.sourceId, communityIdx);
+        }
+      }
+    });
+
+    const sigmaGraph = knowledgeGraphToGraphology(graph, communityMemberships);
     setSigmaGraph(sigmaGraph);
   }, [graph, setSigmaGraph]);
 
diff --git a/gitnexus/src/components/IntelligentClusteringModal.tsx b/gitnexus/src/components/IntelligentClusteringModal.tsx
new file mode 100644
index 000000000..ec9ab92a2
--- /dev/null
+++ b/gitnexus/src/components/IntelligentClusteringModal.tsx
@@ -0,0 +1,140 @@
+import { Brain, Sparkles, X, Settings } from 'lucide-react';
+
+interface IntelligentClusteringModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onEnable: () => void;
+    onConfigure: () => void;
+}
+
+export const IntelligentClusteringModal = ({
+    isOpen,
+    onClose,
+    onEnable,
+    onConfigure
+}: IntelligentClusteringModalProps) => {
+    if (!isOpen) return null;
+
+    // Parent handles all state updates via onEnable/onConfigure/onClose
+    const handleEnable = () => {
+        onEnable();
+    };
+
+    const handleSkip = () => {
+        onClose();
+    };
+
+
+    return (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+            {/* Backdrop */}
+            <div
+                className="absolute inset-0 bg-black/60 backdrop-blur-sm"
+                onClick={handleSkip}
+            />
+
+            {/* Modal Content */}
+            <div className="relative bg-surface border border-border-subtle rounded-2xl shadow-2xl max-w-md w-full overflow-hidden animate-in fade-in zoom-in-95 duration-200">
+
+                {/* Header with cool gradient background */}
+                <div className="bg-gradient-to-br from-accent/20 to-surface p-6 pb-8 border-b border-border-subtle/50 relative overflow-hidden">
+                    <div className="absolute top-0 right-0 p-4 opacity-10">
+                        <Brain className="w-32 h-32 rotate-12" />
+                    </div>
+
+                    <button
+                        onClick={handleSkip}
+                        className="absolute top-4 right-4 p-2 text-text-muted hover:text-text-primary rounded-full hover:bg-black/10 transition-colors"
+                    >
+                        <X className="w-5 h-5" />
+                    </button>
+
+                    <div className="flex items-center gap-3 mb-2">
+                        <div className="p-3 bg-accent text-white rounded-xl shadow-lg shadow-accent/20">
+                            <Sparkles className="w-6 h-6" />
+                        </div>
+                    </div>
+
+                    <h2 className="text-xl font-bold text-text-primary mt-4">
+                        Upgrade to Intelligent Clustering?
+                    </h2>
+                    <p className="text-text-secondary mt-1 text-sm leading-relaxed">
+                        Your clusters are ready, but they could be smarter! Right now they're just named after folders.
+                    </p>
+                </div>
+
+                {/* Body */}
+                <div className="p-6 space-y-6">
+
+                    <div className="space-y-3">
+                        <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
+                            <Brain className="w-4 h-4 text-accent" />
+                            What you get:
+                        </h3>
+                        <ul className="space-y-2 text-sm text-text-secondary">
+                            <li className="flex items-start gap-2">
+                                <span className="text-green-400 mt-1">✓</span>
+                                Semantic names (e.g., "Auth System" vs "utils")
+                            </li>
+                            <li className="flex items-start gap-2">
+                                <span className="text-green-400 mt-1">✓</span>
+                                Search keywords for better agent context
+                            </li>
+                            <li className="flex items-start gap-2">
+                                <span className="text-green-400 mt-1">✓</span>
+                                Descriptions of what the code actually does
+                            </li>
+                        </ul>
+                    </div>
+
+                    {/* How it works */}
+                    <div className="p-4 bg-elevated/50 border border-border-subtle rounded-xl">
+                        <div className="flex items-start gap-3">
+                            <div className="p-2 bg-blue-500/10 rounded-lg text-blue-400">
+                                <Brain className="w-4 h-4" />
+                            </div>
+                            <div>
+                                <h4 className="text-sm font-medium text-text-primary">Uses Your Configured LLM</h4>
+                                <p className="text-xs text-text-muted mt-1 leading-relaxed">
+                                    Runs on your own API key. Very low token usage (~$0.01 for most codebases).
+                                    <br />
+                                    <span className="text-amber-400">💡 Tip:</span> Use a cheaper model like GPT-4o-mini in settings!
+                                </p>
+                            </div>
+                        </div>
+                    </div>
+
+                </div>
+
+                {/* Actions */}
+                <div className="p-6 pt-2 bg-surface flex flex-col gap-3">
+                    <button
+                        onClick={handleEnable}
+                        className="w-full py-3 px-4 bg-accent text-white font-medium rounded-xl hover:bg-accent-dim shadow-lg shadow-accent/20 transition-all active:scale-[0.98] flex items-center justify-center gap-2"
+                    >
+                        <Sparkles className="w-4 h-4" />
+                        Enable Smart Clustering
+                    </button>
+
+                    <div className="flex bg-elevated rounded-xl p-1 gap-1">
+                        <button
+                            onClick={onConfigure}
+                            className="flex-1 py-2 px-3 text-sm font-medium text-text-secondary hover:text-text-primary hover:bg-hover rounded-lg transition-colors flex items-center justify-center gap-2"
+                        >
+                            <Settings className="w-3 h-3" />
+                            Configure Model
+                        </button>
+                        <div className="w-px bg-border-subtle my-2" />
+                        <button
+                            onClick={handleSkip}
+                            className="flex-1 py-2 px-3 text-sm font-medium text-text-muted hover:text-text-primary hover:bg-hover rounded-lg transition-colors"
+                        >
+                            No thanks (Free)
+                        </button>
+                    </div>
+                </div>
+
+            </div>
+        </div>
+    );
+};
diff --git a/gitnexus/src/components/SettingsPanel.tsx b/gitnexus/src/components/SettingsPanel.tsx
index 8d8874214..962bdef7c 100644
--- a/gitnexus/src/components/SettingsPanel.tsx
+++ b/gitnexus/src/components/SettingsPanel.tsx
@@ -1,5 +1,5 @@
 import { useState, useEffect, useCallback } from 'react';
-import { X, Key, Server, Brain, Check, AlertCircle, Eye, EyeOff, RefreshCw } from 'lucide-react';
+import { X, Key, Server, Brain, Check, AlertCircle, Eye, EyeOff, RefreshCw, Sparkles } from 'lucide-react';
 import {
   loadSettings,
   saveSettings,
@@ -534,6 +534,147 @@ export const SettingsPanel = ({ isOpen, onClose, onSettingsSaved }: SettingsPane
             </div>
           )}
 
+
+          {/* Intelligent Clustering Settings */}
+          <div className="space-y-4 animate-fade-in pt-2 border-t border-border-subtle">
+            <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
+              <Sparkles className="w-4 h-4 text-accent" />
+              Intelligent Clustering (Beta)
+            </h3>
+
+            <div className="p-4 bg-elevated/50 border border-border-subtle rounded-xl space-y-4">
+              <div className="flex items-center justify-between">
+                <div>
+                  <label className="text-sm font-medium text-text-primary">Enable AI Enrichment</label>
+                  <p className="text-xs text-text-muted">Generate semantic names and descriptions for code clusters</p>
+                </div>
+                <button
+                  onClick={() => setSettings(prev => ({ ...prev, intelligentClustering: !prev.intelligentClustering }))}
+                  className={`
+                    relative inline-flex h-6 w-11 items-center rounded-full transition-colors
+                    ${settings.intelligentClustering ? 'bg-accent' : 'bg-gray-700'}
+                  `}
+                >
+                  <span
+                    className={`
+                      inline-block h-4 w-4 transform rounded-full bg-white transition-transform
+                      ${settings.intelligentClustering ? 'translate-x-6' : 'translate-x-1'}
+                    `}
+                  />
+                </button>
+              </div>
+
+              {settings.intelligentClustering && (
+                <div className="space-y-4 animate-fade-in pl-1">
+                  <div className="flex items-center justify-between">
+                    <div>
+                      <label className="text-sm font-medium text-text-secondary">Use Agent Model</label>
+                      <p className="text-xs text-text-muted">Use the same provider configured above</p>
+                    </div>
+                    <button
+                      onClick={() => setSettings(prev => ({ ...prev, useSameModelForClustering: !prev.useSameModelForClustering }))}
+                      className={`
+                        relative inline-flex h-6 w-11 items-center rounded-full transition-colors
+                        ${settings.useSameModelForClustering ? 'bg-accent/70' : 'bg-gray-700'}
+                      `}
+                    >
+                      <span
+                        className={`
+                          inline-block h-4 w-4 transform rounded-full bg-white transition-transform
+                          ${settings.useSameModelForClustering ? 'translate-x-6' : 'translate-x-1'}
+                        `}
+                      />
+                    </button>
+                  </div>
+
+                  {!settings.useSameModelForClustering && (
+                    <div className="space-y-3 pt-2 bg-black/20 p-3 rounded-lg">
+                      <div className="flex items-center gap-2 mb-2">
+                        <div className="p-1 bg-amber-500/10 rounded text-amber-400">
+                          <Brain className="w-3 h-3" />
+                        </div>
+                        <p className="text-xs text-amber-300">
+                          <span className="font-semibold">Pro Tip:</span> Use a cheaper model like GPT-4o-mini or Gemini Flash for clustering!
+                        </p>
+                      </div>
+
+                      {/* Simplistic Clustering Provider Config - For now just a model name override for simplicity, 
+                          or we could duplicate the provider selector. 
+                          For key simplicity in this iteration, let's just let them override the MODEL name if using the SAME provider, 
+                          or we can add a provider dropdown. 
+                          
+                          Actually, the simplest implementation for "separate model" is just allowing them to pick a provider/model 
+                          for clustering specifically. But that replicates a lot of UI.
+                          
+                          Let's stick to the plan: "Use same model as agent" vs "Use different model".
+                          If different, show a simplified provider config (just Provider + Model + Key if needed).
+                          
+                          For MVP, let's just assume they want to use OpenAI/Azure/Gemini with a specific model string.
+                      */}
+
+                      <div className="space-y-2">
+                        <label className="block text-sm font-medium text-text-secondary">
+                          Clustering Provider
+                        </label>
+                        <select
+                          value={settings.clusteringProvider?.provider || settings.activeProvider}
+                          onChange={(e) => setSettings(prev => ({
+                            ...prev,
+                            clusteringProvider: {
+                              ...prev.clusteringProvider,
+                              provider: e.target.value as any
+                            }
+                          }))}
+                          className="w-full px-3 py-2 bg-elevated border border-border-subtle rounded-lg text-sm text-text-primary outline-none"
+                        >
+                          {providers.map(p => (
+                            <option key={p} value={p}>{getProviderDisplayName(p)}</option>
+                          ))}
+                        </select>
+                      </div>
+
+                      <div className="space-y-2">
+                        <label className="block text-sm font-medium text-text-secondary">
+                          Model Name
+                        </label>
+                        <input
+                          type="text"
+                          value={settings.clusteringProvider?.model || ''}
+                          onChange={e => setSettings(prev => ({
+                            ...prev,
+                            clusteringProvider: { ...prev.clusteringProvider, model: e.target.value }
+                          }))}
+                          placeholder="e.g. gpt-4o-mini"
+                          className="w-full px-3 py-2 bg-elevated border border-border-subtle rounded-lg text-sm text-text-primary placeholder:text-text-muted outline-none"
+                        />
+                      </div>
+
+                      <div className="space-y-2">
+                        <label className="block text-sm font-medium text-text-secondary">
+                          API Key (Optional)
+                        </label>
+                        <input
+                          type="password"
+                          value={(settings.clusteringProvider as any)?.apiKey || ''}
+                          onChange={e => setSettings(prev => ({
+                            ...prev,
+                            clusteringProvider: { ...prev.clusteringProvider, apiKey: e.target.value }
+                          }))}
+                          placeholder="Leave blank to use main key if matching..."
+                          className="w-full px-3 py-2 bg-elevated border border-border-subtle rounded-lg text-sm text-text-primary placeholder:text-text-muted outline-none"
+                        />
+                      </div>
+
+                      <p className="text-xs text-text-muted">
+                        Required if using a different provider than your main agent.
+                      </p>
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+
           {/* Privacy Note */}
           <div className="p-4 bg-elevated/50 border border-border-subtle rounded-xl">
             <div className="flex gap-3">
diff --git a/gitnexus/src/components/StatusBar.tsx b/gitnexus/src/components/StatusBar.tsx
index 93b6daa09..476f4ecb8 100644
--- a/gitnexus/src/components/StatusBar.tsx
+++ b/gitnexus/src/components/StatusBar.tsx
@@ -1,7 +1,8 @@
+import { Pause, X } from 'lucide-react';
 import { useAppState } from '../hooks/useAppState';
 
 export const StatusBar = () => {
-  const { graph, progress } = useAppState();
+  const { graph, progress, enrichmentProgress, cancelEnrichment } = useAppState();
 
   const nodeCount = graph?.nodes.length ?? 0;
   const edgeCount = graph?.relationships.length ?? 0;
@@ -13,15 +14,17 @@ export const StatusBar = () => {
       .map(n => n.properties.language)
       .filter(Boolean);
     if (languages.length === 0) return null;
-    
+
     const counts = languages.reduce((acc, lang) => {
       acc[lang!] = (acc[lang!] || 0) + 1;
       return acc;
     }, {} as Record<string, number>);
-    
+
     return Object.entries(counts).sort((a, b) => b[1] - a[1])[0]?.[0];
   })();
 
+  const isLabeling = enrichmentProgress !== null;
+
   return (
     <footer className="flex items-center justify-between px-5 py-2 bg-deep border-t border-dashed border-border-subtle text-[11px] text-text-muted">
       {/* Left - Status */}
@@ -29,13 +32,31 @@ export const StatusBar = () => {
         {progress && progress.phase !== 'complete' ? (
           <>
             <div className="w-28 h-1 bg-elevated rounded-full overflow-hidden">
-              <div 
+              <div
                 className="h-full bg-gradient-to-r from-accent to-node-interface rounded-full transition-all duration-300"
                 style={{ width: `${progress.percent}%` }}
               />
             </div>
             <span>{progress.message}</span>
           </>
+        ) : isLabeling ? (
+          <>
+            <div className="w-28 h-1 bg-elevated rounded-full overflow-hidden">
+              <div
+                className="h-full bg-gradient-to-r from-node-interface to-accent rounded-full transition-all duration-300"
+                style={{ width: `${(enrichmentProgress.current / enrichmentProgress.total) * 100}%` }}
+              />
+            </div>
+            <span>Labeling clusters {enrichmentProgress.current}/{enrichmentProgress.total}...</span>
+            <button
+              onClick={() => cancelEnrichment()}
+              className="flex items-center gap-1 px-2 py-0.5 text-[10px] bg-elevated hover:bg-border-subtle rounded transition-colors"
+              title="Stop LLM labeling and use heuristic labels"
+            >
+              <X size={12} />
+              Stop
+            </button>
+          </>
         ) : (
           <div className="flex items-center gap-1.5">
             <span className="w-1.5 h-1.5 bg-node-function rounded-full" />
@@ -63,4 +84,3 @@ export const StatusBar = () => {
     </footer>
   );
 };
-
diff --git a/gitnexus/src/config/supported-languages.ts b/gitnexus/src/config/supported-languages.ts
index bc7870622..15df37c54 100644
--- a/gitnexus/src/config/supported-languages.ts
+++ b/gitnexus/src/config/supported-languages.ts
@@ -2,12 +2,12 @@ export enum SupportedLanguages {
     JavaScript = 'javascript',
     TypeScript = 'typescript',
     Python = 'python',
-    // Java = 'java',
-    // C = 'c',
-    // CPlusPlus = 'cpp',
-    // CSharp = 'csharp',
-    // Go = 'go',
-    // Rust = 'rust',
+    Java = 'java',
+    C = 'c',
+    CPlusPlus = 'cpp',
+    CSharp = 'csharp',
+    Go = 'go',
+    Rust = 'rust',
     // PHP = 'php',
     // Ruby = 'ruby',
     // Swift = 'swift',
diff --git a/gitnexus/src/core/graph/types.ts b/gitnexus/src/core/graph/types.ts
index eb4e81c2a..1e8fa2037 100644
--- a/gitnexus/src/core/graph/types.ts
+++ b/gitnexus/src/core/graph/types.ts
@@ -13,7 +13,8 @@ export type NodeLabel =
   | 'Decorator'
   | 'Import'
   | 'Type'
-  | 'CodeElement';
+  | 'CodeElement'
+  | 'Community';
 
 
 export type NodeProperties = {
@@ -23,6 +24,13 @@ export type NodeProperties = {
   endLine?: number,
   language?: string,
   isExported?: boolean,
+  // Community-specific properties
+  heuristicLabel?: string,
+  cohesion?: number,
+  symbolCount?: number,
+  keywords?: string[],
+  description?: string,
+  enrichedBy?: 'heuristic' | 'llm',
 }
 
 export type RelationshipType = 
@@ -36,6 +44,7 @@ export type RelationshipType =
   | 'DECORATES'
   | 'IMPLEMENTS'
   | 'EXTENDS'
+  | 'MEMBER_OF'
 
 export interface GraphNode {
   id:  string,
diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts
index 77a7ef747..d0ac9b22e 100644
--- a/gitnexus/src/core/ingestion/call-processor.ts
+++ b/gitnexus/src/core/ingestion/call-processor.ts
@@ -23,6 +23,17 @@ const FUNCTION_NODE_TYPES = new Set([
   // Common async variants
   'async_function_declaration',
   'async_arrow_function',
+  // Java
+  'method_declaration',
+  'constructor_declaration',
+  // C/C++
+  // 'function_definition' already included above
+  // Go
+  // 'method_declaration' already included from Java
+  // C#
+  'local_function_statement',
+  // Rust
+  'function_item',
 ]);
 
 /**
diff --git a/gitnexus/src/core/ingestion/cluster-enricher.ts b/gitnexus/src/core/ingestion/cluster-enricher.ts
new file mode 100644
index 000000000..51e00d618
--- /dev/null
+++ b/gitnexus/src/core/ingestion/cluster-enricher.ts
@@ -0,0 +1,245 @@
+/**
+ * Cluster Enricher
+ * 
+ * LLM-based enrichment for community clusters.
+ * Generates semantic names, keywords, and descriptions using an LLM.
+ */
+
+import { CommunityNode } from './community-processor';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ClusterEnrichment {
+  name: string;
+  keywords: string[];
+  description: string;
+}
+
+export interface EnrichmentResult {
+  enrichments: Map<string, ClusterEnrichment>;
+  tokensUsed: number;
+}
+
+export interface LLMClient {
+  generate: (prompt: string) => Promise<string>;
+}
+
+export interface ClusterMemberInfo {
+  name: string;
+  filePath: string;
+  type: string; // 'Function' | 'Class' | 'Method' | 'Interface'
+}
+
+// ============================================================================
+// PROMPT TEMPLATE
+// ============================================================================
+
+const buildEnrichmentPrompt = (
+  members: ClusterMemberInfo[],
+  heuristicLabel: string
+): string => {
+  // Limit to first 20 members to control token usage
+  const limitedMembers = members.slice(0, 20);
+  
+  const memberList = limitedMembers
+    .map(m => `${m.name} (${m.type})`)
+    .join(', ');
+  
+  return `Analyze this code cluster and provide a semantic name and short description.
+
+Heuristic: "${heuristicLabel}"
+Members: ${memberList}${members.length > 20 ? ` (+${members.length - 20} more)` : ''}
+
+Reply with JSON only:
+{"name": "2-4 word semantic name", "description": "One sentence describing purpose"}`
+};
+
+// ============================================================================
+// PARSE LLM RESPONSE
+// ============================================================================
+
+const parseEnrichmentResponse = (
+  response: string,
+  fallbackLabel: string
+): ClusterEnrichment => {
+  try {
+    // Extract JSON from response (handles markdown code blocks)
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      throw new Error('No JSON found in response');
+    }
+    
+    const parsed = JSON.parse(jsonMatch[0]);
+    
+    return {
+      name: parsed.name || fallbackLabel,
+      keywords: Array.isArray(parsed.keywords) ? parsed.keywords : [],
+      description: parsed.description || '',
+    };
+  } catch {
+    // Fallback if parsing fails
+    return {
+      name: fallbackLabel,
+      keywords: [],
+      description: '',
+    };
+  }
+};
+
+// ============================================================================
+// MAIN ENRICHMENT FUNCTION
+// ============================================================================
+
+/**
+ * Enrich clusters with LLM-generated names, keywords, and descriptions
+ * 
+ * @param communities - Community nodes to enrich
+ * @param memberMap - Map of communityId -> member info
+ * @param llmClient - LLM client for generation
+ * @param onProgress - Progress callback
+ */
+export const enrichClusters = async (
+  communities: CommunityNode[],
+  memberMap: Map<string, ClusterMemberInfo[]>,
+  llmClient: LLMClient,
+  onProgress?: (current: number, total: number) => void
+): Promise<EnrichmentResult> => {
+  const enrichments = new Map<string, ClusterEnrichment>();
+  let tokensUsed = 0;
+  
+  for (let i = 0; i < communities.length; i++) {
+    const community = communities[i];
+    const members = memberMap.get(community.id) || [];
+    
+    onProgress?.(i + 1, communities.length);
+    
+    if (members.length === 0) {
+      // No members, use heuristic
+      enrichments.set(community.id, {
+        name: community.heuristicLabel,
+        keywords: [],
+        description: '',
+      });
+      continue;
+    }
+    
+    try {
+      const prompt = buildEnrichmentPrompt(members, community.heuristicLabel);
+      const response = await llmClient.generate(prompt);
+      
+      // Rough token estimate
+      tokensUsed += prompt.length / 4 + response.length / 4;
+      
+      const enrichment = parseEnrichmentResponse(response, community.heuristicLabel);
+      enrichments.set(community.id, enrichment);
+    } catch (error) {
+      // On error, fallback to heuristic
+      console.warn(`Failed to enrich cluster ${community.id}:`, error);
+      enrichments.set(community.id, {
+        name: community.heuristicLabel,
+        keywords: [],
+        description: '',
+      });
+    }
+  }
+  
+  return { enrichments, tokensUsed };
+};
+
+// ============================================================================
+// BATCH ENRICHMENT (more efficient)
+// ============================================================================
+
+/**
+ * Enrich multiple clusters in a single LLM call (batch mode)
+ * More efficient for token usage but requires larger context window
+ */
+export const enrichClustersBatch = async (
+  communities: CommunityNode[],
+  memberMap: Map<string, ClusterMemberInfo[]>,
+  llmClient: LLMClient,
+  batchSize: number = 5,
+  onProgress?: (current: number, total: number) => void
+): Promise<EnrichmentResult> => {
+  const enrichments = new Map<string, ClusterEnrichment>();
+  let tokensUsed = 0;
+  
+  // Process in batches
+  for (let i = 0; i < communities.length; i += batchSize) {
+    // Report progress
+    onProgress?.(Math.min(i + batchSize, communities.length), communities.length);
+
+    const batch = communities.slice(i, i + batchSize);
+    
+    const batchPrompt = batch.map((community, idx) => {
+      const members = memberMap.get(community.id) || [];
+      const limitedMembers = members.slice(0, 15);
+      const memberList = limitedMembers
+        .map(m => `${m.name} (${m.type})`)
+        .join(', ');
+      
+      return `Cluster ${idx + 1} (id: ${community.id}):
+Heuristic: "${community.heuristicLabel}"
+Members: ${memberList}`;
+    }).join('\n\n');
+    
+    const prompt = `Analyze these code clusters and generate semantic names, keywords, and descriptions.
+
+${batchPrompt}
+
+Output JSON array:
+[
+  {"id": "comm_X", "name": "...", "keywords": [...], "description": "..."},
+  ...
+]`;
+    
+    try {
+      const response = await llmClient.generate(prompt);
+      tokensUsed += prompt.length / 4 + response.length / 4;
+      
+      // Parse batch response
+      const jsonMatch = response.match(/\[[\s\S]*\]/);
+      if (jsonMatch) {
+        const parsed = JSON.parse(jsonMatch[0]) as Array<{
+          id: string;
+          name: string;
+          keywords: string[];
+          description: string;
+        }>;
+        
+        for (const item of parsed) {
+          enrichments.set(item.id, {
+            name: item.name,
+            keywords: item.keywords || [],
+            description: item.description || '',
+          });
+        }
+      }
+    } catch (error) {
+      console.warn('Batch enrichment failed, falling back to heuristics:', error);
+      // Fallback for this batch
+      for (const community of batch) {
+        enrichments.set(community.id, {
+          name: community.heuristicLabel,
+          keywords: [],
+          description: '',
+        });
+      }
+    }
+  }
+  
+  // Fill in any missing communities
+  for (const community of communities) {
+    if (!enrichments.has(community.id)) {
+      enrichments.set(community.id, {
+        name: community.heuristicLabel,
+        keywords: [],
+        description: '',
+      });
+    }
+  }
+  
+  return { enrichments, tokensUsed };
+};
diff --git a/gitnexus/src/core/ingestion/community-processor.ts b/gitnexus/src/core/ingestion/community-processor.ts
new file mode 100644
index 000000000..1a8901acc
--- /dev/null
+++ b/gitnexus/src/core/ingestion/community-processor.ts
@@ -0,0 +1,354 @@
+/**
+ * Community Detection Processor
+ * 
+ * Uses the Leiden algorithm (via graphology-communities-louvain) to detect
+ * communities/clusters in the code graph based on CALLS relationships.
+ * 
+ * Communities represent groups of code that work together frequently,
+ * helping agents navigate the codebase by functional area rather than file structure.
+ */
+
+import Graph from 'graphology';
+import louvain from 'graphology-communities-louvain';
+import { KnowledgeGraph, NodeLabel } from '../graph/types';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface CommunityNode {
+  id: string;
+  label: string;
+  heuristicLabel: string;
+  cohesion: number;
+  symbolCount: number;
+}
+
+export interface CommunityMembership {
+  nodeId: string;
+  communityId: string;
+}
+
+export interface CommunityDetectionResult {
+  communities: CommunityNode[];
+  memberships: CommunityMembership[];
+  stats: {
+    totalCommunities: number;
+    modularity: number;
+    nodesProcessed: number;
+  };
+}
+
+// ============================================================================
+// COMMUNITY COLORS (for visualization)
+// ============================================================================
+
+export const COMMUNITY_COLORS = [
+  '#ef4444', // red
+  '#f97316', // orange
+  '#eab308', // yellow
+  '#22c55e', // green
+  '#06b6d4', // cyan
+  '#3b82f6', // blue
+  '#8b5cf6', // violet
+  '#d946ef', // fuchsia
+  '#ec4899', // pink
+  '#f43f5e', // rose
+  '#14b8a6', // teal
+  '#84cc16', // lime
+];
+
+export const getCommunityColor = (communityIndex: number): string => {
+  return COMMUNITY_COLORS[communityIndex % COMMUNITY_COLORS.length];
+};
+
+// ============================================================================
+// MAIN PROCESSOR
+// ============================================================================
+
+/**
+ * Detect communities in the knowledge graph using Leiden algorithm
+ * 
+ * This runs AFTER all relationships (CALLS, IMPORTS, etc.) have been built.
+ * It uses primarily CALLS edges to cluster code that works together.
+ */
+export const processCommunities = async (
+  knowledgeGraph: KnowledgeGraph,
+  onProgress?: (message: string, progress: number) => void
+): Promise<CommunityDetectionResult> => {
+  onProgress?.('Building graph for community detection...', 0);
+
+  // Step 1: Build a graphology graph from the knowledge graph
+  // We only include symbol nodes (Function, Class, Method) and CALLS edges
+  const graph = buildGraphologyGraph(knowledgeGraph);
+  
+  if (graph.order === 0) {
+    // No nodes to cluster
+    return {
+      communities: [],
+      memberships: [],
+      stats: { totalCommunities: 0, modularity: 0, nodesProcessed: 0 }
+    };
+  }
+
+  onProgress?.(`Running Leiden algorithm on ${graph.order} nodes...`, 30);
+
+  // Step 2: Run Leiden (via Louvain implementation with refinement)
+  const details = louvain.detailed(graph, {
+    resolution: 1.0,  // Default resolution, can be tuned
+    randomWalk: true,
+  });
+
+  onProgress?.(`Found ${details.count} communities...`, 60);
+
+  // Step 3: Create community nodes with heuristic labels
+  const communityNodes = createCommunityNodes(
+    details.communities as Record<string, number>,
+    details.count,
+    graph,
+    knowledgeGraph
+  );
+
+  onProgress?.('Creating membership edges...', 80);
+
+  // Step 4: Create membership mappings
+  const memberships: CommunityMembership[] = [];
+  Object.entries(details.communities).forEach(([nodeId, communityNum]) => {
+    memberships.push({
+      nodeId,
+      communityId: `comm_${communityNum}`,
+    });
+  });
+
+  onProgress?.('Community detection complete!', 100);
+
+  return {
+    communities: communityNodes,
+    memberships,
+    stats: {
+      totalCommunities: details.count,
+      modularity: details.modularity,
+      nodesProcessed: graph.order,
+    }
+  };
+};
+
+// ============================================================================
+// HELPER: Build graphology graph from knowledge graph
+// ============================================================================
+
+/**
+ * Build a graphology graph containing only symbol nodes and CALLS edges
+ * This is what the Leiden algorithm will cluster
+ */
+const buildGraphologyGraph = (knowledgeGraph: KnowledgeGraph): Graph => {
+  // Use undirected graph for Leiden - it looks at edge density, not direction
+  const graph = new Graph({ type: 'undirected', allowSelfLoops: false });
+
+  // Symbol types that should be clustered
+  const symbolTypes = new Set<NodeLabel>(['Function', 'Class', 'Method', 'Interface']);
+  
+  // Add symbol nodes
+  knowledgeGraph.nodes.forEach(node => {
+    if (symbolTypes.has(node.label)) {
+      graph.addNode(node.id, {
+        name: node.properties.name,
+        filePath: node.properties.filePath,
+        type: node.label,
+      });
+    }
+  });
+
+  // Add CALLS edges (primary clustering signal)
+  // We can also include EXTENDS/IMPLEMENTS for OOP clustering
+  const clusteringRelTypes = new Set(['CALLS', 'EXTENDS', 'IMPLEMENTS']);
+  
+  knowledgeGraph.relationships.forEach(rel => {
+    if (clusteringRelTypes.has(rel.type)) {
+      // Only add edge if both nodes exist in our symbol graph
+      // Also skip self-loops (recursive calls) - not allowed in undirected graph
+      if (graph.hasNode(rel.sourceId) && graph.hasNode(rel.targetId) && rel.sourceId !== rel.targetId) {
+        // Avoid duplicate edges
+        if (!graph.hasEdge(rel.sourceId, rel.targetId)) {
+          graph.addEdge(rel.sourceId, rel.targetId);
+        }
+      }
+    }
+  });
+
+  return graph;
+};
+
+// ============================================================================
+// HELPER: Create community nodes with heuristic labels
+// ============================================================================
+
+/**
+ * Create Community nodes with auto-generated labels based on member file paths
+ */
+const createCommunityNodes = (
+  communities: Record<string, number>,
+  communityCount: number,
+  graph: Graph,
+  knowledgeGraph: KnowledgeGraph
+): CommunityNode[] => {
+  // Group node IDs by community
+  const communityMembers = new Map<number, string[]>();
+  
+  Object.entries(communities).forEach(([nodeId, commNum]) => {
+    if (!communityMembers.has(commNum)) {
+      communityMembers.set(commNum, []);
+    }
+    communityMembers.get(commNum)!.push(nodeId);
+  });
+
+  // Build node lookup for file paths
+  const nodePathMap = new Map<string, string>();
+  knowledgeGraph.nodes.forEach(node => {
+    if (node.properties.filePath) {
+      nodePathMap.set(node.id, node.properties.filePath);
+    }
+  });
+
+  // Create community nodes - SKIP SINGLETONS (isolated nodes)
+  const communityNodes: CommunityNode[] = [];
+  
+  communityMembers.forEach((memberIds, commNum) => {
+    // Skip singleton communities - they're just isolated nodes
+    if (memberIds.length < 2) return;
+    
+    const heuristicLabel = generateHeuristicLabel(memberIds, nodePathMap, graph, commNum);
+    
+    communityNodes.push({
+      id: `comm_${commNum}`,
+      label: heuristicLabel,
+      heuristicLabel,
+      cohesion: calculateCohesion(memberIds, graph),
+      symbolCount: memberIds.length,
+    });
+  });
+
+  // Sort by size descending
+  communityNodes.sort((a, b) => b.symbolCount - a.symbolCount);
+
+  return communityNodes;
+};
+
+// ============================================================================
+// HELPER: Generate heuristic label from folder patterns
+// ============================================================================
+
+/**
+ * Generate a human-readable label from the most common folder name in the community
+ */
+const generateHeuristicLabel = (
+  memberIds: string[],
+  nodePathMap: Map<string, string>,
+  graph: Graph,
+  commNum: number
+): string => {
+  // Collect folder names from file paths
+  const folderCounts = new Map<string, number>();
+  
+  memberIds.forEach(nodeId => {
+    const filePath = nodePathMap.get(nodeId) || '';
+    const parts = filePath.split('/').filter(Boolean);
+    
+    // Get the most specific folder (parent directory)
+    if (parts.length >= 2) {
+      const folder = parts[parts.length - 2];
+      // Skip generic folder names
+      if (!['src', 'lib', 'core', 'utils', 'common', 'shared', 'helpers'].includes(folder.toLowerCase())) {
+        folderCounts.set(folder, (folderCounts.get(folder) || 0) + 1);
+      }
+    }
+  });
+
+  // Find most common folder
+  let maxCount = 0;
+  let bestFolder = '';
+  
+  folderCounts.forEach((count, folder) => {
+    if (count > maxCount) {
+      maxCount = count;
+      bestFolder = folder;
+    }
+  });
+
+  if (bestFolder) {
+    // Capitalize first letter
+    return bestFolder.charAt(0).toUpperCase() + bestFolder.slice(1);
+  }
+
+  // Fallback: use function names to detect patterns
+  const names: string[] = [];
+  memberIds.forEach(nodeId => {
+    const name = graph.getNodeAttribute(nodeId, 'name');
+    if (name) names.push(name);
+  });
+
+  // Look for common prefixes
+  if (names.length > 2) {
+    const commonPrefix = findCommonPrefix(names);
+    if (commonPrefix.length > 2) {
+      return commonPrefix.charAt(0).toUpperCase() + commonPrefix.slice(1);
+    }
+  }
+
+  // Last resort: generic name with community ID for uniqueness
+  return `Cluster_${commNum}`;
+};
+
+/**
+ * Find common prefix among strings
+ */
+const findCommonPrefix = (strings: string[]): string => {
+  if (strings.length === 0) return '';
+  
+  const sorted = strings.slice().sort();
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  
+  let i = 0;
+  while (i < first.length && first[i] === last[i]) {
+    i++;
+  }
+  
+  return first.substring(0, i);
+};
+
+// ============================================================================
+// HELPER: Calculate community cohesion
+// ============================================================================
+
+/**
+ * Calculate cohesion score (0-1) based on internal edge density
+ * Higher cohesion = more internal connections relative to size
+ */
+const calculateCohesion = (memberIds: string[], graph: Graph): number => {
+  if (memberIds.length <= 1) return 1.0;
+
+  const memberSet = new Set(memberIds);
+  let internalEdges = 0;
+  
+  // Count edges within the community
+  memberIds.forEach(nodeId => {
+    if (graph.hasNode(nodeId)) {
+      graph.forEachNeighbor(nodeId, neighbor => {
+        if (memberSet.has(neighbor)) {
+          internalEdges++;
+        }
+      });
+    }
+  });
+  
+  // Each edge is counted twice (once from each end), so divide by 2
+  internalEdges = internalEdges / 2;
+  
+  // Maximum possible internal edges for n nodes: n*(n-1)/2
+  const maxPossibleEdges = (memberIds.length * (memberIds.length - 1)) / 2;
+  
+  if (maxPossibleEdges === 0) return 1.0;
+  
+  return Math.min(1.0, internalEdges / maxPossibleEdges);
+};
diff --git a/gitnexus/src/core/ingestion/heritage-processor.ts b/gitnexus/src/core/ingestion/heritage-processor.ts
index 1abdece66..378a3bdd1 100644
--- a/gitnexus/src/core/ingestion/heritage-processor.ts
+++ b/gitnexus/src/core/ingestion/heritage-processor.ts
@@ -117,6 +117,33 @@ export const processHeritage = async (
           });
         }
       }
+
+      // IMPLEMENTS (Rust): impl Trait for Struct
+      if (captureMap['heritage.trait'] && captureMap['heritage.class']) {
+        const structName = captureMap['heritage.class'].text;
+        const traitName = captureMap['heritage.trait'].text;
+
+        // Resolve struct and trait IDs
+        const structId = symbolTable.lookupExact(file.path, structName) ||
+                         symbolTable.lookupFuzzy(structName)[0]?.nodeId ||
+                         generateId('Struct', `${file.path}:${structName}`);
+        
+        const traitId = symbolTable.lookupFuzzy(traitName)[0]?.nodeId ||
+                        generateId('Trait', `${traitName}`);
+
+        if (structId && traitId) {
+          const relId = generateId('IMPLEMENTS', `${structId}->${traitId}`);
+          
+          graph.addRelationship({
+            id: relId,
+            sourceId: structId,
+            targetId: traitId,
+            type: 'IMPLEMENTS',
+            confidence: 1.0,
+            reason: 'trait-impl',
+          });
+        }
+      }
     });
 
     // Cleanup
diff --git a/gitnexus/src/core/ingestion/import-processor.ts b/gitnexus/src/core/ingestion/import-processor.ts
index 9edc7d358..0dd9b4893 100644
--- a/gitnexus/src/core/ingestion/import-processor.ts
+++ b/gitnexus/src/core/ingestion/import-processor.ts
@@ -35,8 +35,24 @@ const resolveImportPath = (
   
   const basePath = currentDir.join('/');
 
-  // 3. Try extensions (prioritize .tsx for React projects)
-  const extensions = ['', '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js'];
+  // 3. Try extensions for all supported languages
+  const extensions = [
+    '', 
+    // TypeScript/JavaScript
+    '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js',
+    // Python
+    '.py', '/__init__.py',
+    // Java
+    '.java',
+    // C/C++
+    '.c', '.h', '.cpp', '.hpp', '.cc', '.cxx', '.hxx', '.hh',
+    // C#
+    '.cs',
+    // Go
+    '.go',
+    // Rust
+    '.rs', '/mod.rs'
+  ];
   
   for (const ext of extensions) {
     const candidate = basePath + ext;
diff --git a/gitnexus/src/core/ingestion/parsing-processor.ts b/gitnexus/src/core/ingestion/parsing-processor.ts
index 0b5546ce9..79d53216e 100644
--- a/gitnexus/src/core/ingestion/parsing-processor.ts
+++ b/gitnexus/src/core/ingestion/parsing-processor.ts
@@ -81,10 +81,37 @@ export const processParsing = async (
       
       let nodeLabel = 'CodeElement';
       
+      // Core types
       if (captureMap['definition.function']) nodeLabel = 'Function';
       else if (captureMap['definition.class']) nodeLabel = 'Class';
       else if (captureMap['definition.interface']) nodeLabel = 'Interface';
       else if (captureMap['definition.method']) nodeLabel = 'Method';
+      // Struct types (C, C++, Go, Rust, C#)
+      else if (captureMap['definition.struct']) nodeLabel = 'Struct';
+      // Enum types
+      else if (captureMap['definition.enum']) nodeLabel = 'Enum';
+      // Namespace/Module (C++, C#, Rust)
+      else if (captureMap['definition.namespace']) nodeLabel = 'Namespace';
+      else if (captureMap['definition.module']) nodeLabel = 'Module';
+      // Rust-specific
+      else if (captureMap['definition.trait']) nodeLabel = 'Trait';
+      else if (captureMap['definition.impl']) nodeLabel = 'Impl';
+      else if (captureMap['definition.type']) nodeLabel = 'TypeAlias';
+      else if (captureMap['definition.const']) nodeLabel = 'Const';
+      else if (captureMap['definition.static']) nodeLabel = 'Static';
+      // C-specific
+      else if (captureMap['definition.typedef']) nodeLabel = 'Typedef';
+      else if (captureMap['definition.macro']) nodeLabel = 'Macro';
+      else if (captureMap['definition.union']) nodeLabel = 'Union';
+      // C#-specific
+      else if (captureMap['definition.property']) nodeLabel = 'Property';
+      else if (captureMap['definition.record']) nodeLabel = 'Record';
+      else if (captureMap['definition.delegate']) nodeLabel = 'Delegate';
+      // Java-specific
+      else if (captureMap['definition.annotation']) nodeLabel = 'Annotation';
+      else if (captureMap['definition.constructor']) nodeLabel = 'Constructor';
+      // C++ template
+      else if (captureMap['definition.template']) nodeLabel = 'Template';
 
       const nodeId = generateId(nodeLabel, `${file.path}:${nodeName}`);
       
diff --git a/gitnexus/src/core/ingestion/pipeline.ts b/gitnexus/src/core/ingestion/pipeline.ts
index d598c3f28..a273d1a5d 100644
--- a/gitnexus/src/core/ingestion/pipeline.ts
+++ b/gitnexus/src/core/ingestion/pipeline.ts
@@ -5,6 +5,7 @@ import { processParsing } from './parsing-processor';
 import { processImports, createImportMap } from './import-processor';
 import { processCalls } from './call-processor';
 import { processHeritage } from './heritage-processor';
+import { processCommunities, CommunityDetectionResult } from './community-processor';
 import { createSymbolTable } from './symbol-table';
 import { createASTCache } from './ast-cache';
 import { PipelineProgress, PipelineResult } from '../../types/pipeline';
@@ -150,7 +151,7 @@ export const runPipelineFromFiles = async (
   });
 
   await processHeritage(graph, files, astCache, symbolTable, (current, total) => {
-    const heritageProgress = 92 + ((current / total) * 6);
+    const heritageProgress = 88 + ((current / total) * 4);
     onProgress({
       phase: 'heritage',
       percent: Math.round(heritageProgress),
@@ -159,12 +160,62 @@ export const runPipelineFromFiles = async (
     });
   });
 
+  // Phase 7: Community Detection (92-98%)
+  onProgress({
+    phase: 'communities',
+    percent: 92,
+    message: 'Detecting code communities...',
+    stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+
+  const communityResult = await processCommunities(graph, (message, progress) => {
+    const communityProgress = 92 + (progress * 0.06);
+    onProgress({
+      phase: 'communities',
+      percent: Math.round(communityProgress),
+      message,
+      stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
+    });
+  });
+
+  // Log community detection results
+  if (import.meta.env.DEV) {
+    console.log(`🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`);
+  }
+
+  // Add community nodes to the graph
+  communityResult.communities.forEach(comm => {
+    graph.addNode({
+      id: comm.id,
+      label: 'Community' as const,
+      properties: {
+        name: comm.label,
+        filePath: '',
+        heuristicLabel: comm.heuristicLabel,
+        cohesion: comm.cohesion,
+        symbolCount: comm.symbolCount,
+      }
+    });
+  });
+
+  // Add MEMBER_OF relationships
+  communityResult.memberships.forEach(membership => {
+    graph.addRelationship({
+      id: `${membership.nodeId}_member_of_${membership.communityId}`,
+      type: 'MEMBER_OF',
+      sourceId: membership.nodeId,
+      targetId: membership.communityId,
+      confidence: 1.0,
+      reason: 'leiden-algorithm',
+    });
+  });
+
   
-  // Phase 6: Complete (100%)
+  // Phase 8: Complete (100%)
   onProgress({
     phase: 'complete',
     percent: 100,
-    message: 'Graph generation complete!',
+    message: `Graph complete! ${communityResult.stats.totalCommunities} communities detected.`,
     stats: { 
       filesProcessed: files.length, 
       totalFiles: files.length, 
@@ -175,7 +226,7 @@ export const runPipelineFromFiles = async (
   // Cleanup WASM memory before returning
   astCache.clear();
   
-  return { graph, fileContents };
+  return { graph, fileContents, communityResult };
 
   } catch (error) {
     cleanup();
diff --git a/gitnexus/src/core/ingestion/tree-sitter-queries.ts b/gitnexus/src/core/ingestion/tree-sitter-queries.ts
index 674059649..464ed1f86 100644
--- a/gitnexus/src/core/ingestion/tree-sitter-queries.ts
+++ b/gitnexus/src/core/ingestion/tree-sitter-queries.ts
@@ -148,9 +148,184 @@ export const PYTHON_QUERIES = `
     (identifier) @heritage.extends)) @heritage
 `;
 
+// Java queries - works with tree-sitter-java
+export const JAVA_QUERIES = `
+; Classes, Interfaces, Enums, Annotations
+(class_declaration name: (identifier) @name) @definition.class
+(interface_declaration name: (identifier) @name) @definition.interface
+(enum_declaration name: (identifier) @name) @definition.enum
+(annotation_type_declaration name: (identifier) @name) @definition.annotation
+
+; Methods & Constructors
+(method_declaration name: (identifier) @name) @definition.method
+(constructor_declaration name: (identifier) @name) @definition.constructor
+
+; Imports
+(import_declaration (scoped_identifier) @import.source) @import
+
+; Calls
+(method_invocation name: (identifier) @call.name) @call
+(method_invocation object: (_) name: (identifier) @call.name) @call
+
+; Heritage - extends class
+(class_declaration name: (identifier) @heritage.class
+  (superclass (type_identifier) @heritage.extends)) @heritage
+
+; Heritage - implements interfaces
+(class_declaration name: (identifier) @heritage.class
+  (super_interfaces (type_list (type_identifier) @heritage.implements))) @heritage.impl
+`;
+
+// C queries - works with tree-sitter-c
+export const C_QUERIES = `
+; Functions
+(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+(declaration declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+
+; Structs, Unions, Enums, Typedefs
+(struct_specifier name: (type_identifier) @name) @definition.struct
+(union_specifier name: (type_identifier) @name) @definition.union
+(enum_specifier name: (type_identifier) @name) @definition.enum
+(type_definition declarator: (type_identifier) @name) @definition.typedef
+
+; Macros
+(preproc_function_def name: (identifier) @name) @definition.macro
+(preproc_def name: (identifier) @name) @definition.macro
+
+; Includes
+(preproc_include path: (_) @import.source) @import
+
+; Calls
+(call_expression function: (identifier) @call.name) @call
+(call_expression function: (field_expression field: (field_identifier) @call.name)) @call
+`;
+
+// Go queries - works with tree-sitter-go
+export const GO_QUERIES = `
+; Functions & Methods
+(function_declaration name: (identifier) @name) @definition.function
+(method_declaration name: (field_identifier) @name) @definition.method
+
+; Types
+(type_declaration (type_spec name: (type_identifier) @name type: (struct_type))) @definition.struct
+(type_declaration (type_spec name: (type_identifier) @name type: (interface_type))) @definition.interface
+(type_declaration (type_spec name: (type_identifier) @name)) @definition.type
+
+; Imports
+(import_declaration (import_spec path: (interpreted_string_literal) @import.source)) @import
+(import_declaration (import_spec_list (import_spec path: (interpreted_string_literal) @import.source))) @import
+
+; Calls
+(call_expression function: (identifier) @call.name) @call
+(call_expression function: (selector_expression field: (field_identifier) @call.name)) @call
+`;
+
+// C++ queries - works with tree-sitter-cpp
+export const CPP_QUERIES = `
+; Classes, Structs, Namespaces
+(class_specifier name: (type_identifier) @name) @definition.class
+(struct_specifier name: (type_identifier) @name) @definition.struct
+(namespace_definition name: (namespace_identifier) @name) @definition.namespace
+(enum_specifier name: (type_identifier) @name) @definition.enum
+
+; Functions & Methods
+(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name))) @definition.method
+
+; Templates
+(template_declaration (class_specifier name: (type_identifier) @name)) @definition.template
+(template_declaration (function_definition declarator: (function_declarator declarator: (identifier) @name))) @definition.template
+
+; Includes
+(preproc_include path: (_) @import.source) @import
+
+; Calls
+(call_expression function: (identifier) @call.name) @call
+(call_expression function: (field_expression field: (field_identifier) @call.name)) @call
+(call_expression function: (qualified_identifier name: (identifier) @call.name)) @call
+(call_expression function: (template_function name: (identifier) @call.name)) @call
+
+; Heritage
+(class_specifier name: (type_identifier) @heritage.class
+  (base_class_clause (type_identifier) @heritage.extends)) @heritage
+(class_specifier name: (type_identifier) @heritage.class
+  (base_class_clause (access_specifier) (type_identifier) @heritage.extends)) @heritage
+`;
+
+// C# queries - works with tree-sitter-c-sharp
+export const CSHARP_QUERIES = `
+; Types
+(class_declaration name: (identifier) @name) @definition.class
+(interface_declaration name: (identifier) @name) @definition.interface
+(struct_declaration name: (identifier) @name) @definition.struct
+(enum_declaration name: (identifier) @name) @definition.enum
+(record_declaration name: (identifier) @name) @definition.record
+(delegate_declaration name: (identifier) @name) @definition.delegate
+
+; Namespaces
+(namespace_declaration name: (identifier) @name) @definition.namespace
+(namespace_declaration name: (qualified_name) @name) @definition.namespace
+
+; Methods & Properties
+(method_declaration name: (identifier) @name) @definition.method
+(local_function_statement name: (identifier) @name) @definition.function
+(constructor_declaration name: (identifier) @name) @definition.constructor
+(property_declaration name: (identifier) @name) @definition.property
+
+; Using
+(using_directive (qualified_name) @import.source) @import
+(using_directive (identifier) @import.source) @import
+
+; Calls
+(invocation_expression function: (identifier) @call.name) @call
+(invocation_expression function: (member_access_expression name: (identifier) @call.name)) @call
+
+; Heritage
+(class_declaration name: (identifier) @heritage.class
+  (base_list (simple_base_type (identifier) @heritage.extends))) @heritage
+(class_declaration name: (identifier) @heritage.class
+  (base_list (simple_base_type (generic_name (identifier) @heritage.extends)))) @heritage
+`;
+
+// Rust queries - works with tree-sitter-rust
+export const RUST_QUERIES = `
+; Functions & Items
+(function_item name: (identifier) @name) @definition.function
+(struct_item name: (type_identifier) @name) @definition.struct
+(enum_item name: (type_identifier) @name) @definition.enum
+(trait_item name: (type_identifier) @name) @definition.trait
+(impl_item type: (type_identifier) @name) @definition.impl
+(mod_item name: (identifier) @name) @definition.module
+
+; Type aliases, const, static, macros
+(type_item name: (type_identifier) @name) @definition.type
+(const_item name: (identifier) @name) @definition.const
+(static_item name: (identifier) @name) @definition.static
+(macro_definition name: (identifier) @name) @definition.macro
+
+; Use statements
+(use_declaration argument: (_) @import.source) @import
+
+; Calls
+(call_expression function: (identifier) @call.name) @call
+(call_expression function: (field_expression field: (field_identifier) @call.name)) @call
+(call_expression function: (scoped_identifier name: (identifier) @call.name)) @call
+(call_expression function: (generic_function function: (identifier) @call.name)) @call
+
+; Heritage (trait implementation)
+(impl_item trait: (type_identifier) @heritage.trait type: (type_identifier) @heritage.class) @heritage
+(impl_item trait: (generic_type type: (type_identifier) @heritage.trait) type: (type_identifier) @heritage.class) @heritage
+`;
+
 export const LANGUAGE_QUERIES: Record<SupportedLanguages, string> = {
   [SupportedLanguages.TypeScript]: TYPESCRIPT_QUERIES,
   [SupportedLanguages.JavaScript]: JAVASCRIPT_QUERIES,
   [SupportedLanguages.Python]: PYTHON_QUERIES,
+  [SupportedLanguages.Java]: JAVA_QUERIES,
+  [SupportedLanguages.C]: C_QUERIES,
+  [SupportedLanguages.Go]: GO_QUERIES,
+  [SupportedLanguages.CPlusPlus]: CPP_QUERIES,
+  [SupportedLanguages.CSharp]: CSHARP_QUERIES,
+  [SupportedLanguages.Rust]: RUST_QUERIES,
 };
  
\ No newline at end of file
diff --git a/gitnexus/src/core/ingestion/utils.ts b/gitnexus/src/core/ingestion/utils.ts
index f61b0da71..959eb55dc 100644
--- a/gitnexus/src/core/ingestion/utils.ts
+++ b/gitnexus/src/core/ingestion/utils.ts
@@ -4,11 +4,27 @@ import { SupportedLanguages } from '../../config/supported-languages';
  * Map file extension to SupportedLanguage enum
  */
 export const getLanguageFromFilename = (filename: string): SupportedLanguages | null => {
+  // TypeScript (including TSX)
   if (filename.endsWith('.tsx')) return SupportedLanguages.TypeScript;
   if (filename.endsWith('.ts')) return SupportedLanguages.TypeScript;
+  // JavaScript (including JSX)
   if (filename.endsWith('.jsx')) return SupportedLanguages.JavaScript;
   if (filename.endsWith('.js')) return SupportedLanguages.JavaScript;
+  // Python
   if (filename.endsWith('.py')) return SupportedLanguages.Python;
+  // Java
+  if (filename.endsWith('.java')) return SupportedLanguages.Java;
+  // C (source and headers)
+  if (filename.endsWith('.c') || filename.endsWith('.h')) return SupportedLanguages.C;
+  // C++ (all common extensions)
+  if (filename.endsWith('.cpp') || filename.endsWith('.cc') || filename.endsWith('.cxx') ||
+      filename.endsWith('.hpp') || filename.endsWith('.hxx') || filename.endsWith('.hh')) return SupportedLanguages.CPlusPlus;
+  // C#
+  if (filename.endsWith('.cs')) return SupportedLanguages.CSharp;
+  // Go
+  if (filename.endsWith('.go')) return SupportedLanguages.Go;
+  // Rust
+  if (filename.endsWith('.rs')) return SupportedLanguages.Rust;
   return null;
 };
 
diff --git a/gitnexus/src/core/kuzu/csv-generator.ts b/gitnexus/src/core/kuzu/csv-generator.ts
index be99f6688..0b1689893 100644
--- a/gitnexus/src/core/kuzu/csv-generator.ts
+++ b/gitnexus/src/core/kuzu/csv-generator.ts
@@ -196,6 +196,36 @@ const generateCodeElementCSV = (
   return rows.join('\n');
 };
 
+/**
+ * Generate CSV for Community nodes (from Leiden algorithm)
+ * Headers: id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount
+ */
+const generateCommunityCSV = (nodes: GraphNode[]): string => {
+  const headers = ['id', 'label', 'heuristicLabel', 'keywords', 'description', 'enrichedBy', 'cohesion', 'symbolCount'];
+  const rows: string[] = [headers.join(',')];
+  
+  for (const node of nodes) {
+    if (node.label !== 'Community') continue;
+    
+    // Handle keywords array - convert to KuzuDB array format
+    const keywords = (node.properties as any).keywords || [];
+    const keywordsStr = `[${keywords.map((k: string) => `'${k.replace(/'/g, "''")}'`).join(',')}]`;
+    
+    rows.push([
+      escapeCSVField(node.id),
+      escapeCSVField(node.properties.name || ''),  // label is stored in name
+      escapeCSVField(node.properties.heuristicLabel || ''),
+      keywordsStr,  // Array format for KuzuDB
+      escapeCSVField((node.properties as any).description || ''),
+      escapeCSVField((node.properties as any).enrichedBy || 'heuristic'),
+      escapeCSVNumber(node.properties.cohesion, 0),
+      escapeCSVNumber(node.properties.symbolCount, 0),
+    ].join(','));
+  }
+  
+  return rows.join('\n');
+};
+
 // ============================================================================
 // RELATIONSHIP CSV GENERATOR (Single Table)
 // ============================================================================
@@ -247,6 +277,7 @@ export const generateAllCSVs = (
   nodeCSVs.set('Interface', generateCodeElementCSV(nodes, 'Interface', fileContents));
   nodeCSVs.set('Method', generateCodeElementCSV(nodes, 'Method', fileContents));
   nodeCSVs.set('CodeElement', generateCodeElementCSV(nodes, 'CodeElement', fileContents));
+  nodeCSVs.set('Community', generateCommunityCSV(nodes));
   
   // Generate single relation CSV
   const relCSV = generateRelationCSV(graph);
diff --git a/gitnexus/src/core/kuzu/kuzu-adapter.ts b/gitnexus/src/core/kuzu/kuzu-adapter.ts
index ea994d7f8..73aa40b25 100644
--- a/gitnexus/src/core/kuzu/kuzu-adapter.ts
+++ b/gitnexus/src/core/kuzu/kuzu-adapter.ts
@@ -127,29 +127,51 @@ export const loadGraphToKuzu = async (
         const [, fromId, toId, relType, confidenceStr, reason] = match;
         const confidence = parseFloat(confidenceStr) || 1.0;
         
-        // Extract labels from node IDs (format: Label:path:name)
-        const fromLabel = fromId.split(':')[0];
-        const toLabel = toId.split(':')[0];
+        // Extract labels from node IDs
+        // Community nodes have IDs like "comm_14" (no colon)
+        // Other nodes have IDs like "Label:path:name"
+        const getNodeLabel = (nodeId: string): string => {
+          if (nodeId.startsWith('comm_')) {
+            return 'Community';
+          }
+          return nodeId.split(':')[0];
+        };
+        
+        // Reserved Cypher keywords need backtick escaping
+        const RESERVED_LABELS = ['Macro', 'Enum', 'Union', 'Const', 'Module', 'Struct'];
+        const escapeLabel = (label: string): string => {
+          return RESERVED_LABELS.includes(label) ? `\`${label}\`` : label;
+        };
+        
+        const fromLabel = escapeLabel(getNodeLabel(fromId));
+        const toLabel = escapeLabel(getNodeLabel(toId));
         
         // INSERT with explicit node matching (including confidence and reason)
         const insertQuery = `
-          MATCH (a:${fromLabel} {id: '${fromId.replace(/'/g, "''")}'})
-          MATCH (b:${toLabel} {id: '${toId.replace(/'/g, "''")}'})
+          MATCH (a:${fromLabel} {id: '${fromId.replace(/'/g, "''")}'}),
+                (b:${toLabel} {id: '${toId.replace(/'/g, "''")}'})
           CREATE (a)-[:${REL_TABLE_NAME} {type: '${relType}', confidence: ${confidence}, reason: '${reason.replace(/'/g, "''")}'}]->(b)
         `;
         await conn.query(insertQuery);
         insertedRels++;
-      } catch {
+      } catch (err) {
         // Skip failed insertions (nodes might not exist, or relation pair not allowed by schema)
         skippedRels++;
-        if (import.meta.env.DEV) {
-          const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)"/);
-          if (match) {
-            const [, fromId, toId, relType] = match;
-            const fromLabel = fromId.split(':')[0];
-            const toLabel = toId.split(':')[0];
-            const key = `${relType}:${fromLabel}->${toLabel}`;
-            skippedRelStats.set(key, (skippedRelStats.get(key) || 0) + 1);
+        const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)"/);
+        if (match) {
+          const [, fromId, toId, relType] = match;
+          const getNodeLabel = (nodeId: string): string => {
+            if (nodeId.startsWith('comm_')) return 'Community';
+            return nodeId.split(':')[0];
+          };
+          const fromLabel = getNodeLabel(fromId);
+          const toLabel = getNodeLabel(toId);
+          const key = `${relType}:${fromLabel}->` + toLabel;
+          skippedRelStats.set(key, (skippedRelStats.get(key) || 0) + 1);
+          
+          // Log each skipped relation
+          if (import.meta.env.DEV) {
+            console.warn(`⚠️ Skipped: ${key} | "${fromId}" → "${toId}" | ${err instanceof Error ? err.message : String(err)}`);
           }
         }
       }
@@ -204,6 +226,9 @@ const getCopyQuery = (table: NodeTableName, path: string): string => {
   if (table === 'Folder') {
     return `COPY Folder(id, name, filePath) FROM "${path}" (HEADER=true, PARALLEL=false)`;
   }
+  if (table === 'Community') {
+    return `COPY Community(id, label, heuristicLabel, keywords, description, enrichedBy, cohesion, symbolCount) FROM "${path}" (HEADER=true, PARALLEL=false)`;
+  }
   // All code element tables: Function, Class, Interface, Method, CodeElement
   return `COPY ${table}(id, name, filePath, startLine, endLine, content) FROM "${path}" (HEADER=true, PARALLEL=false)`;
 };
diff --git a/gitnexus/src/core/kuzu/schema.ts b/gitnexus/src/core/kuzu/schema.ts
index 0be8b8576..437383c2d 100644
--- a/gitnexus/src/core/kuzu/schema.ts
+++ b/gitnexus/src/core/kuzu/schema.ts
@@ -12,7 +12,12 @@
 // ============================================================================
 // NODE TABLE NAMES
 // ============================================================================
-export const NODE_TABLES = ['File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement'] as const;
+export const NODE_TABLES = [
+  'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community',
+  // Multi-language support
+  'Struct', 'Enum', 'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl',
+  'TypeAlias', 'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module'
+] as const;
 export type NodeTableName = typeof NODE_TABLES[number];
 
 // ============================================================================
@@ -21,7 +26,7 @@ export type NodeTableName = typeof NODE_TABLES[number];
 export const REL_TABLE_NAME = 'CodeRelation';
 
 // Valid relation types
-export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS'] as const;
+export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS', 'MEMBER_OF'] as const;
 export type RelType = typeof REL_TYPES[number];
 
 // ============================================================================
@@ -105,6 +110,58 @@ CREATE NODE TABLE CodeElement (
   PRIMARY KEY (id)
 )`;
 
+// ============================================================================
+// COMMUNITY NODE TABLE (for Leiden algorithm clusters)
+// ============================================================================
+
+export const COMMUNITY_SCHEMA = `
+CREATE NODE TABLE Community (
+  id STRING,
+  label STRING,
+  heuristicLabel STRING,
+  keywords STRING[],
+  description STRING,
+  enrichedBy STRING,
+  cohesion DOUBLE,
+  symbolCount INT32,
+  PRIMARY KEY (id)
+)`;
+
+// ============================================================================
+// MULTI-LANGUAGE NODE TABLE SCHEMAS
+// ============================================================================
+
+// Generic code element with startLine/endLine for C, C++, Rust, Go, Java, C#
+const CODE_ELEMENT_BASE = (name: string) => `
+CREATE NODE TABLE \`${name}\` (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const STRUCT_SCHEMA = CODE_ELEMENT_BASE('Struct');
+export const ENUM_SCHEMA = CODE_ELEMENT_BASE('Enum');
+export const MACRO_SCHEMA = CODE_ELEMENT_BASE('Macro');
+export const TYPEDEF_SCHEMA = CODE_ELEMENT_BASE('Typedef');
+export const UNION_SCHEMA = CODE_ELEMENT_BASE('Union');
+export const NAMESPACE_SCHEMA = CODE_ELEMENT_BASE('Namespace');
+export const TRAIT_SCHEMA = CODE_ELEMENT_BASE('Trait');
+export const IMPL_SCHEMA = CODE_ELEMENT_BASE('Impl');
+export const TYPE_ALIAS_SCHEMA = CODE_ELEMENT_BASE('TypeAlias');
+export const CONST_SCHEMA = CODE_ELEMENT_BASE('Const');
+export const STATIC_SCHEMA = CODE_ELEMENT_BASE('Static');
+export const PROPERTY_SCHEMA = CODE_ELEMENT_BASE('Property');
+export const RECORD_SCHEMA = CODE_ELEMENT_BASE('Record');
+export const DELEGATE_SCHEMA = CODE_ELEMENT_BASE('Delegate');
+export const ANNOTATION_SCHEMA = CODE_ELEMENT_BASE('Annotation');
+export const CONSTRUCTOR_SCHEMA = CODE_ELEMENT_BASE('Constructor');
+export const TEMPLATE_SCHEMA = CODE_ELEMENT_BASE('Template');
+export const MODULE_SCHEMA = CODE_ELEMENT_BASE('Module');
+
 // ============================================================================
 // RELATION TABLE SCHEMA
 // Single table with 'type' property - connects all node tables
@@ -119,18 +176,79 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM File TO Interface,
   FROM File TO Method,
   FROM File TO CodeElement,
+  FROM File TO \`Struct\`,
+  FROM File TO \`Enum\`,
+  FROM File TO \`Macro\`,
+  FROM File TO Typedef,
+  FROM File TO \`Union\`,
+  FROM File TO Namespace,
+  FROM File TO Trait,
+  FROM File TO Impl,
+  FROM File TO TypeAlias,
+  FROM File TO \`Const\`,
+  FROM File TO Static,
+  FROM File TO Property,
+  FROM File TO Record,
+  FROM File TO Delegate,
+  FROM File TO Annotation,
+  FROM File TO Constructor,
+  FROM File TO Template,
+  FROM File TO \`Module\`,
   FROM Folder TO Folder,
   FROM Folder TO File,
   FROM Function TO Function,
   FROM Function TO Method,
   FROM Function TO Class,
+  FROM Function TO Community,
+  FROM Function TO \`Macro\`,
+  FROM Function TO \`Struct\`,
+  FROM Function TO Template,
+  FROM Function TO \`Enum\`,
+  FROM Function TO Namespace,
+  FROM Function TO TypeAlias,
   FROM Class TO Method,
   FROM Class TO Function,
   FROM Class TO Class,
   FROM Class TO Interface,
+  FROM Class TO Community,
+  FROM Class TO Template,
   FROM Method TO Function,
   FROM Method TO Method,
   FROM Method TO Class,
+  FROM Method TO Community,
+  FROM Method TO Template,
+  FROM Method TO \`Struct\`,
+  FROM Template TO Template,
+  FROM Template TO Function,
+  FROM Template TO Method,
+  FROM Template TO Class,
+  FROM Template TO \`Struct\`,
+  FROM CodeElement TO Community,
+  FROM Interface TO Community,
+  FROM \`Struct\` TO Community,
+  FROM \`Struct\` TO Trait,
+  FROM \`Struct\` TO Function,
+  FROM \`Struct\` TO Method,
+  FROM \`Enum\` TO Community,
+  FROM \`Macro\` TO Community,
+  FROM Typedef TO Community,
+  FROM \`Union\` TO Community,
+  FROM Namespace TO Community,
+  FROM Trait TO Community,
+  FROM Impl TO Community,
+  FROM Impl TO Trait,
+  FROM TypeAlias TO Community,
+  FROM \`Const\` TO Community,
+  FROM Static TO Community,
+  FROM Property TO Community,
+  FROM Record TO Community,
+  FROM Delegate TO Community,
+  FROM Annotation TO Community,
+  FROM Constructor TO Community,
+  FROM Constructor TO Interface,
+  FROM Constructor TO Class,
+  FROM Template TO Community,
+  FROM \`Module\` TO Community,
   type STRING,
   confidence DOUBLE,
   reason STRING
@@ -169,6 +287,26 @@ export const NODE_SCHEMA_QUERIES = [
   INTERFACE_SCHEMA,
   METHOD_SCHEMA,
   CODE_ELEMENT_SCHEMA,
+  COMMUNITY_SCHEMA,
+  // Multi-language support
+  STRUCT_SCHEMA,
+  ENUM_SCHEMA,
+  MACRO_SCHEMA,
+  TYPEDEF_SCHEMA,
+  UNION_SCHEMA,
+  NAMESPACE_SCHEMA,
+  TRAIT_SCHEMA,
+  IMPL_SCHEMA,
+  TYPE_ALIAS_SCHEMA,
+  CONST_SCHEMA,
+  STATIC_SCHEMA,
+  PROPERTY_SCHEMA,
+  RECORD_SCHEMA,
+  DELEGATE_SCHEMA,
+  ANNOTATION_SCHEMA,
+  CONSTRUCTOR_SCHEMA,
+  TEMPLATE_SCHEMA,
+  MODULE_SCHEMA,
 ];
 
 export const REL_SCHEMA_QUERIES = [
diff --git a/gitnexus/src/core/llm/types.ts b/gitnexus/src/core/llm/types.ts
index c01811933..8df3114b0 100644
--- a/gitnexus/src/core/llm/types.ts
+++ b/gitnexus/src/core/llm/types.ts
@@ -87,6 +87,12 @@ export interface LLMSettings {
   gemini?: Partial<Omit<GeminiConfig, 'provider'>>;
   anthropic?: Partial<Omit<AnthropicConfig, 'provider'>>;
   ollama?: Partial<Omit<OllamaConfig, 'provider'>>;
+
+  // Intelligent Clustering Settings
+  intelligentClustering: boolean;
+  hasSeenClusteringPrompt: boolean;
+  useSameModelForClustering: boolean;
+  clusteringProvider?: Partial<ProviderConfig>; // Optional specific config for clustering
 }
 
 /**
@@ -94,6 +100,9 @@ export interface LLMSettings {
  */
 export const DEFAULT_LLM_SETTINGS: LLMSettings = {
   activeProvider: 'gemini',
+  intelligentClustering: false,
+  hasSeenClusteringPrompt: false,
+  useSameModelForClustering: true,
   openai: {
     apiKey: '',
     model: 'gpt-4o',
diff --git a/gitnexus/src/core/tree-sitter/parser-loader.ts b/gitnexus/src/core/tree-sitter/parser-loader.ts
index e6092f8b6..d5224ca4e 100644
--- a/gitnexus/src/core/tree-sitter/parser-loader.ts
+++ b/gitnexus/src/core/tree-sitter/parser-loader.ts
@@ -33,6 +33,12 @@ const getWasmPath = (language: SupportedLanguages, filePath?: string): string =>
         [SupportedLanguages.JavaScript]: '/wasm/javascript/tree-sitter-javascript.wasm',
         [SupportedLanguages.TypeScript]: '/wasm/typescript/tree-sitter-typescript.wasm',
         [SupportedLanguages.Python]: '/wasm/python/tree-sitter-python.wasm',
+        [SupportedLanguages.Java]: '/wasm/java/tree-sitter-java.wasm',
+        [SupportedLanguages.C]: '/wasm/c/tree-sitter-c.wasm',
+        [SupportedLanguages.CPlusPlus]: '/wasm/cpp/tree-sitter-cpp.wasm',
+        [SupportedLanguages.CSharp]: '/wasm/csharp/tree-sitter-csharp.wasm',
+        [SupportedLanguages.Go]: '/wasm/go/tree-sitter-go.wasm',
+        [SupportedLanguages.Rust]: '/wasm/rust/tree-sitter-rust.wasm',
     };
     
     return languageFileMap[language];
@@ -40,18 +46,27 @@ const getWasmPath = (language: SupportedLanguages, filePath?: string): string =>
 
 export const loadLanguage = async (language: SupportedLanguages, filePath?: string): Promise<void> => {
     if (!parser) await loadParser();
-
     const wasmPath = getWasmPath(language, filePath);
     
-    // Use wasmPath as cache key to differentiate ts vs tsx
     if (languageCache.has(wasmPath)) {
         parser!.setLanguage(languageCache.get(wasmPath)!);
         return;
     }
 
-    if (!wasmPath) throw new Error(`Unsupported language: ${language}`);
+    if (!wasmPath) {
+        console.error(`❌ [Parser] No WASM path configured for language: ${language}`);
+        throw new Error(`Unsupported language: ${language}`);
+    }
     
-    const loadedLanguage = await Parser.Language.load(wasmPath);    
-    languageCache.set(wasmPath, loadedLanguage);
-    parser!.setLanguage(loadedLanguage);
+    try {
+        const loadedLanguage = await Parser.Language.load(wasmPath);    
+        languageCache.set(wasmPath, loadedLanguage);
+        parser!.setLanguage(loadedLanguage);
+    } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`❌ [Parser] Failed to load WASM grammar for ${language}`);
+        console.error(`   WASM Path: ${wasmPath}`);
+        console.error(`   Error: ${errorMessage}`);
+        throw new Error(`Failed to load grammar for ${language}: ${errorMessage}`);
+    }
 }
diff --git a/gitnexus/src/hooks/useAppState.tsx b/gitnexus/src/hooks/useAppState.tsx
index 28bffef81..bce50e94e 100644
--- a/gitnexus/src/hooks/useAppState.tsx
+++ b/gitnexus/src/hooks/useAppState.tsx
@@ -8,7 +8,7 @@ import type { IngestionWorkerApi } from '../workers/ingestion.worker';
 import type { FileEntry } from '../services/zip';
 import type { EmbeddingProgress, SemanticSearchResult } from '../core/embeddings/types';
 import type { LLMSettings, ProviderConfig, AgentStreamChunk, ChatMessage, ToolCallInfo, MessageStep } from '../core/llm/types';
-import { loadSettings, getActiveProviderConfig } from '../core/llm/settings-service';
+import { loadSettings, getActiveProviderConfig, saveSettings } from '../core/llm/settings-service';
 import type { AgentMessage } from '../core/llm/agent';
 import { DEFAULT_VISIBLE_EDGES, type EdgeType } from '../lib/constants';
 
@@ -112,8 +112,8 @@ interface AppState {
   setProjectName: (name: string) => void;
 
   // Worker API (shared across app)
-  runPipeline: (file: File, onProgress: (p: PipelineProgress) => void) => Promise<PipelineResult>;
-  runPipelineFromFiles: (files: FileEntry[], onProgress: (p: PipelineProgress) => void) => Promise<PipelineResult>;
+  runPipeline: (file: File, onProgress: (p: PipelineProgress) => void, clusteringConfig?: ProviderConfig) => Promise<PipelineResult>;
+  runPipelineFromFiles: (files: FileEntry[], onProgress: (p: PipelineProgress) => void, clusteringConfig?: ProviderConfig) => Promise<PipelineResult>;
   runQuery: (cypher: string) => Promise<any[]>;
   isDatabaseReady: () => Promise<boolean>;
 
@@ -123,6 +123,9 @@ interface AppState {
 
   // Embedding methods
   startEmbeddings: (forceDevice?: 'webgpu' | 'wasm') => Promise<void>;
+  startBackgroundEnrichment: () => Promise<void>;
+  cancelEnrichment: () => Promise<void>;
+  enrichmentProgress: { current: number; total: number } | null;
   semanticSearch: (query: string, k?: number) => Promise<SemanticSearchResult[]>;
   semanticSearchWithContext: (query: string, k?: number, hops?: number) => Promise<any[]>;
   isEmbeddingReady: boolean;
@@ -132,6 +135,7 @@ interface AppState {
 
   // LLM/Agent state
   llmSettings: LLMSettings;
+  updateLLMSettings: (updates: Partial<LLMSettings>) => void;
   isSettingsPanelOpen: boolean;
   setSettingsPanelOpen: (open: boolean) => void;
   isAgentReady: boolean;
@@ -145,6 +149,7 @@ interface AppState {
 
   // LLM methods
   refreshLLMSettings: () => void;
+  runClusterEnrichment: () => Promise<void>;
   initializeAgent: (overrideProjectName?: string) => Promise<void>;
   sendChatMessage: (message: string) => Promise<void>;
   clearChat: () => void;
@@ -289,6 +294,10 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
   const [isCodePanelOpen, setCodePanelOpen] = useState(false);
   const [codeReferenceFocus, setCodeReferenceFocus] = useState<CodeReferenceFocus | null>(null);
 
+  // Cluster enrichment state
+  const [enrichmentProgress, setEnrichmentProgress] = useState<{ current: number; total: number } | null>(null);
+  const enrichmentCancelledRef = useRef(false);
+
   const normalizePath = useCallback((p: string) => {
     return p.replace(/\\/g, '/').replace(/^\.?\//, '');
   }, []);
@@ -427,25 +436,27 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
 
   const runPipeline = useCallback(async (
     file: File,
-    onProgress: (progress: PipelineProgress) => void
+    onProgress: (progress: PipelineProgress) => void,
+    clusteringConfig?: ProviderConfig
   ): Promise<PipelineResult> => {
     const api = apiRef.current;
     if (!api) throw new Error('Worker not initialized');
 
     const proxiedOnProgress = Comlink.proxy(onProgress);
-    const serializedResult = await api.runPipeline(file, proxiedOnProgress);
+    const serializedResult = await api.runPipeline(file, proxiedOnProgress, clusteringConfig);
     return deserializePipelineResult(serializedResult, createKnowledgeGraph);
   }, []);
 
   const runPipelineFromFiles = useCallback(async (
     files: FileEntry[],
-    onProgress: (progress: PipelineProgress) => void
+    onProgress: (progress: PipelineProgress) => void,
+    clusteringConfig?: ProviderConfig
   ): Promise<PipelineResult> => {
     const api = apiRef.current;
     if (!api) throw new Error('Worker not initialized');
 
     const proxiedOnProgress = Comlink.proxy(onProgress);
-    const serializedResult = await api.runPipelineFromFiles(files, proxiedOnProgress);
+    const serializedResult = await api.runPipelineFromFiles(files, proxiedOnProgress, clusteringConfig);
     return deserializePipelineResult(serializedResult, createKnowledgeGraph);
   }, []);
 
@@ -510,6 +521,63 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
     }
   }, []);
 
+  // Background cluster enrichment
+  const startBackgroundEnrichment = useCallback(async (): Promise<void> => {
+    const api = apiRef.current;
+    if (!api) return;
+
+    enrichmentCancelledRef.current = false;
+
+    try {
+      const result = await api.startBackgroundEnrichment(
+        Comlink.proxy((current: number, total: number) => {
+          setEnrichmentProgress({ current, total });
+          setProgress({
+            phase: 'complete',
+            percent: 100,
+            message: `Labeling clusters ${current}/${total}...`,
+          });
+        })
+      );
+
+      setEnrichmentProgress(null);
+
+      if (!result.skipped && result.enriched > 0) {
+        setProgress({
+          phase: 'complete',
+          percent: 100,
+          message: 'Smart cluster labels generated!',
+        });
+        // Clear after 3 seconds
+        setTimeout(() => setProgress(null), 3000);
+      }
+    } catch (err) {
+      console.warn('Background enrichment failed:', err);
+      setEnrichmentProgress(null);
+    }
+  }, []);
+
+  // Cancel/pause enrichment
+  const cancelEnrichment = useCallback(async (): Promise<void> => {
+    const api = apiRef.current;
+    if (!api) return;
+
+    enrichmentCancelledRef.current = true;
+    setEnrichmentProgress(null);
+
+    try {
+      await api.cancelEnrichment();
+      setProgress({
+        phase: 'complete',
+        percent: 100,
+        message: 'LLM labeling stopped. Using heuristic labels.',
+      });
+      setTimeout(() => setProgress(null), 3000);
+    } catch (err) {
+      console.warn('Cancel enrichment failed:', err);
+    }
+  }, []);
+
   const semanticSearch = useCallback(async (
     query: string,
     k: number = 10
@@ -536,6 +604,101 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
   }, []);
 
   // LLM methods
+  const updateLLMSettings = useCallback((updates: Partial<LLMSettings>) => {
+    setLLMSettings(prev => {
+      const next = { ...prev, ...updates };
+      saveSettings(next);
+      return next;
+    });
+  }, []);
+
+  const runClusterEnrichment = useCallback(async () => {
+    const api = apiRef.current;
+    if (!api) {
+      setAgentError('Worker not initialized');
+      return;
+    }
+
+
+    const defaultConfig = getActiveProviderConfig();
+    const configToUse = (!llmSettings.useSameModelForClustering && llmSettings.clusteringProvider?.provider)
+      ? {
+        ...defaultConfig,
+        provider: llmSettings.clusteringProvider.provider || defaultConfig!.provider,
+        model: llmSettings.clusteringProvider.model || defaultConfig!.model,
+        apiKey: (llmSettings.clusteringProvider as any).apiKey || (defaultConfig as any).apiKey
+      } as ProviderConfig
+      : defaultConfig;
+
+    if (!configToUse) {
+      // No provider configured - open settings panel
+      setSettingsPanelOpen(true);
+      setAgentError('Please configure an LLM provider in Settings first.');
+      return;
+    }
+
+
+    try {
+      setProgress({
+        phase: 'enriching',
+        percent: 1,
+        message: 'Starting AI enrichment...',
+        stats: { filesProcessed: 0, totalFiles: 0, nodesCreated: 0 }
+      });
+
+      const { enrichments } = await api.enrichCommunities(
+        configToUse,
+        Comlink.proxy((current, total) => {
+          setProgress(prev => prev ? ({
+            ...prev,
+            percent: Math.min(99, 5 + Math.round((current / total) * 90)),
+            message: `Enriching clusters ${current}/${total}`
+          }) : null);
+        })
+      );
+
+      // Update local graph
+      setGraph(prevGraph => {
+        if (!prevGraph) return null;
+
+        const newNodes = prevGraph.nodes.map(n => {
+          if (n.label === 'Community' && enrichments[n.id]) {
+            const e = enrichments[n.id];
+            return {
+              ...n,
+              properties: {
+                ...n.properties,
+                name: e.name,
+                keywords: e.keywords,
+                description: e.description,
+                enrichedBy: 'llm' as const
+              }
+            };
+          }
+          return n;
+        });
+        return { ...prevGraph, nodes: newNodes };
+      });
+
+      setProgress({
+        phase: 'complete',
+        percent: 100,
+        message: '✨ Smart labels generated!',
+        stats: { filesProcessed: 0, totalFiles: 0, nodesCreated: 0 }
+      });
+
+
+      // Clear progress after 3 seconds
+      setTimeout(() => setProgress(null), 3000);
+
+    } catch (err) {
+      console.error(err);
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      setAgentError('Clustering enrichment failed: ' + errorMsg);
+      setProgress(null);
+    }
+  }, [llmSettings]);
+
   const refreshLLMSettings = useCallback(() => {
     setLLMSettings(loadSettings());
   }, []);
@@ -1039,6 +1202,9 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
     embeddingStatus,
     embeddingProgress,
     startEmbeddings,
+    startBackgroundEnrichment,
+    cancelEnrichment,
+    enrichmentProgress,
     semanticSearch,
     semanticSearchWithContext,
     isEmbeddingReady: embeddingStatus === 'ready',
@@ -1046,6 +1212,7 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
     testArrayParams,
     // LLM/Agent state
     llmSettings,
+    updateLLMSettings,
     isSettingsPanelOpen,
     setSettingsPanelOpen,
     isAgentReady,
@@ -1057,6 +1224,7 @@ export const AppStateProvider = ({ children }: { children: ReactNode }) => {
     currentToolCalls,
     // LLM methods
     refreshLLMSettings,
+    runClusterEnrichment,
     initializeAgent,
     sendChatMessage,
     clearChat,
diff --git a/gitnexus/src/hooks/useSettings.ts b/gitnexus/src/hooks/useSettings.ts
new file mode 100644
index 000000000..a27bf313f
--- /dev/null
+++ b/gitnexus/src/hooks/useSettings.ts
@@ -0,0 +1,10 @@
+import { useAppState } from './useAppState';
+
+export const useSettings = () => {
+  const { llmSettings, updateLLMSettings } = useAppState();
+  
+  return {
+    settings: llmSettings,
+    updateSettings: updateLLMSettings
+  };
+};
diff --git a/gitnexus/src/lib/constants.ts b/gitnexus/src/lib/constants.ts
index 549ab9adf..a5c231b32 100644
--- a/gitnexus/src/lib/constants.ts
+++ b/gitnexus/src/lib/constants.ts
@@ -17,6 +17,7 @@ export const NODE_COLORS: Record<NodeLabel, string> = {
   Import: '#475569',     // Slate darker - very muted
   Type: '#a78bfa',       // Violet light
   CodeElement: '#64748b', // Slate - muted
+  Community: '#818cf8',  // Indigo light - cluster indicator
 };
 
 // Node sizes by type - clear visual hierarchy with dramatic size differences
@@ -37,6 +38,27 @@ export const NODE_SIZES: Record<NodeLabel, number> = {
   Import: 1.5,     // Very small - usually hidden anyway
   Type: 3,         // Type alias - small
   CodeElement: 2,  // Generic small
+  Community: 0,    // Hidden by default - metadata node
+};
+
+// Community color palette for cluster-based coloring
+export const COMMUNITY_COLORS = [
+  '#ef4444', // red
+  '#f97316', // orange
+  '#eab308', // yellow
+  '#22c55e', // green
+  '#06b6d4', // cyan
+  '#3b82f6', // blue
+  '#8b5cf6', // violet
+  '#d946ef', // fuchsia
+  '#ec4899', // pink
+  '#f43f5e', // rose
+  '#14b8a6', // teal
+  '#84cc16', // lime
+];
+
+export const getCommunityColor = (communityIndex: number): string => {
+  return COMMUNITY_COLORS[communityIndex % COMMUNITY_COLORS.length];
 };
 
 // Labels to show by default (hide imports and variables by default as they clutter)
diff --git a/gitnexus/src/lib/graph-adapter.ts b/gitnexus/src/lib/graph-adapter.ts
index 92a1a9d67..a190d45a2 100644
--- a/gitnexus/src/lib/graph-adapter.ts
+++ b/gitnexus/src/lib/graph-adapter.ts
@@ -1,6 +1,6 @@
 import Graph from 'graphology';
 import { KnowledgeGraph, NodeLabel } from '../core/graph/types';
-import { NODE_COLORS, NODE_SIZES } from './constants';
+import { NODE_COLORS, NODE_SIZES, getCommunityColor } from './constants';
 
 export interface SigmaNodeAttributes {
   x: number;
@@ -16,6 +16,8 @@ export interface SigmaNodeAttributes {
   zIndex?: number;
   highlighted?: boolean;
   mass?: number; // ForceAtlas2 mass - higher = more repulsion
+  community?: number; // Community index from Leiden algorithm
+  communityColor?: string; // Color assigned by community
 }
 
 export interface SigmaEdgeAttributes {
@@ -74,9 +76,13 @@ const getNodeMass = (nodeType: NodeLabel, nodeCount: number): number => {
 /**
  * Converts the KnowledgeGraph to a graphology Graph for Sigma.js
  * Folders are positioned in a wide spread, children positioned NEAR their parents
+ * 
+ * @param knowledgeGraph - The knowledge graph to convert
+ * @param communityMemberships - Optional map of nodeId -> communityIndex for community coloring
  */
 export const knowledgeGraphToGraphology = (
-  knowledgeGraph: KnowledgeGraph
+  knowledgeGraph: KnowledgeGraph,
+  communityMemberships?: Map<string, number>
 ): Graph<SigmaNodeAttributes, SigmaEdgeAttributes> => {
   const graph = new Graph<SigmaNodeAttributes, SigmaEdgeAttributes>();
   const nodeCount = knowledgeGraph.nodes.length;
@@ -116,6 +122,31 @@ export const knowledgeGraphToGraphology = (
   // Small jitter for children around their parent
   const childJitter = Math.sqrt(nodeCount) * 3;
 
+  // === CLUSTER-BASED POSITIONING ===
+  // Calculate cluster centers - each cluster gets a region of the graph
+  const clusterCenters = new Map<number, { x: number; y: number }>();
+  if (communityMemberships && communityMemberships.size > 0) {
+    // Find unique community IDs
+    const communities = new Set(communityMemberships.values());
+    const communityCount = communities.size;
+    const clusterSpread = structuralSpread * 0.8; // Clusters spread across 80% of graph
+    
+    // Position cluster centers using golden angle for even distribution
+    const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+    let idx = 0;
+    communities.forEach(communityId => {
+      const angle = idx * goldenAngle;
+      const radius = clusterSpread * Math.sqrt((idx + 1) / communityCount);
+      clusterCenters.set(communityId, {
+        x: radius * Math.cos(angle),
+        y: radius * Math.sin(angle),
+      });
+      idx++;
+    });
+  }
+  // Jitter within cluster (tighter than childJitter)
+  const clusterJitter = Math.sqrt(nodeCount) * 1.5;
+
   // Store positions for parent lookup
   const nodePositions = new Map<string, { x: number; y: number }>();
 
@@ -136,6 +167,7 @@ export const knowledgeGraphToGraphology = (
     const baseSize = NODE_SIZES[node.label] || 8;
     const scaledSize = getScaledNodeSize(baseSize, nodeCount);
     
+    // Structural nodes keep their type-based color
     graph.addNode(node.id, {
       x,
       y,
@@ -161,18 +193,28 @@ export const knowledgeGraphToGraphology = (
     
     let x: number, y: number;
     
-    // Find parent position (parent should already be positioned!)
-    const parentId = childToParent.get(nodeId);
-    const parentPos = parentId ? nodePositions.get(parentId) : null;
+    // Check if this is a symbol node with a community assignment
+    const communityIndex = communityMemberships?.get(nodeId);
+    const symbolTypes = new Set(['Function', 'Class', 'Method', 'Interface']);
+    const clusterCenter = communityIndex !== undefined ? clusterCenters.get(communityIndex) : null;
     
-    if (parentPos) {
-      // Position near parent with small random offset
-      x = parentPos.x + (Math.random() - 0.5) * childJitter;
-      y = parentPos.y + (Math.random() - 0.5) * childJitter;
+    if (clusterCenter && symbolTypes.has(node.label)) {
+      // CLUSTER-BASED POSITIONING: Position near cluster center with tight jitter
+      x = clusterCenter.x + (Math.random() - 0.5) * clusterJitter;
+      y = clusterCenter.y + (Math.random() - 0.5) * clusterJitter;
     } else {
-      // No parent found - position randomly but still spread out
-      x = (Math.random() - 0.5) * structuralSpread * 0.5;
-      y = (Math.random() - 0.5) * structuralSpread * 0.5;
+      // HIERARCHY-BASED POSITIONING: Position near parent
+      const parentId = childToParent.get(nodeId);
+      const parentPos = parentId ? nodePositions.get(parentId) : null;
+      
+      if (parentPos) {
+        x = parentPos.x + (Math.random() - 0.5) * childJitter;
+        y = parentPos.y + (Math.random() - 0.5) * childJitter;
+      } else {
+        // No parent found - position randomly but still spread out
+        x = (Math.random() - 0.5) * structuralSpread * 0.5;
+        y = (Math.random() - 0.5) * structuralSpread * 0.5;
+      }
     }
     
     nodePositions.set(nodeId, { x, y });
@@ -180,11 +222,20 @@ export const knowledgeGraphToGraphology = (
     const baseSize = NODE_SIZES[node.label] || 8;
     const scaledSize = getScaledNodeSize(baseSize, nodeCount);
     
+    // Check if this node has a community assignment (reuse communityIndex from above)
+    const hasCommunity = communityIndex !== undefined;
+    
+    // Symbol nodes get colored by community if available
+    const usesCommunityColor = hasCommunity && symbolTypes.has(node.label);
+    const nodeColor = usesCommunityColor 
+      ? getCommunityColor(communityIndex!)
+      : NODE_COLORS[node.label] || '#9ca3af';
+    
     graph.addNode(nodeId, {
       x,
       y,
       size: scaledSize,
-      color: NODE_COLORS[node.label] || '#9ca3af',
+      color: nodeColor,
       label: node.properties.name,
       nodeType: node.label,
       filePath: node.properties.filePath,
@@ -192,6 +243,8 @@ export const knowledgeGraphToGraphology = (
       endLine: node.properties.endLine,
       hidden: false,
       mass: getNodeMass(node.label, nodeCount),
+      community: communityIndex,
+      communityColor: hasCommunity ? getCommunityColor(communityIndex!) : undefined,
     });
   };
   
diff --git a/gitnexus/src/repomix-output.md b/gitnexus/src/repomix-output.md
new file mode 100644
index 000000000..6a96c3c1e
--- /dev/null
+++ b/gitnexus/src/repomix-output.md
@@ -0,0 +1,13681 @@
+This file is a merged representation of the entire codebase, combining all repository files into a single document.
+Generated by Repomix on: 2026-01-20 12:29:34
+
+# File Summary
+
+## Purpose:
+
+This file contains a packed representation of the entire repository's contents.
+It is designed to be easily consumable by AI systems for analysis, code review,
+or other automated processes.
+
+## File Format:
+
+The content is organized as follows:
+1. This summary section
+2. Repository information
+3. Repository structure
+4. Multiple file entries, each consisting of:
+   a. A header with the file path (## File: path/to/file)
+   b. The full contents of the file in a code block
+
+## Usage Guidelines:
+
+- This file should be treated as read-only. Any changes should be made to the
+  original repository files, not this packed version.
+- When processing this file, use the file path to distinguish
+  between different files in the repository.
+- Be aware that this file may contain sensitive information. Handle it with
+  the same level of security as you would the original repository.
+
+## Notes:
+
+- Some files may have been excluded based on .gitignore rules and Repomix's
+  configuration.
+- Binary files are not included in this packed representation. Please refer to
+  the Repository Structure section for a complete list of file paths, including
+  binary files.
+
+## Additional Information:
+
+For more information about Repomix, visit: https://github.com/andersonby/python-repomix
+
+
+# Repository Structure
+
+```
+App.tsx
+components
+  ActivityFeed.tsx
+  CodeReferencesPanel.tsx
+  EmbeddingStatus.tsx
+  FileTreePanel.tsx
+  GraphCanvas.tsx
+  Header.tsx
+  IntelligentClusteringModal.tsx
+  LoadingOverlay.tsx
+  MarkdownRenderer.tsx
+  MCPToggle.tsx
+  MermaidDiagram.tsx
+  QueryFAB.tsx
+  RightPanel.tsx
+  StatusBar.tsx
+  ToolCallCard.tsx
+  WebGPUFallbackDialog.tsx
+config
+  ignore-service.ts
+  supported-languages.ts
+core
+  embeddings
+    embedder.ts
+    embedding-pipeline.ts
+    index.ts
+    text-generator.ts
+    types.ts
+  graph
+    graph.ts
+    types.ts
+  ingestion
+    ast-cache.ts
+    call-processor.ts
+    cluster-enricher.ts
+    community-processor.ts
+    heritage-processor.ts
+    import-processor.ts
+    parsing-processor.ts
+    pipeline.ts
+    structure-processor.ts
+    symbol-table.ts
+    tree-sitter-queries.ts
+    utils.ts
+  kuzu
+    csv-generator.ts
+    kuzu-adapter.ts
+    schema.ts
+  llm
+    agent.ts
+    context-builder.ts
+    index.ts
+    settings-service.ts
+  mcp
+    mcp-client.ts
+  search
+    hybrid-search.ts
+    index.ts
+  tree-sitter
+    parser-loader.ts
+hooks
+  useAppState.tsx
+  useSigma.ts
+index.css
+main.tsx
+services
+  zip.ts
+types
+  kuzu-wasm.d.ts
+  pipeline.ts
+vite-env.d.ts
+workers
+  ingestion.worker.ts
+```
+
+# Repository Files
+
+
+## App.tsx
+
+```text
+import { useCallback, useRef } from 'react';
+import { AppStateProvider, useAppState } from './hooks/useAppState';
+import { DropZone } from './components/DropZone';
+import { LoadingOverlay } from './components/LoadingOverlay';
+import { Header } from './components/Header';
+import { GraphCanvas, GraphCanvasHandle } from './components/GraphCanvas';
+import { RightPanel } from './components/RightPanel';
+import { SettingsPanel } from './components/SettingsPanel';
+import { StatusBar } from './components/StatusBar';
+import { FileTreePanel } from './components/FileTreePanel';
+import { CodeReferencesPanel } from './components/CodeReferencesPanel';
+import { FileEntry } from './services/zip';
+import { getActiveProviderConfig } from './core/llm/settings-service';
+
+const AppContent = () => {
+  const {
+    viewMode,
+    setViewMode,
+    setGraph,
+    setFileContents,
+    setProgress,
+    setProjectName,
+    progress,
+    isRightPanelOpen,
+    runPipeline,
+    runPipelineFromFiles,
+    isSettingsPanelOpen,
+    setSettingsPanelOpen,
+    refreshLLMSettings,
+    initializeAgent,
+    startEmbeddings,
+    embeddingStatus,
+    codeReferences,
+    selectedNode,
+    isCodePanelOpen,
+  } = useAppState();
+
+  const graphCanvasRef = useRef<GraphCanvasHandle>(null);
+
+  const handleFileSelect = useCallback(async (file: File) => {
+    const projectName = file.name.replace('.zip', '');
+    setProjectName(projectName);
+    setViewMode('loading');
+
+    try {
+      const result = await runPipeline(file, (progress) => {
+        setProgress(progress);
+      });
+
+      setGraph(result.graph);
+      setFileContents(result.fileContents);
+      setViewMode('exploring');
+
+      // Initialize (or re-initialize) the agent AFTER a repo loads so it captures
+      // the current codebase context (file contents + graph tools) in the worker.
+      if (getActiveProviderConfig()) {
+        initializeAgent(projectName);
+      }
+
+      // Auto-start embeddings pipeline in background
+      // Uses WebGPU if available, falls back to WASM
+      startEmbeddings().catch((err) => {
+        // WebGPU not available - try WASM fallback silently
+        if (err?.name === 'WebGPUNotAvailableError' || err?.message?.includes('WebGPU')) {
+          startEmbeddings('wasm').catch(console.warn);
+        } else {
+          console.warn('Embeddings auto-start failed:', err);
+        }
+      });
+    } catch (error) {
+      console.error('Pipeline error:', error);
+      setProgress({
+        phase: 'error',
+        percent: 0,
+        message: 'Error processing file',
+        detail: error instanceof Error ? error.message : 'Unknown error',
+      });
+      setTimeout(() => {
+        setViewMode('onboarding');
+        setProgress(null);
+      }, 3000);
+    }
+  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipeline, startEmbeddings, initializeAgent]);
+
+  const handleGitClone = useCallback(async (files: FileEntry[]) => {
+    // Extract project name from first file path (e.g., "owner-repo-123/src/..." -> "owner-repo")
+    const firstPath = files[0]?.path || 'repository';
+    const projectName = firstPath.split('/')[0].replace(/-\d+$/, '') || 'repository';
+
+    setProjectName(projectName);
+    setViewMode('loading');
+
+    try {
+      const result = await runPipelineFromFiles(files, (progress) => {
+        setProgress(progress);
+      });
+
+      setGraph(result.graph);
+      setFileContents(result.fileContents);
+      setViewMode('exploring');
+
+      // Initialize (or re-initialize) the agent AFTER a repo loads so it captures
+      // the current codebase context (file contents + graph tools) in the worker.
+      if (getActiveProviderConfig()) {
+        initializeAgent(projectName);
+      }
+
+      // Auto-start embeddings pipeline in background
+      // Uses WebGPU if available, falls back to WASM
+      startEmbeddings().catch((err) => {
+        // WebGPU not available - try WASM fallback silently
+        if (err?.name === 'WebGPUNotAvailableError' || err?.message?.includes('WebGPU')) {
+          startEmbeddings('wasm').catch(console.warn);
+        } else {
+          console.warn('Embeddings auto-start failed:', err);
+        }
+      });
+    } catch (error) {
+      console.error('Pipeline error:', error);
+      setProgress({
+        phase: 'error',
+        percent: 0,
+        message: 'Error processing repository',
+        detail: error instanceof Error ? error.message : 'Unknown error',
+      });
+      setTimeout(() => {
+        setViewMode('onboarding');
+        setProgress(null);
+      }, 3000);
+    }
+  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipelineFromFiles, startEmbeddings, initializeAgent]);
+
+  const handleFocusNode = useCallback((nodeId: string) => {
+    graphCanvasRef.current?.focusNode(nodeId);
+  }, []);
+
+  // Handle settings saved - refresh and reinitialize agent
+  // NOTE: Must be defined BEFORE any conditional returns (React hooks rule)
+  const handleSettingsSaved = useCallback(() => {
+    refreshLLMSettings();
+    initializeAgent();
+  }, [refreshLLMSettings, initializeAgent]);
+
+  // Render based on view mode
+  if (viewMode === 'onboarding') {
+    return <DropZone onFileSelect={handleFileSelect} onGitClone={handleGitClone} />;
+  }
+
+  if (viewMode === 'loading' && progress) {
+    return <LoadingOverlay progress={progress} />;
+  }
+
+  // Exploring view
+  return (
+    <div className="flex flex-col h-screen bg-void overflow-hidden">
+      <Header onFocusNode={handleFocusNode} />
+
+      <main className="flex-1 flex min-h-0">
+        {/* Left Panel - File Tree */}
+        <FileTreePanel onFocusNode={handleFocusNode} />
+
+        {/* Graph area - takes remaining space */}
+        <div className="flex-1 relative min-w-0">
+          <GraphCanvas ref={graphCanvasRef} />
+
+          {/* Code References Panel (overlay) - does NOT resize the graph, it overlaps on top */}
+          {isCodePanelOpen && (codeReferences.length > 0 || !!selectedNode) && (
+            <div className="absolute inset-y-0 left-0 z-30 pointer-events-auto">
+              <CodeReferencesPanel onFocusNode={handleFocusNode} />
+            </div>
+          )}
+        </div>
+
+        {/* Right Panel - Code & Chat (tabbed) */}
+        {isRightPanelOpen && <RightPanel />}
+      </main>
+
+      <StatusBar />
+
+      {/* Settings Panel (modal) */}
+      <SettingsPanel
+        isOpen={isSettingsPanelOpen}
+        onClose={() => setSettingsPanelOpen(false)}
+        onSettingsSaved={handleSettingsSaved}
+      />
+    </div>
+  );
+};
+
+function App() {
+  return (
+    <AppStateProvider>
+      <AppContent />
+    </AppStateProvider>
+  );
+}
+
+export default App;
+```
+
+## components/ActivityFeed.tsx
+
+```text
+/**
+ * Activity Feed Component
+ * 
+ * Shows real-time log of external AI agent tool calls.
+ * Used in RightPanel as an alternative to the Chat tab.
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import { Activity, Search, Database, Terminal, Eye, Loader2, CheckCircle, XCircle, Clock, FileText, Zap } from 'lucide-react';
+import { getMCPClient, type ActivityEvent } from '../core/mcp/mcp-client';
+
+// Tool icons
+const TOOL_ICONS: Record<string, typeof Search> = {
+    context: Zap,
+    search: Search,
+    cypher: Database,
+    grep: Terminal,
+    read: FileText,
+    blastRadius: Activity,
+    highlight: Eye,
+};
+
+// Tool colors
+const TOOL_COLORS: Record<string, string> = {
+    context: 'text-amber-400',
+    search: 'text-cyan-400',
+    cypher: 'text-purple-400',
+    grep: 'text-green-400',
+    read: 'text-blue-400',
+    blastRadius: 'text-rose-400',
+    highlight: 'text-teal-400',
+};
+
+export function ActivityFeed() {
+    const [events, setEvents] = useState<ActivityEvent[]>([]);
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        const client = getMCPClient();
+
+        // Subscribe to activity events
+        const unsubscribe = client.onActivity((event) => {
+            setEvents(prev => {
+                // Keep max 100 events
+                const next = [...prev, event];
+                if (next.length > 100) {
+                    next.shift();
+                }
+                return next;
+            });
+        });
+
+        // Get existing events
+        setEvents(client.getActivityLog());
+
+        return () => {
+            unsubscribe();
+        };
+    }, []);
+
+    // Auto-scroll to bottom
+    useEffect(() => {
+        if (containerRef.current) {
+            containerRef.current.scrollTop = containerRef.current.scrollHeight;
+        }
+    }, [events]);
+
+    const formatTime = (timestamp: number) => {
+        const date = new Date(timestamp);
+        return date.toLocaleTimeString('en-US', {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+    };
+
+    const formatParams = (params: any): string => {
+        if (!params) return '';
+        // Show first key-value pairs, truncated
+        const entries = Object.entries(params).slice(0, 2);
+        return entries.map(([k, v]) => {
+            const val = typeof v === 'string' ? v.slice(0, 30) : JSON.stringify(v).slice(0, 30);
+            return `${k}: ${val}${val.length >= 30 ? '...' : ''}`;
+        }).join(', ');
+    };
+
+    const formatResult = (event: ActivityEvent): string => {
+        if (event.status === 'running') return 'Running...';
+        if (event.status === 'error') return `Error: ${event.error?.slice(0, 50) || 'Unknown'}`;
+
+        // Format result based on type
+        if (Array.isArray(event.result)) {
+            return `${event.result.length} results`;
+        }
+        if (typeof event.result === 'object' && event.result) {
+            const keys = Object.keys(event.result);
+            if (keys.includes('content')) return `${event.result.content?.length || 0} chars`;
+            if (keys.includes('projectName')) return event.result.projectName;
+            return `{${keys.slice(0, 3).join(', ')}${keys.length > 3 ? '...' : ''}}`;
+        }
+        return String(event.result || 'Done');
+    };
+
+    if (events.length === 0) {
+        return (
+            <div className="flex flex-col items-center justify-center h-full text-center px-8">
+                <div className="w-14 h-14 mb-4 flex items-center justify-center bg-gradient-to-br from-accent to-node-class rounded-xl shadow-glow text-2xl">
+                    📡
+                </div>
+                <h3 className="text-base font-medium mb-2">
+                    No Agent Activity
+                </h3>
+                <p className="text-sm text-text-secondary leading-relaxed">
+                    When external AI agents (Cursor, Claude Code) call GitNexus tools,
+                    their activity will appear here in real-time.
+                </p>
+                <p className="text-xs text-text-muted mt-4">
+                    Make sure MCP toggle is enabled in the header
+                </p>
+            </div>
+        );
+    }
+
+    return (
+        <div ref={containerRef} className="flex-1 overflow-y-auto p-4 scrollbar-thin">
+            <div className="space-y-3">
+                {events.map((event) => {
+                    const Icon = TOOL_ICONS[event.tool] || Activity;
+                    const color = TOOL_COLORS[event.tool] || 'text-text-muted';
+
+                    return (
+                        <div
+                            key={event.id}
+                            className="bg-elevated border border-border-subtle rounded-lg p-3 animate-fade-in"
+                        >
+                            {/* Header row */}
+                            <div className="flex items-center gap-2 mb-2">
+                                {/* Agent color indicator */}
+                                {event.agentColor && (
+                                    <div
+                                        className="w-2 h-2 rounded-full shrink-0"
+                                        style={{ backgroundColor: event.agentColor }}
+                                        title={event.agentName || 'Unknown agent'}
+                                    />
+                                )}
+                                <Icon className={`w-4 h-4 ${color}`} />
+                                <span className="font-medium text-sm">{event.tool}</span>
+                                {event.agentName && event.agentName !== 'Unknown' && (
+                                    <span
+                                        className="text-[10px] px-1.5 py-0.5 rounded-full"
+                                        style={{
+                                            backgroundColor: `${event.agentColor}20`,
+                                            color: event.agentColor
+                                        }}
+                                    >
+                                        {event.agentName}
+                                    </span>
+                                )}
+                                <span className="text-xs text-text-muted ml-auto flex items-center gap-1">
+                                    <Clock className="w-3 h-3" />
+                                    {formatTime(event.timestamp)}
+                                </span>
+                            </div>
+
+                            {/* Params preview */}
+                            {event.params && Object.keys(event.params).length > 0 && (
+                                <div className="text-xs text-text-secondary font-mono bg-deep rounded px-2 py-1 mb-2 truncate">
+                                    {formatParams(event.params)}
+                                </div>
+                            )}
+
+                            {/* Status/Result */}
+                            <div className="flex items-center gap-2 text-xs">
+                                {event.status === 'running' && (
+                                    <>
+                                        <Loader2 className="w-3 h-3 animate-spin text-accent" />
+                                        <span className="text-accent">Running...</span>
+                                    </>
+                                )}
+                                {event.status === 'complete' && (
+                                    <>
+                                        <CheckCircle className="w-3 h-3 text-green-400" />
+                                        <span className="text-text-secondary">{formatResult(event)}</span>
+                                        {event.duration && (
+                                            <span className="text-text-muted ml-auto">{event.duration}ms</span>
+                                        )}
+                                    </>
+                                )}
+                                {event.status === 'error' && (
+                                    <>
+                                        <XCircle className="w-3 h-3 text-rose-400" />
+                                        <span className="text-rose-300">{formatResult(event)}</span>
+                                    </>
+                                )}
+                            </div>
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
+```
+
+## components/CodeReferencesPanel.tsx
+
+```text
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Code, PanelLeftClose, PanelLeft, Trash2, X, Target, FileCode, Sparkles, MousePointerClick } from 'lucide-react';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import { useAppState } from '../hooks/useAppState';
+import { NODE_COLORS } from '../lib/constants';
+
+// Match the code theme used elsewhere in the app
+const customTheme = {
+  ...vscDarkPlus,
+  'pre[class*="language-"]': {
+    ...vscDarkPlus['pre[class*="language-"]'],
+    background: '#0a0a10',
+    margin: 0,
+    padding: '12px 0',
+    fontSize: '13px',
+    lineHeight: '1.6',
+  },
+  'code[class*="language-"]': {
+    ...vscDarkPlus['code[class*="language-"]'],
+    background: 'transparent',
+    fontFamily: '"JetBrains Mono", "Fira Code", monospace',
+  },
+};
+
+export interface CodeReferencesPanelProps {
+  onFocusNode: (nodeId: string) => void;
+}
+
+export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) => {
+  const {
+    graph,
+    fileContents,
+    selectedNode,
+    codeReferences,
+    removeCodeReference,
+    clearCodeReferences,
+    setSelectedNode,
+    codeReferenceFocus,
+  } = useAppState();
+
+  const [isCollapsed, setIsCollapsed] = useState(false);
+  const [glowRefId, setGlowRefId] = useState<string | null>(null);
+  const panelRef = useRef<HTMLElement | null>(null);
+  const resizeRef = useRef<{ startX: number; startWidth: number } | null>(null);
+  const refCardEls = useRef<Map<string, HTMLDivElement | null>>(new Map());
+  const glowTimerRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (glowTimerRef.current) {
+        window.clearTimeout(glowTimerRef.current);
+        glowTimerRef.current = null;
+      }
+    };
+  }, []);
+
+  const [panelWidth, setPanelWidth] = useState<number>(() => {
+    try {
+      const saved = window.localStorage.getItem('gitnexus.codePanelWidth');
+      const parsed = saved ? parseInt(saved, 10) : NaN;
+      if (!Number.isFinite(parsed)) return 560; // increased default
+      return Math.max(420, Math.min(parsed, 900));
+    } catch {
+      return 560;
+    }
+  });
+
+  useEffect(() => {
+    try {
+      window.localStorage.setItem('gitnexus.codePanelWidth', String(panelWidth));
+    } catch {
+      // ignore
+    }
+  }, [panelWidth]);
+
+  const startResize = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    resizeRef.current = { startX: e.clientX, startWidth: panelWidth };
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+
+    const onMove = (ev: MouseEvent) => {
+      const state = resizeRef.current;
+      if (!state) return;
+      const delta = ev.clientX - state.startX;
+      const next = Math.max(420, Math.min(state.startWidth + delta, 900));
+      setPanelWidth(next);
+    };
+
+    const onUp = () => {
+      resizeRef.current = null;
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+  }, [panelWidth]);
+
+  const aiReferences = useMemo(() => codeReferences.filter(r => r.source === 'ai'), [codeReferences]);
+
+  // When the user clicks a citation badge in chat, focus the corresponding snippet card:
+  // - expand the panel if collapsed
+  // - smooth-scroll the card into view
+  // - briefly glow it for discoverability
+  useEffect(() => {
+    if (!codeReferenceFocus) return;
+
+    // Ensure panel is expanded
+    setIsCollapsed(false);
+
+    const { filePath, startLine, endLine } = codeReferenceFocus;
+    const target =
+      aiReferences.find(r =>
+        r.filePath === filePath &&
+        r.startLine === startLine &&
+        r.endLine === endLine
+      ) ??
+      aiReferences.find(r => r.filePath === filePath);
+
+    if (!target) return;
+
+    // Double rAF: wait for collapse state + list DOM to render.
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        const el = refCardEls.current.get(target.id);
+        if (!el) return;
+
+        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        setGlowRefId(target.id);
+
+        if (glowTimerRef.current) {
+          window.clearTimeout(glowTimerRef.current);
+        }
+        glowTimerRef.current = window.setTimeout(() => {
+          setGlowRefId((prev) => (prev === target.id ? null : prev));
+          glowTimerRef.current = null;
+        }, 1200);
+      });
+    });
+  }, [codeReferenceFocus?.ts, aiReferences]);
+
+  const refsWithSnippets = useMemo(() => {
+    return aiReferences.map((ref) => {
+      const content = fileContents.get(ref.filePath);
+      if (!content) {
+        return { ref, content: null as string | null, start: 0, end: 0, highlightStart: 0, highlightEnd: 0, totalLines: 0 };
+      }
+
+      const lines = content.split('\n');
+      const totalLines = lines.length;
+
+      const startLine = ref.startLine ?? 0;
+      const endLine = ref.endLine ?? startLine;
+
+      const contextBefore = 3;
+      const contextAfter = 20;
+      const start = Math.max(0, startLine - contextBefore);
+      const end = Math.min(totalLines - 1, endLine + contextAfter);
+
+      return {
+        ref,
+        content: lines.slice(start, end + 1).join('\n'),
+        start,
+        end,
+        highlightStart: Math.max(0, startLine - start),
+        highlightEnd: Math.max(0, endLine - start),
+        totalLines,
+      };
+    });
+  }, [aiReferences, fileContents]);
+
+  const selectedFilePath = selectedNode?.properties?.filePath;
+  const selectedFileContent = selectedFilePath ? fileContents.get(selectedFilePath) : undefined;
+  const selectedIsFile = selectedNode?.label === 'File' && !!selectedFilePath;
+  const showSelectedViewer = !!selectedNode && !!selectedFilePath;
+  const showCitations = aiReferences.length > 0;
+
+  if (isCollapsed) {
+    return (
+      <aside className="h-full w-12 bg-surface border-r border-border-subtle flex flex-col items-center py-3 gap-2 flex-shrink-0">
+        <button
+          onClick={() => setIsCollapsed(false)}
+          className="p-2 text-text-secondary hover:text-cyan-400 hover:bg-cyan-500/10 rounded transition-colors"
+          title="Expand Code Panel"
+        >
+          <PanelLeft className="w-5 h-5" />
+        </button>
+        <div className="w-6 h-px bg-border-subtle my-1" />
+        {showSelectedViewer && (
+          <div className="text-[9px] text-amber-400 rotate-90 whitespace-nowrap font-medium tracking-wide">
+            SELECTED
+          </div>
+        )}
+        {showCitations && (
+          <div className="text-[9px] text-cyan-400 rotate-90 whitespace-nowrap font-medium tracking-wide mt-4">
+            AI • {aiReferences.length}
+          </div>
+        )}
+      </aside>
+    );
+  }
+
+  return (
+    <aside
+      ref={(el) => { panelRef.current = el; }}
+      className="h-full bg-surface/95 backdrop-blur-md border-r border-border-subtle flex flex-col animate-slide-in relative shadow-2xl"
+      style={{ width: panelWidth }}
+    >
+      {/* Resize handle */}
+      <div
+        onMouseDown={startResize}
+        className="absolute top-0 right-0 h-full w-2 cursor-col-resize bg-transparent hover:bg-cyan-500/25 transition-colors"
+        title="Drag to resize"
+      />
+      {/* Header */}
+      <div className="flex items-center justify-between px-3 py-2.5 border-b border-border-subtle bg-gradient-to-r from-elevated/60 to-surface/60">
+        <div className="flex items-center gap-2">
+          <Code className="w-4 h-4 text-cyan-400" />
+          <span className="text-sm font-semibold text-text-primary">Code Inspector</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          {showCitations && (
+            <button
+              onClick={() => clearCodeReferences()}
+              className="p-1.5 text-text-muted hover:text-red-400 hover:bg-red-500/10 rounded transition-colors"
+              title="Clear AI citations"
+            >
+              <Trash2 className="w-4 h-4" />
+            </button>
+          )}
+          <button
+            onClick={() => setIsCollapsed(true)}
+            className="p-1.5 text-text-muted hover:text-text-primary hover:bg-hover rounded transition-colors"
+            title="Collapse Panel"
+          >
+            <PanelLeftClose className="w-4 h-4" />
+          </button>
+        </div>
+      </div>
+
+      <div className="flex-1 min-h-0 flex flex-col">
+        {/* Top: Selected file viewer (when a node is selected) */}
+        {showSelectedViewer && (
+          <div className={`${showCitations ? 'h-[42%]' : 'flex-1'} min-h-0 flex flex-col`}>
+            <div className="px-3 py-2 bg-gradient-to-r from-amber-500/8 to-orange-500/5 border-b border-amber-500/20 flex items-center gap-2">
+              <div className="flex items-center gap-1.5 px-2 py-0.5 bg-amber-500/15 rounded-md border border-amber-500/25">
+                <MousePointerClick className="w-3 h-3 text-amber-400" />
+                <span className="text-[10px] text-amber-300 font-semibold uppercase tracking-wide">Selected</span>
+              </div>
+              <FileCode className="w-3.5 h-3.5 text-amber-400/70 ml-1" />
+              <span className="text-xs text-text-primary font-mono truncate flex-1">
+                {selectedNode?.properties?.filePath?.split('/').pop() ?? selectedNode?.properties?.name}
+              </span>
+              <button
+                onClick={() => setSelectedNode(null)}
+                className="p-1 text-text-muted hover:text-amber-400 hover:bg-amber-500/10 rounded transition-colors"
+                title="Clear selection"
+              >
+                <X className="w-4 h-4" />
+              </button>
+            </div>
+            <div className="flex-1 min-h-0 overflow-auto scrollbar-thin">
+              {selectedFileContent ? (
+                <SyntaxHighlighter
+                  language={
+                    selectedFilePath?.endsWith('.py') ? 'python' :
+                    selectedFilePath?.endsWith('.js') || selectedFilePath?.endsWith('.jsx') ? 'javascript' :
+                    selectedFilePath?.endsWith('.ts') || selectedFilePath?.endsWith('.tsx') ? 'typescript' :
+                    'text'
+                  }
+                  style={customTheme as any}
+                  showLineNumbers
+                  startingLineNumber={1}
+                  lineNumberStyle={{
+                    minWidth: '3em',
+                    paddingRight: '1em',
+                    color: '#5a5a70',
+                    textAlign: 'right',
+                    userSelect: 'none',
+                  }}
+                  lineProps={(lineNumber) => {
+                    const startLine = selectedNode?.properties?.startLine;
+                    const endLine = selectedNode?.properties?.endLine ?? startLine;
+                    const isHighlighted =
+                      typeof startLine === 'number' &&
+                      lineNumber >= startLine + 1 &&
+                      lineNumber <= (endLine ?? startLine) + 1;
+                    return {
+                      style: {
+                        display: 'block',
+                        backgroundColor: isHighlighted ? 'rgba(6, 182, 212, 0.14)' : 'transparent',
+                        borderLeft: isHighlighted ? '3px solid #06b6d4' : '3px solid transparent',
+                        paddingLeft: '12px',
+                        paddingRight: '16px',
+                      },
+                    };
+                  }}
+                  wrapLines
+                >
+                  {selectedFileContent}
+                </SyntaxHighlighter>
+              ) : (
+                <div className="px-3 py-3 text-sm text-text-muted">
+                  {selectedIsFile ? (
+                    <>Code not available in memory for <span className="font-mono">{selectedFilePath}</span></>
+                  ) : (
+                    <>Select a file node to preview its contents.</>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Divider between Selected viewer and AI refs (more visible) */}
+        {showSelectedViewer && showCitations && (
+          <div className="h-1.5 bg-gradient-to-r from-transparent via-border-subtle to-transparent" />
+        )}
+
+        {/* Bottom: AI citations list */}
+        {showCitations && (
+          <div className="flex-1 min-h-0 flex flex-col">
+            {/* AI Citations Section Header */}
+            <div className="px-3 py-2 bg-gradient-to-r from-cyan-500/8 to-teal-500/5 border-b border-cyan-500/20 flex items-center gap-2">
+              <div className="flex items-center gap-1.5 px-2 py-0.5 bg-cyan-500/15 rounded-md border border-cyan-500/25">
+                <Sparkles className="w-3 h-3 text-cyan-400" />
+                <span className="text-[10px] text-cyan-300 font-semibold uppercase tracking-wide">AI Citations</span>
+              </div>
+              <span className="text-xs text-text-muted ml-1">{aiReferences.length} reference{aiReferences.length !== 1 ? 's' : ''}</span>
+            </div>
+            <div className="flex-1 min-h-0 overflow-y-auto scrollbar-thin p-3 space-y-3">
+            {refsWithSnippets.map(({ ref, content, start, highlightStart, highlightEnd, totalLines }) => {
+          const nodeColor = ref.label ? (NODE_COLORS as any)[ref.label] || '#6b7280' : '#6b7280';
+          const hasRange = typeof ref.startLine === 'number';
+          const startDisplay = hasRange ? (ref.startLine ?? 0) + 1 : undefined;
+          const endDisplay = hasRange ? (ref.endLine ?? ref.startLine ?? 0) + 1 : undefined;
+          const language =
+            ref.filePath.endsWith('.py') ? 'python' :
+            ref.filePath.endsWith('.js') || ref.filePath.endsWith('.jsx') ? 'javascript' :
+            ref.filePath.endsWith('.ts') || ref.filePath.endsWith('.tsx') ? 'typescript' :
+            'text';
+
+          const isGlowing = glowRefId === ref.id;
+
+          return (
+            <div
+              key={ref.id}
+              ref={(el) => { refCardEls.current.set(ref.id, el); }}
+              className={[
+                'bg-elevated border border-border-subtle rounded-xl overflow-hidden transition-all',
+                isGlowing ? 'ring-2 ring-cyan-300/70 shadow-[0_0_0_6px_rgba(34,211,238,0.14)] animate-pulse' : '',
+              ].join(' ')}
+            >
+              <div className="px-3 py-2 border-b border-border-subtle bg-surface/40 flex items-start gap-2">
+                <span
+                  className="mt-0.5 px-2 py-0.5 rounded text-[10px] font-semibold uppercase tracking-wide flex-shrink-0"
+                  style={{ backgroundColor: nodeColor, color: '#06060a' }}
+                  title={ref.label ?? 'Code'}
+                >
+                  {ref.label ?? 'Code'}
+                </span>
+                <div className="min-w-0 flex-1">
+                  <div className="text-xs text-text-primary font-medium truncate">
+                    {ref.name ?? ref.filePath.split('/').pop() ?? ref.filePath}
+                  </div>
+                  <div className="text-[11px] text-text-muted font-mono truncate">
+                    {ref.filePath}
+                    {startDisplay !== undefined && (
+                      <span className="text-text-secondary">
+                        {' '}
+                        • L{startDisplay}
+                        {endDisplay !== startDisplay ? `–${endDisplay}` : ''}
+                      </span>
+                    )}
+                    {totalLines > 0 && <span className="text-text-muted"> • {totalLines} lines</span>}
+                  </div>
+                </div>
+                <div className="flex items-center gap-1">
+                  {ref.nodeId && (
+                    <button
+                      onClick={() => {
+                        const nodeId = ref.nodeId!;
+                        // Sync selection + focus graph
+                        if (graph) {
+                          const node = graph.nodes.find((n) => n.id === nodeId);
+                          if (node) setSelectedNode(node);
+                        }
+                        onFocusNode(nodeId);
+                      }}
+                      className="p-1.5 text-text-muted hover:text-text-primary hover:bg-hover rounded transition-colors"
+                      title="Focus in graph"
+                    >
+                      <Target className="w-4 h-4" />
+                    </button>
+                  )}
+                  <button
+                    onClick={() => removeCodeReference(ref.id)}
+                    className="p-1.5 text-text-muted hover:text-text-primary hover:bg-hover rounded transition-colors"
+                    title="Remove"
+                  >
+                    <X className="w-4 h-4" />
+                  </button>
+                </div>
+              </div>
+
+              <div className="overflow-x-auto">
+                {content ? (
+                  <SyntaxHighlighter
+                    language={language}
+                    style={customTheme as any}
+                    showLineNumbers
+                    startingLineNumber={start + 1}
+                    lineNumberStyle={{
+                      minWidth: '3em',
+                      paddingRight: '1em',
+                      color: '#5a5a70',
+                      textAlign: 'right',
+                      userSelect: 'none',
+                    }}
+                    lineProps={(lineNumber) => {
+                      const isHighlighted =
+                        hasRange &&
+                        lineNumber >= start + highlightStart + 1 &&
+                        lineNumber <= start + highlightEnd + 1;
+                      return {
+                        style: {
+                          display: 'block',
+                          backgroundColor: isHighlighted ? 'rgba(6, 182, 212, 0.14)' : 'transparent',
+                          borderLeft: isHighlighted ? '3px solid #06b6d4' : '3px solid transparent',
+                          paddingLeft: '12px',
+                          paddingRight: '16px',
+                        },
+                      };
+                    }}
+                    wrapLines
+                  >
+                    {content}
+                  </SyntaxHighlighter>
+                ) : (
+                  <div className="px-3 py-3 text-sm text-text-muted">
+                    Code not available in memory for <span className="font-mono">{ref.filePath}</span>
+                  </div>
+                )}
+              </div>
+            </div>
+          );
+            })}
+            </div>
+          </div>
+        )}
+      </div>
+    </aside>
+  );
+};
+```
+
+## components/EmbeddingStatus.tsx
+
+```text
+import { Brain, Loader2, Check, AlertCircle, Zap, FlaskConical } from 'lucide-react';
+import { useAppState } from '../hooks/useAppState';
+import { useState } from 'react';
+import { WebGPUFallbackDialog } from './WebGPUFallbackDialog';
+
+/**
+ * Embedding status indicator and trigger button
+ * Shows in header when graph is loaded
+ */
+export const EmbeddingStatus = () => {
+  const { 
+    embeddingStatus, 
+    embeddingProgress, 
+    startEmbeddings, 
+    graph,
+    viewMode,
+    testArrayParams,
+  } = useAppState();
+  
+  const [testResult, setTestResult] = useState<string | null>(null);
+  const [showFallbackDialog, setShowFallbackDialog] = useState(false);
+
+  // Only show when exploring a loaded graph
+  if (viewMode !== 'exploring' || !graph) return null;
+
+  const nodeCount = graph.nodes.length;
+
+  const handleStartEmbeddings = async (forceDevice?: 'webgpu' | 'wasm') => {
+    try {
+      await startEmbeddings(forceDevice);
+    } catch (error: any) {
+      // Check if it's a WebGPU not available error
+      if (error?.name === 'WebGPUNotAvailableError' || 
+          error?.message?.includes('WebGPU not available')) {
+        setShowFallbackDialog(true);
+      } else {
+        console.error('Embedding failed:', error);
+      }
+    }
+  };
+
+  const handleUseCPU = () => {
+    setShowFallbackDialog(false);
+    handleStartEmbeddings('wasm');
+  };
+
+  const handleSkipEmbeddings = () => {
+    setShowFallbackDialog(false);
+    // Just close - user can try again later if they want
+  };
+  
+  const handleTestArrayParams = async () => {
+    setTestResult('Testing...');
+    const result = await testArrayParams();
+    if (result.success) {
+      setTestResult('✅ Array params WORK!');
+      console.log('✅ Array params test passed!');
+    } else {
+      setTestResult(`❌ ${result.error}`);
+      console.error('❌ Array params test failed:', result.error);
+    }
+  };
+
+  // WebGPU fallback dialog - rendered independently of state
+  const fallbackDialog = (
+    <WebGPUFallbackDialog
+      isOpen={showFallbackDialog}
+      onClose={() => setShowFallbackDialog(false)}
+      onUseCPU={handleUseCPU}
+      onSkip={handleSkipEmbeddings}
+      nodeCount={nodeCount}
+    />
+  );
+
+  // Idle state - show button to start
+  if (embeddingStatus === 'idle') {
+    return (
+      <>
+        <div className="flex items-center gap-2">
+          {/* Test button (dev only) */}
+          {import.meta.env.DEV && (
+            <button
+              onClick={handleTestArrayParams}
+              className="flex items-center gap-1 px-2 py-1.5 bg-surface border border-border-subtle rounded-lg text-xs text-text-muted hover:bg-hover hover:text-text-secondary transition-all"
+              title="Test if KuzuDB supports array params"
+            >
+              <FlaskConical className="w-3 h-3" />
+              {testResult || 'Test'}
+            </button>
+          )}
+          
+          <button
+            onClick={() => handleStartEmbeddings()}
+            className="flex items-center gap-2 px-3 py-1.5 bg-surface border border-border-subtle rounded-lg text-sm text-text-secondary hover:bg-hover hover:text-text-primary hover:border-accent/50 transition-all group"
+            title="Generate embeddings for semantic search"
+          >
+            <Brain className="w-4 h-4 text-node-interface group-hover:text-accent transition-colors" />
+            <span className="hidden sm:inline">Enable Semantic Search</span>
+            <Zap className="w-3 h-3 text-text-muted" />
+          </button>
+        </div>
+        {fallbackDialog}
+      </>
+    );
+  }
+
+  // Loading model
+  if (embeddingStatus === 'loading') {
+    const downloadPercent = embeddingProgress?.modelDownloadPercent ?? 0;
+    return (
+      <>
+        <div className="flex items-center gap-2.5 px-3 py-1.5 bg-surface border border-accent/30 rounded-lg text-sm">
+          <Loader2 className="w-4 h-4 text-accent animate-spin" />
+          <div className="flex flex-col gap-0.5">
+            <span className="text-text-secondary text-xs">Loading AI model...</span>
+            <div className="w-24 h-1 bg-elevated rounded-full overflow-hidden">
+              <div 
+                className="h-full bg-gradient-to-r from-accent to-node-interface rounded-full transition-all duration-300"
+                style={{ width: `${downloadPercent}%` }}
+              />
+            </div>
+          </div>
+        </div>
+        {fallbackDialog}
+      </>
+    );
+  }
+
+  // Embedding in progress
+  if (embeddingStatus === 'embedding') {
+    const processed = embeddingProgress?.nodesProcessed ?? 0;
+    const total = embeddingProgress?.totalNodes ?? 0;
+    const percent = embeddingProgress?.percent ?? 0;
+    
+    return (
+      <div className="flex items-center gap-2.5 px-3 py-1.5 bg-surface border border-node-function/30 rounded-lg text-sm">
+        <Loader2 className="w-4 h-4 text-node-function animate-spin" />
+        <div className="flex flex-col gap-0.5">
+          <span className="text-text-secondary text-xs">
+            Embedding {processed}/{total} nodes
+          </span>
+          <div className="w-24 h-1 bg-elevated rounded-full overflow-hidden">
+            <div 
+              className="h-full bg-gradient-to-r from-node-function to-accent rounded-full transition-all duration-300"
+              style={{ width: `${percent}%` }}
+            />
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // Indexing
+  if (embeddingStatus === 'indexing') {
+    return (
+      <div className="flex items-center gap-2 px-3 py-1.5 bg-surface border border-node-interface/30 rounded-lg text-sm text-text-secondary">
+        <Loader2 className="w-4 h-4 text-node-interface animate-spin" />
+        <span className="text-xs">Creating vector index...</span>
+      </div>
+    );
+  }
+
+  // Ready
+  if (embeddingStatus === 'ready') {
+    return (
+      <div 
+        className="flex items-center gap-2 px-3 py-1.5 bg-node-function/10 border border-node-function/30 rounded-lg text-sm text-node-function"
+        title="Semantic search is ready! Use natural language in the AI chat."
+      >
+        <Check className="w-4 h-4" />
+        <span className="text-xs font-medium">Semantic Ready</span>
+      </div>
+    );
+  }
+
+  // Error
+  if (embeddingStatus === 'error') {
+    return (
+      <>
+        <button
+          onClick={() => handleStartEmbeddings()}
+          className="flex items-center gap-2 px-3 py-1.5 bg-red-500/10 border border-red-500/30 rounded-lg text-sm text-red-400 hover:bg-red-500/20 transition-colors"
+          title={embeddingProgress?.error || 'Embedding failed. Click to retry.'}
+        >
+          <AlertCircle className="w-4 h-4" />
+          <span className="text-xs">Failed - Retry</span>
+        </button>
+        {fallbackDialog}
+      </>
+    );
+  }
+
+  return null;
+};
+```
+
+## components/FileTreePanel.tsx
+
+```text
+import { useState, useMemo, useCallback, useEffect } from 'react';
+import {
+  ChevronRight,
+  ChevronDown,
+  Folder,
+  FolderOpen,
+  FileCode,
+  Search,
+  Filter,
+  PanelLeftClose,
+  PanelLeft,
+  Box,
+  Braces,
+  Variable,
+  Hash,
+  Target,
+} from 'lucide-react';
+import { useAppState } from '../hooks/useAppState';
+import { FILTERABLE_LABELS, NODE_COLORS, ALL_EDGE_TYPES, EDGE_INFO, type EdgeType } from '../lib/constants';
+import { GraphNode, NodeLabel } from '../core/graph/types';
+
+// Tree node structure
+interface TreeNode {
+  id: string;
+  name: string;
+  type: 'folder' | 'file';
+  path: string;
+  children: TreeNode[];
+  graphNode?: GraphNode;
+}
+
+// Build tree from graph nodes
+const buildFileTree = (nodes: GraphNode[]): TreeNode[] => {
+  const root: TreeNode[] = [];
+  const pathMap = new Map<string, TreeNode>();
+
+  // Filter to only folders and files
+  const fileNodes = nodes.filter(n => n.label === 'Folder' || n.label === 'File');
+
+  // Sort by path to ensure parents come before children
+  fileNodes.sort((a, b) => a.properties.filePath.localeCompare(b.properties.filePath));
+
+  fileNodes.forEach(node => {
+    const parts = node.properties.filePath.split('/').filter(Boolean);
+    let currentPath = '';
+    let currentLevel = root;
+
+    parts.forEach((part, index) => {
+      currentPath = currentPath ? `${currentPath}/${part}` : part;
+
+      let existing = pathMap.get(currentPath);
+
+      if (!existing) {
+        const isLastPart = index === parts.length - 1;
+        const isFile = isLastPart && node.label === 'File';
+
+        existing = {
+          id: isLastPart ? node.id : currentPath,
+          name: part,
+          type: isFile ? 'file' : 'folder',
+          path: currentPath,
+          children: [],
+          graphNode: isLastPart ? node : undefined,
+        };
+
+        pathMap.set(currentPath, existing);
+        currentLevel.push(existing);
+      }
+
+      currentLevel = existing.children;
+    });
+  });
+
+  return root;
+};
+
+// Tree item component
+interface TreeItemProps {
+  node: TreeNode;
+  depth: number;
+  searchQuery: string;
+  onNodeClick: (node: TreeNode) => void;
+  expandedPaths: Set<string>;
+  toggleExpanded: (path: string) => void;
+  selectedPath: string | null;
+}
+
+const TreeItem = ({
+  node,
+  depth,
+  searchQuery,
+  onNodeClick,
+  expandedPaths,
+  toggleExpanded,
+  selectedPath,
+}: TreeItemProps) => {
+  const isExpanded = expandedPaths.has(node.path);
+  const isSelected = selectedPath === node.path;
+  const hasChildren = node.children.length > 0;
+
+  // Filter children based on search
+  const filteredChildren = useMemo(() => {
+    if (!searchQuery) return node.children;
+    return node.children.filter(child =>
+      child.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
+      child.children.some(c => c.name.toLowerCase().includes(searchQuery.toLowerCase()))
+    );
+  }, [node.children, searchQuery]);
+
+  // Check if this node matches search
+  const matchesSearch = searchQuery && node.name.toLowerCase().includes(searchQuery.toLowerCase());
+
+  const handleClick = () => {
+    if (hasChildren) {
+      toggleExpanded(node.path);
+    }
+    onNodeClick(node);
+  };
+
+  return (
+    <div>
+      <button
+        onClick={handleClick}
+        className={`
+          w-full flex items-center gap-1.5 px-2 py-1 text-left text-sm
+          hover:bg-hover transition-colors rounded relative
+          ${isSelected ? 'bg-amber-500/15 text-amber-300 border-l-2 border-amber-400' : 'text-text-secondary hover:text-text-primary border-l-2 border-transparent'}
+          ${matchesSearch ? 'bg-accent/10' : ''}
+        `}
+        style={{ paddingLeft: `${depth * 12 + 8}px` }}
+      >
+        {/* Expand/collapse icon */}
+        {hasChildren ? (
+          isExpanded ? (
+            <ChevronDown className="w-3.5 h-3.5 shrink-0 text-text-muted" />
+          ) : (
+            <ChevronRight className="w-3.5 h-3.5 shrink-0 text-text-muted" />
+          )
+        ) : (
+          <span className="w-3.5" />
+        )}
+
+        {/* Node icon */}
+        {node.type === 'folder' ? (
+          isExpanded ? (
+            <FolderOpen className="w-4 h-4 shrink-0" style={{ color: NODE_COLORS.Folder }} />
+          ) : (
+            <Folder className="w-4 h-4 shrink-0" style={{ color: NODE_COLORS.Folder }} />
+          )
+        ) : (
+          <FileCode className="w-4 h-4 shrink-0" style={{ color: NODE_COLORS.File }} />
+        )}
+
+        {/* Name */}
+        <span className="truncate font-mono text-xs">{node.name}</span>
+      </button>
+
+      {/* Children */}
+      {isExpanded && filteredChildren.length > 0 && (
+        <div>
+          {filteredChildren.map(child => (
+            <TreeItem
+              key={child.id}
+              node={child}
+              depth={depth + 1}
+              searchQuery={searchQuery}
+              onNodeClick={onNodeClick}
+              expandedPaths={expandedPaths}
+              toggleExpanded={toggleExpanded}
+              selectedPath={selectedPath}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// Icon for node types
+const getNodeTypeIcon = (label: NodeLabel) => {
+  switch (label) {
+    case 'Folder': return Folder;
+    case 'File': return FileCode;
+    case 'Class': return Box;
+    case 'Function': return Braces;
+    case 'Method': return Braces;
+    case 'Interface': return Hash;
+    case 'Import': return FileCode;
+    default: return Variable;
+  }
+};
+
+interface FileTreePanelProps {
+  onFocusNode: (nodeId: string) => void;
+}
+
+export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
+  const { graph, visibleLabels, toggleLabelVisibility, visibleEdgeTypes, toggleEdgeVisibility, selectedNode, setSelectedNode, openCodePanel, depthFilter, setDepthFilter } = useAppState();
+
+  const [isCollapsed, setIsCollapsed] = useState(false);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [expandedPaths, setExpandedPaths] = useState<Set<string>>(new Set());
+  const [activeTab, setActiveTab] = useState<'files' | 'filters'>('files');
+
+  // Build file tree from graph
+  const fileTree = useMemo(() => {
+    if (!graph) return [];
+    return buildFileTree(graph.nodes);
+  }, [graph]);
+
+  // Auto-expand first level on initial load
+  useEffect(() => {
+    if (fileTree.length > 0 && expandedPaths.size === 0) {
+      const firstLevel = new Set(fileTree.map(n => n.path));
+      setExpandedPaths(firstLevel);
+    }
+  }, [fileTree.length]); // Only run when tree first loads
+
+  // Auto-expand to selected file when selectedNode changes (e.g., from graph click)
+  useEffect(() => {
+    const path = selectedNode?.properties?.filePath;
+    if (!path) return;
+
+    // Expand all parent folders leading to this file
+    const parts = path.split('/').filter(Boolean);
+    const pathsToExpand: string[] = [];
+    let currentPath = '';
+
+    // Build all parent paths (exclude the last part if it's a file)
+    for (let i = 0; i < parts.length - 1; i++) {
+      currentPath = currentPath ? `${currentPath}/${parts[i]}` : parts[i];
+      pathsToExpand.push(currentPath);
+    }
+
+    if (pathsToExpand.length > 0) {
+      setExpandedPaths(prev => {
+        const next = new Set(prev);
+        pathsToExpand.forEach(p => next.add(p));
+        return next;
+      });
+    }
+  }, [selectedNode?.id]); // Trigger when selected node changes
+
+  const toggleExpanded = useCallback((path: string) => {
+    setExpandedPaths(prev => {
+      const next = new Set(prev);
+      if (next.has(path)) {
+        next.delete(path);
+      } else {
+        next.add(path);
+      }
+      return next;
+    });
+  }, []);
+
+  const handleNodeClick = useCallback((treeNode: TreeNode) => {
+    if (treeNode.graphNode) {
+      // Only focus if selecting a different node
+      const isSameNode = selectedNode?.id === treeNode.graphNode.id;
+      setSelectedNode(treeNode.graphNode);
+      openCodePanel();
+      if (!isSameNode) {
+        onFocusNode(treeNode.graphNode.id);
+      }
+    }
+  }, [setSelectedNode, openCodePanel, onFocusNode, selectedNode]);
+
+  const selectedPath = selectedNode?.properties.filePath || null;
+
+  if (isCollapsed) {
+    return (
+      <div className="h-full w-12 bg-surface border-r border-border-subtle flex flex-col items-center py-3 gap-2">
+        <button
+          onClick={() => setIsCollapsed(false)}
+          className="p-2 text-text-secondary hover:text-text-primary hover:bg-hover rounded transition-colors"
+          title="Expand Panel"
+        >
+          <PanelLeft className="w-5 h-5" />
+        </button>
+        <div className="w-6 h-px bg-border-subtle my-1" />
+        <button
+          onClick={() => { setIsCollapsed(false); setActiveTab('files'); }}
+          className={`p-2 rounded transition-colors ${activeTab === 'files' ? 'text-accent bg-accent/10' : 'text-text-secondary hover:text-text-primary hover:bg-hover'}`}
+          title="File Explorer"
+        >
+          <Folder className="w-5 h-5" />
+        </button>
+        <button
+          onClick={() => { setIsCollapsed(false); setActiveTab('filters'); }}
+          className={`p-2 rounded transition-colors ${activeTab === 'filters' ? 'text-accent bg-accent/10' : 'text-text-secondary hover:text-text-primary hover:bg-hover'}`}
+          title="Filters"
+        >
+          <Filter className="w-5 h-5" />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="h-full w-64 bg-surface border-r border-border-subtle flex flex-col animate-slide-in">
+      {/* Header */}
+      <div className="flex items-center justify-between px-3 py-2 border-b border-border-subtle">
+        <div className="flex items-center gap-1">
+          <button
+            onClick={() => setActiveTab('files')}
+            className={`px-2 py-1 text-xs rounded transition-colors ${activeTab === 'files'
+              ? 'bg-accent/20 text-accent'
+              : 'text-text-secondary hover:text-text-primary hover:bg-hover'
+              }`}
+          >
+            Explorer
+          </button>
+          <button
+            onClick={() => setActiveTab('filters')}
+            className={`px-2 py-1 text-xs rounded transition-colors ${activeTab === 'filters'
+              ? 'bg-accent/20 text-accent'
+              : 'text-text-secondary hover:text-text-primary hover:bg-hover'
+              }`}
+          >
+            Filters
+          </button>
+        </div>
+        <button
+          onClick={() => setIsCollapsed(true)}
+          className="p-1 text-text-muted hover:text-text-primary hover:bg-hover rounded transition-colors"
+          title="Collapse Panel"
+        >
+          <PanelLeftClose className="w-4 h-4" />
+        </button>
+      </div>
+
+      {activeTab === 'files' && (
+        <>
+          {/* Search */}
+          <div className="px-3 py-2 border-b border-border-subtle">
+            <div className="relative">
+              <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-text-muted" />
+              <input
+                type="text"
+                placeholder="Search files..."
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                className="w-full pl-8 pr-3 py-1.5 bg-elevated border border-border-subtle rounded text-xs text-text-primary placeholder:text-text-muted focus:outline-none focus:border-accent"
+              />
+            </div>
+          </div>
+
+          {/* File tree */}
+          <div className="flex-1 overflow-y-auto scrollbar-thin py-2">
+            {fileTree.length === 0 ? (
+              <div className="px-3 py-4 text-center text-text-muted text-xs">
+                No files loaded
+              </div>
+            ) : (
+              fileTree.map(node => (
+                <TreeItem
+                  key={node.id}
+                  node={node}
+                  depth={0}
+                  searchQuery={searchQuery}
+                  onNodeClick={handleNodeClick}
+                  expandedPaths={expandedPaths}
+                  toggleExpanded={toggleExpanded}
+                  selectedPath={selectedPath}
+                />
+              ))
+            )}
+          </div>
+        </>
+      )}
+
+      {activeTab === 'filters' && (
+        <div className="flex-1 overflow-y-auto scrollbar-thin p-3">
+          <div className="mb-3">
+            <h3 className="text-xs font-medium text-text-secondary uppercase tracking-wide mb-2">
+              Node Types
+            </h3>
+            <p className="text-[11px] text-text-muted mb-3">
+              Toggle visibility of node types in the graph
+            </p>
+          </div>
+
+          <div className="flex flex-col gap-1">
+            {FILTERABLE_LABELS.map((label) => {
+              const Icon = getNodeTypeIcon(label);
+              const isVisible = visibleLabels.includes(label);
+
+              return (
+                <button
+                  key={label}
+                  onClick={() => toggleLabelVisibility(label)}
+                  className={`
+                    flex items-center gap-2.5 px-2 py-1.5 rounded text-left transition-colors
+                    ${isVisible
+                      ? 'bg-elevated text-text-primary'
+                      : 'text-text-muted hover:bg-hover hover:text-text-secondary'
+                    }
+                  `}
+                >
+                  <div
+                    className={`w-5 h-5 rounded flex items-center justify-center ${isVisible ? '' : 'opacity-40'}`}
+                    style={{ backgroundColor: `${NODE_COLORS[label]}20` }}
+                  >
+                    <Icon className="w-3 h-3" style={{ color: NODE_COLORS[label] }} />
+                  </div>
+                  <span className="text-xs flex-1">{label}</span>
+                  <div
+                    className={`w-2 h-2 rounded-full transition-colors ${isVisible ? 'bg-accent' : 'bg-border-subtle'}`}
+                  />
+                </button>
+              );
+            })}
+          </div>
+
+          {/* Edge Type Toggles */}
+          <div className="mt-6 pt-4 border-t border-border-subtle">
+            <h3 className="text-xs font-medium text-text-secondary uppercase tracking-wide mb-2">
+              Edge Types
+            </h3>
+            <p className="text-[11px] text-text-muted mb-3">
+              Toggle visibility of relationship types
+            </p>
+
+            <div className="flex flex-col gap-1">
+              {ALL_EDGE_TYPES.map((edgeType) => {
+                const info = EDGE_INFO[edgeType];
+                const isVisible = visibleEdgeTypes.includes(edgeType);
+
+                return (
+                  <button
+                    key={edgeType}
+                    onClick={() => toggleEdgeVisibility(edgeType)}
+                    className={`
+                      flex items-center gap-2.5 px-2 py-1.5 rounded text-left transition-colors
+                      ${isVisible
+                        ? 'bg-elevated text-text-primary'
+                        : 'text-text-muted hover:bg-hover hover:text-text-secondary'
+                      }
+                    `}
+                  >
+                    <div
+                      className={`w-6 h-1.5 rounded-full ${isVisible ? '' : 'opacity-40'}`}
+                      style={{ backgroundColor: info.color }}
+                    />
+                    <span className="text-xs flex-1">{info.label}</span>
+                    <div
+                      className={`w-2 h-2 rounded-full transition-colors ${isVisible ? 'bg-accent' : 'bg-border-subtle'}`}
+                    />
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+
+          {/* Depth Filter */}
+          <div className="mt-6 pt-4 border-t border-border-subtle">
+            <h3 className="text-xs font-medium text-text-secondary uppercase tracking-wide mb-2">
+              <Target className="w-3 h-3 inline mr-1.5" />
+              Focus Depth
+            </h3>
+            <p className="text-[11px] text-text-muted mb-3">
+              Show nodes within N hops of selection
+            </p>
+
+            <div className="flex flex-wrap gap-1.5">
+              {[
+                { value: null, label: 'All' },
+                { value: 1, label: '1 hop' },
+                { value: 2, label: '2 hops' },
+                { value: 3, label: '3 hops' },
+                { value: 5, label: '5 hops' },
+              ].map(({ value, label }) => (
+                <button
+                  key={label}
+                  onClick={() => setDepthFilter(value)}
+                  className={`
+                    px-2 py-1 text-xs rounded transition-colors
+                    ${depthFilter === value
+                      ? 'bg-accent text-white'
+                      : 'bg-elevated text-text-secondary hover:bg-hover hover:text-text-primary'
+                    }
+                  `}
+                >
+                  {label}
+                </button>
+              ))}
+            </div>
+
+            {depthFilter !== null && !selectedNode && (
+              <p className="mt-2 text-[10px] text-amber-400">
+                Select a node to apply depth filter
+              </p>
+            )}
+          </div>
+
+          {/* Legend */}
+          <div className="mt-6 pt-4 border-t border-border-subtle">
+            <h3 className="text-xs font-medium text-text-secondary uppercase tracking-wide mb-3">
+              Color Legend
+            </h3>
+            <div className="grid grid-cols-2 gap-2">
+              {(['Folder', 'File', 'Class', 'Function', 'Interface', 'Method'] as NodeLabel[]).map(label => (
+                <div key={label} className="flex items-center gap-1.5">
+                  <div
+                    className="w-2.5 h-2.5 rounded-full"
+                    style={{ backgroundColor: NODE_COLORS[label] }}
+                  />
+                  <span className="text-[10px] text-text-muted">{label}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Stats footer */}
+      {graph && (
+        <div className="px-3 py-2 border-t border-border-subtle bg-elevated/50">
+          <div className="flex items-center justify-between text-[10px] text-text-muted">
+            <span>{graph.nodes.length} nodes</span>
+            <span>{graph.relationships.length} edges</span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+## components/GraphCanvas.tsx
+
+```text
+import { useEffect, useCallback, useMemo, useState, forwardRef, useImperativeHandle } from 'react';
+import { ZoomIn, ZoomOut, Maximize2, Focus, RotateCcw, Play, Pause, Lightbulb, LightbulbOff } from 'lucide-react';
+import { useSigma } from '../hooks/useSigma';
+import { useAppState } from '../hooks/useAppState';
+import { knowledgeGraphToGraphology, filterGraphByDepth, SigmaNodeAttributes, SigmaEdgeAttributes } from '../lib/graph-adapter';
+import { QueryFAB } from './QueryFAB';
+import Graph from 'graphology';
+
+export interface GraphCanvasHandle {
+  focusNode: (nodeId: string) => void;
+}
+
+export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
+  const {
+    graph,
+    setSelectedNode,
+    selectedNode: appSelectedNode,
+    visibleLabels,
+    visibleEdgeTypes,
+    openCodePanel,
+    depthFilter,
+    highlightedNodeIds,
+    aiCitationHighlightedNodeIds,
+    aiToolHighlightedNodeIds,
+    blastRadiusNodeIds,
+    isAIHighlightsEnabled,
+    toggleAIHighlights,
+    animatedNodes,
+  } = useAppState();
+  const [hoveredNodeName, setHoveredNodeName] = useState<string | null>(null);
+
+  const effectiveHighlightedNodeIds = useMemo(() => {
+    if (!isAIHighlightsEnabled) return highlightedNodeIds;
+    const next = new Set(highlightedNodeIds);
+    for (const id of aiCitationHighlightedNodeIds) next.add(id);
+    for (const id of aiToolHighlightedNodeIds) next.add(id);
+    // Note: blast radius nodes are handled separately with red color
+    return next;
+  }, [highlightedNodeIds, aiCitationHighlightedNodeIds, aiToolHighlightedNodeIds, isAIHighlightsEnabled]);
+
+  // Blast radius nodes (only when AI highlights enabled)
+  const effectiveBlastRadiusNodeIds = useMemo(() => {
+    if (!isAIHighlightsEnabled) return new Set<string>();
+    return blastRadiusNodeIds;
+  }, [blastRadiusNodeIds, isAIHighlightsEnabled]);
+
+  // Animated nodes (only when AI highlights enabled)
+  const effectiveAnimatedNodes = useMemo(() => {
+    if (!isAIHighlightsEnabled) return new Map();
+    return animatedNodes;
+  }, [animatedNodes, isAIHighlightsEnabled]);
+
+  const handleNodeClick = useCallback((nodeId: string) => {
+    if (!graph) return;
+    const node = graph.nodes.find(n => n.id === nodeId);
+    if (node) {
+      setSelectedNode(node);
+      openCodePanel();
+    }
+  }, [graph, setSelectedNode, openCodePanel]);
+
+  const handleNodeHover = useCallback((nodeId: string | null) => {
+    if (!nodeId || !graph) {
+      setHoveredNodeName(null);
+      return;
+    }
+    const node = graph.nodes.find(n => n.id === nodeId);
+    if (node) {
+      setHoveredNodeName(node.properties.name);
+    }
+  }, [graph]);
+
+  const handleStageClick = useCallback(() => {
+    setSelectedNode(null);
+  }, [setSelectedNode]);
+
+  const {
+    containerRef,
+    sigmaRef,
+    setGraph: setSigmaGraph,
+    zoomIn,
+    zoomOut,
+    resetZoom,
+    focusNode,
+    isLayoutRunning,
+    startLayout,
+    stopLayout,
+    selectedNode: sigmaSelectedNode,
+    setSelectedNode: setSigmaSelectedNode,
+  } = useSigma({
+    onNodeClick: handleNodeClick,
+    onNodeHover: handleNodeHover,
+    onStageClick: handleStageClick,
+    highlightedNodeIds: effectiveHighlightedNodeIds,
+    blastRadiusNodeIds: effectiveBlastRadiusNodeIds,
+    animatedNodes: effectiveAnimatedNodes,
+    visibleEdgeTypes,
+  });
+
+  // Expose focusNode to parent via ref
+  useImperativeHandle(ref, () => ({
+    focusNode: (nodeId: string) => {
+      // Also update app state so the selection syncs properly
+      if (graph) {
+        const node = graph.nodes.find(n => n.id === nodeId);
+        if (node) {
+          setSelectedNode(node);
+          openCodePanel();
+        }
+      }
+      focusNode(nodeId);
+    }
+  }), [focusNode, graph, setSelectedNode, openCodePanel]);
+
+  // Update Sigma graph when KnowledgeGraph changes
+  useEffect(() => {
+    if (!graph) return;
+    const sigmaGraph = knowledgeGraphToGraphology(graph);
+    setSigmaGraph(sigmaGraph);
+  }, [graph, setSigmaGraph]);
+
+  // Update node visibility when filters change
+  useEffect(() => {
+    const sigma = sigmaRef.current;
+    if (!sigma) return;
+
+    const sigmaGraph = sigma.getGraph() as Graph<SigmaNodeAttributes, SigmaEdgeAttributes>;
+    if (sigmaGraph.order === 0) return; // Don't filter empty graph
+
+    filterGraphByDepth(sigmaGraph, appSelectedNode?.id || null, depthFilter, visibleLabels);
+    sigma.refresh();
+  }, [visibleLabels, depthFilter, appSelectedNode, sigmaRef]);
+
+  // Sync app selected node with sigma
+  useEffect(() => {
+    if (appSelectedNode) {
+      setSigmaSelectedNode(appSelectedNode.id);
+    } else {
+      setSigmaSelectedNode(null);
+    }
+  }, [appSelectedNode, setSigmaSelectedNode]);
+
+  // Focus on selected node
+  const handleFocusSelected = useCallback(() => {
+    if (appSelectedNode) {
+      focusNode(appSelectedNode.id);
+    }
+  }, [appSelectedNode, focusNode]);
+
+  // Clear selection
+  const handleClearSelection = useCallback(() => {
+    setSelectedNode(null);
+    setSigmaSelectedNode(null);
+    resetZoom();
+  }, [setSelectedNode, setSigmaSelectedNode, resetZoom]);
+
+  return (
+    <div className="relative w-full h-full bg-void">
+      {/* Background gradient */}
+      <div className="absolute inset-0 pointer-events-none">
+        <div
+          className="absolute inset-0"
+          style={{
+            background: `
+              radial-gradient(circle at 50% 50%, rgba(124, 58, 237, 0.03) 0%, transparent 70%),
+              linear-gradient(to bottom, #06060a, #0a0a10)
+            `
+          }}
+        />
+      </div>
+
+      {/* Sigma container */}
+      <div
+        ref={containerRef}
+        className="sigma-container w-full h-full cursor-grab active:cursor-grabbing"
+      />
+
+      {/* Hovered node tooltip - only show when NOT selected */}
+      {hoveredNodeName && !sigmaSelectedNode && (
+        <div className="absolute top-4 left-1/2 -translate-x-1/2 px-3 py-1.5 bg-elevated/95 border border-border-subtle rounded-lg backdrop-blur-sm z-20 pointer-events-none animate-fade-in">
+          <span className="font-mono text-sm text-text-primary">{hoveredNodeName}</span>
+        </div>
+      )}
+
+      {/* Selection info bar */}
+      {sigmaSelectedNode && appSelectedNode && (
+        <div className="absolute top-4 left-1/2 -translate-x-1/2 flex items-center gap-2 px-4 py-2 bg-accent/20 border border-accent/30 rounded-xl backdrop-blur-sm z-20 animate-slide-up">
+          <div className="w-2 h-2 bg-accent rounded-full animate-pulse" />
+          <span className="font-mono text-sm text-text-primary">
+            {appSelectedNode.properties.name}
+          </span>
+          <span className="text-xs text-text-muted">
+            ({appSelectedNode.label})
+          </span>
+          <button
+            onClick={handleClearSelection}
+            className="ml-2 px-2 py-0.5 text-xs text-text-secondary hover:text-text-primary hover:bg-white/10 rounded transition-colors"
+          >
+            Clear
+          </button>
+        </div>
+      )}
+
+      {/* Graph Controls - Bottom Right */}
+      <div className="absolute bottom-4 right-4 flex flex-col gap-1 z-10">
+        <button
+          onClick={zoomIn}
+          className="w-9 h-9 flex items-center justify-center bg-elevated border border-border-subtle rounded-md text-text-secondary hover:bg-hover hover:text-text-primary transition-colors"
+          title="Zoom In"
+        >
+          <ZoomIn className="w-4 h-4" />
+        </button>
+        <button
+          onClick={zoomOut}
+          className="w-9 h-9 flex items-center justify-center bg-elevated border border-border-subtle rounded-md text-text-secondary hover:bg-hover hover:text-text-primary transition-colors"
+          title="Zoom Out"
+        >
+          <ZoomOut className="w-4 h-4" />
+        </button>
+        <button
+          onClick={resetZoom}
+          className="w-9 h-9 flex items-center justify-center bg-elevated border border-border-subtle rounded-md text-text-secondary hover:bg-hover hover:text-text-primary transition-colors"
+          title="Fit to Screen"
+        >
+          <Maximize2 className="w-4 h-4" />
+        </button>
+
+        {/* Divider */}
+        <div className="h-px bg-border-subtle my-1" />
+
+        {/* Focus on selected */}
+        {appSelectedNode && (
+          <button
+            onClick={handleFocusSelected}
+            className="w-9 h-9 flex items-center justify-center bg-accent/20 border border-accent/30 rounded-md text-accent hover:bg-accent/30 transition-colors"
+            title="Focus on Selected Node"
+          >
+            <Focus className="w-4 h-4" />
+          </button>
+        )}
+
+        {/* Clear selection */}
+        {sigmaSelectedNode && (
+          <button
+            onClick={handleClearSelection}
+            className="w-9 h-9 flex items-center justify-center bg-elevated border border-border-subtle rounded-md text-text-secondary hover:bg-hover hover:text-text-primary transition-colors"
+            title="Clear Selection"
+          >
+            <RotateCcw className="w-4 h-4" />
+          </button>
+        )}
+
+        {/* Divider */}
+        <div className="h-px bg-border-subtle my-1" />
+
+        {/* Layout control */}
+        <button
+          onClick={isLayoutRunning ? stopLayout : startLayout}
+          className={`
+            w-9 h-9 flex items-center justify-center border rounded-md transition-all
+            ${isLayoutRunning
+              ? 'bg-accent border-accent text-white shadow-glow animate-pulse'
+              : 'bg-elevated border-border-subtle text-text-secondary hover:bg-hover hover:text-text-primary'
+            }
+          `}
+          title={isLayoutRunning ? 'Stop Layout' : 'Run Layout Again'}
+        >
+          {isLayoutRunning ? (
+            <Pause className="w-4 h-4" />
+          ) : (
+            <Play className="w-4 h-4" />
+          )}
+        </button>
+      </div>
+
+      {/* Layout running indicator */}
+      {isLayoutRunning && (
+        <div className="absolute bottom-4 left-1/2 -translate-x-1/2 flex items-center gap-2 px-3 py-1.5 bg-emerald-500/20 border border-emerald-500/30 rounded-full backdrop-blur-sm z-10 animate-fade-in">
+          <div className="w-2 h-2 bg-emerald-400 rounded-full animate-ping" />
+          <span className="text-xs text-emerald-400 font-medium">Layout optimizing...</span>
+        </div>
+      )}
+
+      {/* Query FAB */}
+      <QueryFAB />
+
+      {/* AI Highlights toggle - Top Right */}
+      <div className="absolute top-4 right-4 z-20">
+        <button
+          onClick={toggleAIHighlights}
+          className={
+            isAIHighlightsEnabled
+              ? 'w-10 h-10 flex items-center justify-center bg-cyan-500/15 border border-cyan-400/40 rounded-lg text-cyan-200 hover:bg-cyan-500/20 hover:border-cyan-300/60 transition-colors'
+              : 'w-10 h-10 flex items-center justify-center bg-elevated border border-border-subtle rounded-lg text-text-muted hover:bg-hover hover:text-text-primary transition-colors'
+          }
+          title={isAIHighlightsEnabled ? 'Turn off AI highlights' : 'Turn on AI highlights'}
+        >
+          {isAIHighlightsEnabled ? <Lightbulb className="w-4 h-4" /> : <LightbulbOff className="w-4 h-4" />}
+        </button>
+      </div>
+    </div>
+  );
+});
+
+GraphCanvas.displayName = 'GraphCanvas';
+```
+
+## components/Header.tsx
+
+```text
+import { Search, Settings, HelpCircle, Sparkles, Github, Star } from 'lucide-react';
+import { useAppState } from '../hooks/useAppState';
+import { useState, useMemo, useRef, useEffect, useCallback } from 'react';
+import { GraphNode } from '../core/graph/types';
+import { EmbeddingStatus } from './EmbeddingStatus';
+import { MCPToggle } from './MCPToggle';
+import { buildCodebaseContext } from '../core/llm/context-builder';
+
+// Color mapping for node types in search results
+const NODE_TYPE_COLORS: Record<string, string> = {
+  Folder: '#6366f1',
+  File: '#3b82f6',
+  Function: '#10b981',
+  Class: '#f59e0b',
+  Method: '#14b8a6',
+  Interface: '#ec4899',
+  Variable: '#64748b',
+  Import: '#475569',
+  Type: '#a78bfa',
+};
+
+interface HeaderProps {
+  onFocusNode?: (nodeId: string) => void;
+}
+
+export const Header = ({ onFocusNode }: HeaderProps) => {
+  const {
+    projectName,
+    graph,
+    openChatPanel,
+    isRightPanelOpen,
+    rightPanelTab,
+    setSettingsPanelOpen,
+    runQuery,
+    semanticSearch,
+    setHighlightedNodeIds,
+    fileContents,
+    triggerNodeAnimation,
+  } = useAppState();
+  const [searchQuery, setSearchQuery] = useState('');
+  const [isSearchOpen, setIsSearchOpen] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const searchRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const nodeCount = graph?.nodes.length ?? 0;
+  const edgeCount = graph?.relationships.length ?? 0;
+
+  // Search results - filter nodes by name
+  const searchResults = useMemo(() => {
+    if (!graph || !searchQuery.trim()) return [];
+
+    const query = searchQuery.toLowerCase();
+    return graph.nodes
+      .filter(node => node.properties.name.toLowerCase().includes(query))
+      .slice(0, 10); // Limit to 10 results
+  }, [graph, searchQuery]);
+
+  // Handle clicking outside to close dropdown
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (searchRef.current && !searchRef.current.contains(e.target as Node)) {
+        setIsSearchOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  // Keyboard shortcut (Cmd+K / Ctrl+K)
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        inputRef.current?.focus();
+        setIsSearchOpen(true);
+      }
+      if (e.key === 'Escape') {
+        setIsSearchOpen(false);
+        inputRef.current?.blur();
+      }
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, []);
+
+  // Handle keyboard navigation in results
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (!isSearchOpen || searchResults.length === 0) return;
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setSelectedIndex(i => Math.min(i + 1, searchResults.length - 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setSelectedIndex(i => Math.max(i - 1, 0));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      const selected = searchResults[selectedIndex];
+      if (selected) {
+        handleSelectNode(selected);
+      }
+    }
+  };
+
+  const handleSelectNode = (node: GraphNode) => {
+    // onFocusNode handles both camera focus AND selection in useSigma
+    onFocusNode?.(node.id);
+    setSearchQuery('');
+    setIsSearchOpen(false);
+    setSelectedIndex(0);
+  };
+
+  return (
+    <header className="flex items-center justify-between px-5 py-3 bg-deep border-b border-dashed border-border-subtle">
+      {/* Left section */}
+      <div className="flex items-center gap-4">
+        {/* Logo */}
+        <div className="flex items-center gap-2.5">
+          <div className="w-7 h-7 flex items-center justify-center bg-gradient-to-br from-accent to-node-interface rounded-md shadow-glow text-white text-sm font-bold">
+            ◇
+          </div>
+          <span className="font-semibold text-[15px] tracking-tight">GitNexus</span>
+        </div>
+
+        {/* Project badge */}
+        {projectName && (
+          <div className="flex items-center gap-2 px-3 py-1.5 bg-surface border border-border-subtle rounded-lg text-sm text-text-secondary">
+            <span className="w-1.5 h-1.5 bg-node-function rounded-full animate-pulse" />
+            <span className="truncate max-w-[200px]">{projectName}</span>
+          </div>
+        )}
+      </div>
+
+      {/* Center - Search */}
+      <div className="flex-1 max-w-md mx-6 relative" ref={searchRef}>
+        <div className="flex items-center gap-2.5 px-3.5 py-2 bg-surface border border-border-subtle rounded-lg transition-all focus-within:border-accent focus-within:ring-2 focus-within:ring-accent/20">
+          <Search className="w-4 h-4 text-text-muted flex-shrink-0" />
+          <input
+            ref={inputRef}
+            type="text"
+            placeholder="Search nodes..."
+            value={searchQuery}
+            onChange={(e) => {
+              setSearchQuery(e.target.value);
+              setIsSearchOpen(true);
+              setSelectedIndex(0);
+            }}
+            onFocus={() => setIsSearchOpen(true)}
+            onKeyDown={handleKeyDown}
+            className="flex-1 bg-transparent border-none outline-none text-sm text-text-primary placeholder:text-text-muted"
+          />
+          <kbd className="px-1.5 py-0.5 bg-elevated border border-border-subtle rounded text-[10px] text-text-muted font-mono">
+            ⌘K
+          </kbd>
+        </div>
+
+        {/* Search Results Dropdown */}
+        {isSearchOpen && searchQuery.trim() && (
+          <div className="absolute top-full left-0 right-0 mt-1 bg-surface border border-border-subtle rounded-lg shadow-xl overflow-hidden z-50">
+            {searchResults.length === 0 ? (
+              <div className="px-4 py-3 text-sm text-text-muted">
+                No nodes found for "{searchQuery}"
+              </div>
+            ) : (
+              <div className="max-h-80 overflow-y-auto">
+                {searchResults.map((node, index) => (
+                  <button
+                    key={node.id}
+                    onClick={() => handleSelectNode(node)}
+                    className={`w-full px-4 py-2.5 flex items-center gap-3 text-left transition-colors ${index === selectedIndex
+                      ? 'bg-accent/20 text-text-primary'
+                      : 'hover:bg-hover text-text-secondary'
+                      }`}
+                  >
+                    {/* Node type indicator */}
+                    <span
+                      className="w-2.5 h-2.5 rounded-full flex-shrink-0"
+                      style={{ backgroundColor: NODE_TYPE_COLORS[node.label] || '#6b7280' }}
+                    />
+                    {/* Node name */}
+                    <span className="flex-1 truncate text-sm font-medium">
+                      {node.properties.name}
+                    </span>
+                    {/* Node type badge */}
+                    <span className="text-xs text-text-muted px-2 py-0.5 bg-elevated rounded">
+                      {node.label}
+                    </span>
+                  </button>
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Right section */}
+      <div className="flex items-center gap-2">
+        {/* GitHub Star Button */}
+        <a
+          href="https://github.com/abhigyanpatwari/GitNexus"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="flex items-center gap-2 px-3.5 py-2 bg-gradient-to-r from-purple-600 to-pink-600 hover:from-purple-500 hover:to-pink-500 rounded-lg text-white text-sm font-medium shadow-lg hover:shadow-xl hover:-translate-y-0.5 transition-all duration-200 group"
+        >
+          <Github className="w-4 h-4" />
+          <span className="hidden sm:inline">Star if cool</span>
+          <Star className="w-3.5 h-3.5 group-hover:fill-yellow-300 group-hover:text-yellow-300 transition-all" />
+          <span className="hidden sm:inline">✨</span>
+        </a>
+
+        {/* Stats */}
+        {graph && (
+          <div className="flex items-center gap-4 mr-2 text-xs text-text-muted">
+            <span>{nodeCount} nodes</span>
+            <span>{edgeCount} edges</span>
+          </div>
+        )}
+
+        {/* Embedding Status */}
+        <EmbeddingStatus />
+
+        {/* MCP Toggle for external AI agents */}
+        <MCPToggle
+          showOnboardingTip={!!graph}
+          onSearch={async (query, limit = 10) => {
+            // Use semantic search from the app
+            const results = await semanticSearch(query, limit);
+            // Trigger pulse animation on search results
+            const nodeIds = results.map((r: any) => r.id).filter(Boolean);
+            if (nodeIds.length > 0) {
+              triggerNodeAnimation(nodeIds, 'pulse');
+            }
+            return results;
+          }}
+          onCypher={async (query) => {
+            // Execute Cypher query
+            const results = await runQuery(query);
+            return results;
+          }}
+          onBlastRadius={async (nodeId, hops = 2) => {
+            // Run blast radius query
+            const query = `
+              MATCH (start)-[*1..${hops}]-(connected)
+              WHERE start.id = '${nodeId}' OR start.name = '${nodeId}'
+              RETURN DISTINCT connected.id AS id, connected.name AS name, labels(connected) AS labels
+            `;
+            const results = await runQuery(query);
+            // Trigger ripple animation on blast radius results
+            const nodeIds = results.map((r: any) => r.id).filter(Boolean);
+            if (nodeIds.length > 0) {
+              triggerNodeAnimation(nodeIds, 'ripple');
+            }
+            return results;
+          }}
+          onHighlight={(nodeIds) => {
+            // Highlight nodes in the graph
+            setHighlightedNodeIds(new Set(nodeIds));
+            // Trigger glow animation on highlighted nodes
+            if (nodeIds.length > 0) {
+              triggerNodeAnimation(nodeIds, 'glow');
+            }
+          }}
+          getContext={async () => {
+            // Build codebase context for external AI agents
+            if (!projectName) return null;
+            const context = await buildCodebaseContext(runQuery, projectName);
+            // Reshape to match MCP CodebaseContext format
+            return {
+              projectName: context.stats.projectName,
+              stats: {
+                fileCount: context.stats.fileCount,
+                functionCount: context.stats.functionCount,
+                classCount: context.stats.classCount,
+                interfaceCount: context.stats.interfaceCount,
+                methodCount: context.stats.methodCount,
+              },
+              hotspots: context.hotspots,
+              folderTree: context.folderTree,
+            };
+          }}
+          onGrep={async (pattern, caseSensitive = false, maxResults = 50) => {
+            // Grep across file contents
+            const results: Array<{ filePath: string; line: string; lineNumber: number; match: string }> = [];
+            const regex = new RegExp(pattern, caseSensitive ? 'g' : 'gi');
+
+            for (const [filePath, content] of fileContents.entries()) {
+              const lines = content.split('\n');
+              for (let i = 0; i < lines.length && results.length < maxResults; i++) {
+                const line = lines[i];
+                const match = line.match(regex);
+                if (match) {
+                  results.push({
+                    filePath,
+                    line: line.trim(),
+                    lineNumber: i + 1,
+                    match: match[0],
+                  });
+                }
+              }
+              if (results.length >= maxResults) break;
+            }
+            return results;
+          }}
+          onRead={async (filePath, startLine, endLine) => {
+            // Read file content
+            let content = fileContents.get(filePath);
+
+            // Try normalized path if not found
+            if (!content) {
+              const normalizedPath = filePath.replace(/\\/g, '/');
+              for (const [path, c] of fileContents.entries()) {
+                if (path.endsWith(normalizedPath) || normalizedPath.endsWith(path)) {
+                  content = c;
+                  break;
+                }
+              }
+            }
+
+            if (!content) {
+              return { error: `File not found: ${filePath}` };
+            }
+
+            const lines = content.split('\n');
+            const language = filePath.split('.').pop() || 'text';
+
+            // If line range specified, return only those lines
+            if (startLine !== undefined && endLine !== undefined) {
+              const slice = lines.slice(startLine - 1, endLine);
+              return {
+                filePath,
+                content: slice.join('\n'),
+                language,
+                lines: slice.length,
+              };
+            }
+
+            return {
+              filePath,
+              content,
+              language,
+              lines: lines.length,
+            };
+          }}
+        />
+
+        {/* Icon buttons */}
+        <button
+          onClick={() => setSettingsPanelOpen(true)}
+          className="w-9 h-9 flex items-center justify-center rounded-md text-text-secondary hover:bg-hover hover:text-text-primary transition-colors"
+          title="AI Settings"
+        >
+          <Settings className="w-[18px] h-[18px]" />
+        </button>
+        <button className="w-9 h-9 flex items-center justify-center rounded-md text-text-secondary hover:bg-hover hover:text-text-primary transition-colors">
+          <HelpCircle className="w-[18px] h-[18px]" />
+        </button>
+
+        {/* AI Button */}
+        <button
+          onClick={openChatPanel}
+          className={`
+            flex items-center gap-1.5 px-3.5 py-2 rounded-lg text-sm font-medium transition-all
+            ${isRightPanelOpen && rightPanelTab === 'chat'
+              ? 'bg-accent text-white shadow-glow'
+              : 'bg-gradient-to-r from-accent to-accent-dim text-white shadow-glow hover:shadow-lg hover:-translate-y-0.5'
+            }
+          `}
+        >
+          <Sparkles className="w-4 h-4" />
+          <span>Nexus AI</span>
+        </button>
+      </div>
+    </header>
+  );
+};
+```
+
+## components/IntelligentClusteringModal.tsx
+
+```text
+import { Brain, Sparkles, X, Settings, Wallet } from 'lucide-react';
+import { useSettings } from '../hooks/useSettings';
+import { useAppState } from '../hooks/useAppState';
+
+interface IntelligentClusteringModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onEnable: () => void;
+    onConfigure: () => void;
+}
+
+export const IntelligentClusteringModal = ({
+    isOpen,
+    onClose,
+    onEnable,
+    onConfigure
+}: IntelligentClusteringModalProps) => {
+    const { updateSettings } = useSettings();
+
+    if (!isOpen) return null;
+
+    const handleEnable = () => {
+        updateSettings({ intelligentClustering: true, hasSeenClusteringPrompt: true });
+        onEnable();
+        onClose();
+    };
+
+    const handleSkip = () => {
+        updateSettings({ hasSeenClusteringPrompt: true });
+        onClose();
+    };
+
+    return (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+            {/* Backdrop */}
+            <div
+                className="absolute inset-0 bg-black/60 backdrop-blur-sm"
+                onClick={handleSkip}
+            />
+
+            {/* Modal Content */}
+            <div className="relative bg-surface border border-border-subtle rounded-2xl shadow-2xl max-w-md w-full overflow-hidden animate-in fade-in zoom-in-95 duration-200">
+
+                {/* Header with cool gradient background */}
+                <div className="bg-gradient-to-br from-accent/20 to-surface p-6 pb-8 border-b border-border-subtle/50 relative overflow-hidden">
+                    <div className="absolute top-0 right-0 p-4 opacity-10">
+                        <Brain className="w-32 h-32 rotate-12" />
+                    </div>
+
+                    <button
+                        onClick={handleSkip}
+                        className="absolute top-4 right-4 p-2 text-text-muted hover:text-text-primary rounded-full hover:bg-black/10 transition-colors"
+                    >
+                        <X className="w-5 h-5" />
+                    </button>
+
+                    <div className="flex items-center gap-3 mb-2">
+                        <div className="p-3 bg-accent text-white rounded-xl shadow-lg shadow-accent/20">
+                            <Sparkles className="w-6 h-6" />
+                        </div>
+                    </div>
+
+                    <h2 className="text-xl font-bold text-text-primary mt-4">
+                        Upgrade to Intelligent Clustering?
+                    </h2>
+                    <p className="text-text-secondary mt-1 text-sm leading-relaxed">
+                        Your clusters are ready, but they could be smarter! Right now they're just named after folders.
+                    </p>
+                </div>
+
+                {/* Body */}
+                <div className="p-6 space-y-6">
+
+                    <div className="space-y-3">
+                        <h3 className="text-sm font-semibold text-text-primary flex items-center gap-2">
+                            <Brain className="w-4 h-4 text-accent" />
+                            What you get:
+                        </h3>
+                        <ul className="space-y-2 text-sm text-text-secondary">
+                            <li className="flex items-start gap-2">
+                                <span className="text-green-400 mt-1">✓</span>
+                                Semantic names (e.g., "Auth System" vs "utils")
+                            </li>
+                            <li className="flex items-start gap-2">
+                                <span className="text-green-400 mt-1">✓</span>
+                                Search keywords for better agent context
+                            </li>
+                            <li className="flex items-start gap-2">
+                                <span className="text-green-400 mt-1">✓</span>
+                                Descriptions of what the code actually does
+                            </li>
+                        </ul>
+                    </div>
+
+                    {/* Cost Note */}
+                    <div className="p-4 bg-accent/5 border border-accent/10 rounded-xl">
+                        <div className="flex items-start gap-3">
+                            <div className="p-2 bg-accent/10 rounded-lg text-accent shine">
+                                <Wallet className="w-4 h-4" />
+                            </div>
+                            <div>
+                                <h4 className="text-sm font-medium text-text-primary">Super cheap!</h4>
+                                <p className="text-xs text-text-muted mt-1 leading-relaxed">
+                                    Costs very less tokens for the whole codebase.
+                                    <br />
+                                    <span className="text-amber-400">Pro tip:</span> Smaller, cheaper models like GPT-4o-mini work great too!
+                                </p>
+                            </div>
+                        </div>
+                    </div>
+
+                </div>
+
+                {/* Actions */}
+                <div className="p-6 pt-2 bg-surface flex flex-col gap-3">
+                    <button
+                        onClick={handleEnable}
+                        className="w-full py-3 px-4 bg-accent text-white font-medium rounded-xl hover:bg-accent-dim shadow-lg shadow-accent/20 transition-all active:scale-[0.98] flex items-center justify-center gap-2"
+                    >
+                        <Sparkles className="w-4 h-4" />
+                        Enable Smart Clustering
+                    </button>
+
+                    <div className="flex bg-elevated rounded-xl p-1 gap-1">
+                        <button
+                            onClick={onConfigure}
+                            className="flex-1 py-2 px-3 text-sm font-medium text-text-secondary hover:text-text-primary hover:bg-hover rounded-lg transition-colors flex items-center justify-center gap-2"
+                        >
+                            <Settings className="w-3 h-3" />
+                            Configure Model
+                        </button>
+                        <div className="w-px bg-border-subtle my-2" />
+                        <button
+                            onClick={handleSkip}
+                            className="flex-1 py-2 px-3 text-sm font-medium text-text-muted hover:text-text-primary hover:bg-hover rounded-lg transition-colors"
+                        >
+                            No thanks (Free)
+                        </button>
+                    </div>
+                </div>
+
+            </div>
+        </div>
+    );
+};
+```
+
+## components/LoadingOverlay.tsx
+
+```text
+import { PipelineProgress } from '../types/pipeline';
+
+interface LoadingOverlayProps {
+  progress: PipelineProgress;
+}
+
+export const LoadingOverlay = ({ progress }: LoadingOverlayProps) => {
+  return (
+    <div className="fixed inset-0 flex flex-col items-center justify-center bg-void z-50">
+      {/* Background gradient effects */}
+      <div className="absolute inset-0 pointer-events-none">
+        <div className="absolute top-1/3 left-1/3 w-96 h-96 bg-accent/10 rounded-full blur-3xl animate-pulse" />
+        <div className="absolute bottom-1/3 right-1/3 w-96 h-96 bg-node-interface/10 rounded-full blur-3xl animate-pulse" />
+      </div>
+
+      {/* Pulsing orb */}
+      <div className="relative mb-10">
+        <div className="w-28 h-28 bg-gradient-to-br from-accent to-node-interface rounded-full animate-pulse-glow" />
+        <div className="absolute inset-0 w-28 h-28 bg-gradient-to-br from-accent to-node-interface rounded-full blur-xl opacity-50" />
+      </div>
+
+      {/* Progress bar */}
+      <div className="w-80 mb-4">
+        <div className="h-1.5 bg-elevated rounded-full overflow-hidden">
+          <div 
+            className="h-full bg-gradient-to-r from-accent to-node-interface rounded-full transition-all duration-300 ease-out"
+            style={{ width: `${progress.percent}%` }}
+          />
+        </div>
+      </div>
+
+      {/* Status text */}
+      <div className="text-center">
+        <p className="font-mono text-sm text-text-secondary mb-1">
+          {progress.message}
+          <span className="animate-pulse">|</span>
+        </p>
+        {progress.detail && (
+          <p className="font-mono text-xs text-text-muted truncate max-w-md">
+            {progress.detail}
+          </p>
+        )}
+      </div>
+
+      {/* Stats */}
+      {progress.stats && (
+        <div className="mt-8 flex items-center gap-6 text-xs text-text-muted">
+          <div className="flex items-center gap-2">
+            <span className="w-2 h-2 bg-node-file rounded-full" />
+            <span>{progress.stats.filesProcessed} / {progress.stats.totalFiles} files</span>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="w-2 h-2 bg-node-function rounded-full" />
+            <span>{progress.stats.nodesCreated} nodes</span>
+          </div>
+        </div>
+      )}
+
+      {/* Percent */}
+      <p className="mt-4 font-mono text-3xl font-semibold text-text-primary">
+        {progress.percent}%
+      </p>
+    </div>
+  );
+};
+```
+
+## components/MarkdownRenderer.tsx
+
+````text
+import React from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import { MermaidDiagram } from './MermaidDiagram';
+import { ToolCallCard } from './ToolCallCard';
+
+// Custom syntax theme
+const customTheme = {
+    ...vscDarkPlus,
+    'pre[class*="language-"]': {
+        ...vscDarkPlus['pre[class*="language-"]'],
+        background: '#0a0a10',
+        margin: 0,
+        padding: '16px 0',
+        fontSize: '13px',
+        lineHeight: '1.6',
+    },
+    'code[class*="language-"]': {
+        ...vscDarkPlus['code[class*="language-"]'],
+        background: 'transparent',
+        fontFamily: '"JetBrains Mono", "Fira Code", monospace',
+    },
+};
+
+interface MarkdownRendererProps {
+    content: string;
+    onLinkClick?: (href: string) => void;
+    toolCalls?: any[]; // Keep flexible for now
+}
+
+export const MarkdownRenderer: React.FC<MarkdownRendererProps> = ({
+    content,
+    onLinkClick,
+    toolCalls
+}) => {
+
+    // Helper to format text for display (convert [[links]] to markdown links)
+    const formatMarkdownForDisplay = (md: string) => {
+        // Avoid rewriting inside fenced code blocks.
+        const parts = md.split('```');
+        for (let i = 0; i < parts.length; i += 2) {
+            // Pattern 1: File grounding - [[file.ext]]
+            parts[i] = parts[i].replace(
+                /\[\[([a-zA-Z0-9_\-./\\]+\.[a-zA-Z0-9]+(?::\d+(?:[-–]\d+)?)?)\]\]/g,
+                (_m, inner: string) => {
+                    const trimmed = inner.trim();
+                    const href = `code-ref:${encodeURIComponent(trimmed)}`;
+                    return `[${trimmed}](${href})`;
+                }
+            );
+
+            // Pattern 2: Node grounding - [[Type:Name]]
+            parts[i] = parts[i].replace(
+                /\[\[(?:graph:)?(Class|Function|Method|Interface|File|Folder|Variable|Enum|Type|CodeElement):([^\]]+)\]\]/g,
+                (_m, nodeType: string, nodeName: string) => {
+                    const trimmed = `${nodeType}:${nodeName.trim()}`;
+                    const href = `node-ref:${encodeURIComponent(trimmed)}`;
+                    return `[${trimmed}](${href})`;
+                }
+            );
+        }
+        return parts.join('```');
+    };
+
+    const handleLinkClick = (e: React.MouseEvent<HTMLAnchorElement>, href: string) => {
+        if (href.startsWith('code-ref:') || href.startsWith('node-ref:')) {
+            e.preventDefault();
+            onLinkClick?.(href);
+        }
+        // External links open in new tab (default behavior)
+    };
+
+    const formattedContent = React.useMemo(() => formatMarkdownForDisplay(content), [content]);
+
+    const markdownComponents = React.useMemo(() => ({
+        a: ({ href, children, ...props }: any) => {
+            const hrefStr = href || '';
+
+            // Grounding links (Code refs & Node refs)
+            if (hrefStr.startsWith('code-ref:') || hrefStr.startsWith('node-ref:')) {
+                const isNodeRef = hrefStr.startsWith('node-ref:');
+                const inner = decodeURIComponent(hrefStr.slice(isNodeRef ? 9 : 9)); // length is same? wait.. code-ref: (9), node-ref: (9). Yes.
+
+                // Styles
+                const baseParams = "code-ref-btn inline-flex items-center px-2 py-0.5 rounded-md font-mono text-[12px] !no-underline hover:!no-underline transition-colors";
+                const colorParams = isNodeRef
+                    ? "border border-amber-300/55 bg-amber-400/10 !text-amber-200 visited:!text-amber-200 hover:bg-amber-400/15 hover:border-amber-200/70"
+                    : "border border-cyan-300/55 bg-cyan-400/10 !text-cyan-200 visited:!text-cyan-200 hover:bg-cyan-400/15 hover:border-cyan-200/70";
+
+                return (
+                    <a
+                        href={hrefStr}
+                        onClick={(e) => handleLinkClick(e, hrefStr)}
+                        className={`${baseParams} ${colorParams}`}
+                        title={isNodeRef ? `View ${inner} in Code panel` : `Open in Code panel • ${inner}`}
+                        {...props}
+                    >
+                        <span className="text-inherit">{children}</span>
+                    </a>
+                );
+            }
+
+            // External links
+            return (
+                <a
+                    href={hrefStr}
+                    className="text-accent underline underline-offset-2 hover:text-purple-300"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    {...props}
+                >
+                    {children}
+                </a>
+            );
+        },
+        code: ({ className, children, ...props }: any) => {
+            const match = /language-(\w+)/.exec(className || '');
+            const isInline = !className && !match;
+            const codeContent = String(children).replace(/\n$/, '');
+
+            if (isInline) {
+                return <code {...props}>{children}</code>;
+            }
+
+            const language = match ? match[1] : 'text';
+
+            // Render Mermaid diagrams
+            if (language === 'mermaid') {
+                return <MermaidDiagram code={codeContent} />;
+            }
+
+            return (
+                <SyntaxHighlighter
+                    style={customTheme}
+                    language={language}
+                    PreTag="div"
+                    customStyle={{
+                        margin: 0,
+                        padding: '14px 16px',
+                        borderRadius: '8px',
+                        fontSize: '13px',
+                        background: '#0a0a10',
+                        border: '1px solid #1e1e2a',
+                    }}
+                >
+                    {codeContent}
+                </SyntaxHighlighter>
+            );
+        },
+        pre: ({ children }: any) => <>{children}</>,
+    }), [onLinkClick]); // Removed handleLinkClick dependency as it is defined inside component but depends on onLinkClick
+
+    return (
+        <div className="text-text-primary text-sm">
+            <ReactMarkdown
+                remarkPlugins={[remarkGfm]}
+                urlTransform={(url) => {
+                    if (url.startsWith('code-ref:') || url.startsWith('node-ref:')) return url;
+                    // Default behavior for http/https/etc
+                    return url;
+                }}
+                components={markdownComponents}
+            >
+                {formattedContent}
+            </ReactMarkdown>
+
+            {/* Tool Call Cards appended at the bottom if provided */}
+            {toolCalls && toolCalls.length > 0 && (
+                <div className="mt-3 space-y-2">
+                    {toolCalls.map(tc => (
+                        <ToolCallCard key={tc.id} toolCall={tc} defaultExpanded={false} />
+                    ))}
+                </div>
+            )}
+        </div>
+    );
+};
+````
+
+## components/MCPToggle.tsx
+
+```text
+/**
+ * MCP Toggle Component
+ * 
+ * Toggle for enabling MCP exposure to external AI agents (Cursor, Claude, etc.)
+ * Shows MCP config for setup and connection status.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { Copy, Check, X, Sparkles, Zap, ExternalLink } from 'lucide-react';
+import { getMCPClient, type CodebaseContext } from '../core/mcp/mcp-client';
+
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+interface MCPToggleProps {
+    onSearch?: (query: string, limit?: number) => Promise<any>;
+    onCypher?: (query: string) => Promise<any>;
+    onBlastRadius?: (nodeId: string, hops?: number) => Promise<any>;
+    onHighlight?: (nodeIds: string[], color?: string) => void;
+    onGrep?: (pattern: string, caseSensitive?: boolean, maxResults?: number) => Promise<any>;
+    onRead?: (filePath: string, startLine?: number, endLine?: number) => Promise<any>;
+    showOnboardingTip?: boolean;
+    getContext?: () => Promise<CodebaseContext | null>;
+}
+
+const MCP_TIP_DISMISSED_KEY = 'gitnexus-mcp-tip-dismissed';
+
+// MCP config that users copy to their AI agent
+const MCP_CONFIG = `{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus-mcp"]
+    }
+  }
+}`;
+
+export function MCPToggle({
+    onSearch,
+    onCypher,
+    onBlastRadius,
+    onHighlight,
+    onGrep,
+    onRead,
+    showOnboardingTip = false,
+    getContext,
+}: MCPToggleProps = {}) {
+    const [status, setStatus] = useState<ConnectionState>('disconnected');
+    const [copied, setCopied] = useState(false);
+    const [showPopup, setShowPopup] = useState(false);
+    const popupRef = useRef<HTMLDivElement | null>(null);
+    const [showTip, setShowTip] = useState(false);
+
+    const isConnected = status === 'connected';
+    const isConnecting = status === 'connecting';
+
+    // Show tip when graph becomes ready
+    useEffect(() => {
+        if (showOnboardingTip) {
+            const dismissed = localStorage.getItem(MCP_TIP_DISMISSED_KEY);
+            if (!dismissed) {
+                const timer = setTimeout(() => setShowTip(true), 1500);
+                return () => clearTimeout(timer);
+            }
+        }
+    }, [showOnboardingTip]);
+
+    // Close popup when clicking outside
+    useEffect(() => {
+        if (!showPopup) return;
+        const handleClickOutside = (event: MouseEvent) => {
+            if (popupRef.current && !popupRef.current.contains(event.target as Node)) {
+                setShowPopup(false);
+            }
+        };
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => document.removeEventListener('mousedown', handleClickOutside);
+    }, [showPopup]);
+
+    const dismissTip = () => {
+        setShowTip(false);
+        localStorage.setItem(MCP_TIP_DISMISSED_KEY, 'true');
+    };
+
+    const connect = useCallback(async () => {
+        const client = getMCPClient();
+        setStatus('connecting');
+        setShowTip(false);
+
+        try {
+            await client.connect();
+
+            // Register tool handlers
+            if (onSearch) client.registerHandler('search', async (params) => onSearch(params.query, params.limit));
+            if (onCypher) client.registerHandler('cypher', async (params) => onCypher(params.query));
+            if (onBlastRadius) client.registerHandler('blastRadius', async (params) => onBlastRadius(params.nodeId, params.hops));
+            if (onHighlight) client.registerHandler('highlight', async (params) => { onHighlight(params.nodeIds, params.color); return { highlighted: params.nodeIds.length }; });
+            if (onGrep) client.registerHandler('grep', async (params) => onGrep(params.pattern, params.caseSensitive, params.maxResults));
+            if (onRead) client.registerHandler('read', async (params) => onRead(params.filePath, params.startLine, params.endLine));
+            if (getContext) client.registerHandler('context', async () => getContext());
+
+            setStatus('connected');
+            setShowPopup(false);
+            localStorage.setItem(MCP_TIP_DISMISSED_KEY, 'true');
+
+            // Send context after connecting
+            if (getContext) {
+                try {
+                    const context = await getContext();
+                    if (context) client.sendContext(context);
+                } catch (e) {
+                    console.error('[MCP] Failed to send context:', e);
+                }
+            }
+        } catch {
+            setStatus('error');
+        }
+    }, [onSearch, onCypher, onBlastRadius, onHighlight, onGrep, onRead, getContext]);
+
+    const disconnect = useCallback(() => {
+        const client = getMCPClient();
+        client.disconnect();
+        setStatus('disconnected');
+    }, []);
+
+    const toggle = useCallback(() => {
+        if (isConnected) {
+            disconnect();
+        } else if (!isConnecting) {
+            connect();
+        }
+    }, [isConnected, isConnecting, connect, disconnect]);
+
+    const copyConfig = () => {
+        navigator.clipboard.writeText(MCP_CONFIG);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+    };
+
+    // Listen for connection changes
+    useEffect(() => {
+        const client = getMCPClient();
+        const unsubscribe = client.onConnectionChange((connected) => {
+            setStatus(connected ? 'connected' : 'disconnected');
+            if (connected) setShowPopup(false);
+        });
+        return () => { unsubscribe(); };
+    }, []);
+
+    return (
+        <div className="relative flex items-center gap-2">
+            {/* MCP Button */}
+            <button
+                onClick={() => setShowPopup(!showPopup)}
+                className={`
+          flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg text-xs font-medium
+          transition-all duration-200
+          ${isConnected
+                        ? 'bg-green-500/15 text-green-400 border border-green-500/30 hover:bg-green-500/25'
+                        : 'bg-surface hover:bg-hover text-text-secondary hover:text-text-primary border border-border-subtle'
+                    }
+        `}
+            >
+                <Zap className={`w-3.5 h-3.5 ${isConnected ? 'text-green-400' : ''}`} />
+                <span>MCP</span>
+                {isConnected && <span className="w-1.5 h-1.5 rounded-full bg-green-400 animate-pulse" />}
+            </button>
+
+            {/* Popup */}
+            {showPopup && (
+                <div
+                    ref={popupRef}
+                    className="absolute top-full right-0 mt-2 w-[380px] bg-surface/95 backdrop-blur-xl border border-border-subtle rounded-xl shadow-2xl z-50 overflow-hidden"
+                >
+                    {/* Header */}
+                    <div className="px-4 py-3 bg-gradient-to-r from-accent/10 to-transparent border-b border-border-subtle">
+                        <div className="flex items-center justify-between">
+                            <div className="flex items-center gap-2">
+                                <div className="p-1.5 bg-accent/20 rounded-lg">
+                                    <Sparkles className="w-4 h-4 text-accent" />
+                                </div>
+                                <div>
+                                    <h3 className="text-sm font-semibold text-text-primary">Connect AI Agents</h3>
+                                    <p className="text-[10px] text-text-muted">Cursor, Claude Code, Antigravity</p>
+                                </div>
+                            </div>
+                            <button
+                                onClick={() => setShowPopup(false)}
+                                className="p-1 text-text-muted hover:text-text-primary rounded transition-colors"
+                            >
+                                <X className="w-4 h-4" />
+                            </button>
+                        </div>
+                    </div>
+
+                    {/* Content */}
+                    <div className="p-4 space-y-4">
+                        {/* Step 1: Config */}
+                        <div>
+                            <div className="flex items-center gap-2 mb-2">
+                                <span className="flex items-center justify-center w-5 h-5 rounded-full bg-accent/20 text-accent text-[10px] font-bold">1</span>
+                                <span className="text-xs text-text-secondary">Add to your AI agent's MCP config</span>
+                            </div>
+                            <div className="relative group">
+                                <pre className="p-3 bg-deep rounded-lg text-[11px] font-mono text-text-primary overflow-x-auto border border-border-subtle">
+                                    {MCP_CONFIG}
+                                </pre>
+                                <button
+                                    onClick={copyConfig}
+                                    className="absolute top-2 right-2 p-1.5 bg-surface/80 hover:bg-hover rounded-md transition-colors opacity-0 group-hover:opacity-100"
+                                    title="Copy config"
+                                >
+                                    {copied ? (
+                                        <Check className="w-3.5 h-3.5 text-green-400" />
+                                    ) : (
+                                        <Copy className="w-3.5 h-3.5 text-text-muted" />
+                                    )}
+                                </button>
+                            </div>
+                        </div>
+
+                        {/* Step 2: Connect */}
+                        <div>
+                            <div className="flex items-center gap-2 mb-2">
+                                <span className="flex items-center justify-center w-5 h-5 rounded-full bg-accent/20 text-accent text-[10px] font-bold">2</span>
+                                <span className="text-xs text-text-secondary">Connect browser to daemon</span>
+                            </div>
+                            <button
+                                onClick={toggle}
+                                disabled={isConnecting}
+                                className={`
+                  w-full py-2.5 rounded-lg text-sm font-medium transition-all duration-200
+                  ${isConnected
+                                        ? 'bg-green-500/15 text-green-400 border border-green-500/30 hover:bg-green-500/25'
+                                        : isConnecting
+                                            ? 'bg-surface text-text-muted cursor-wait'
+                                            : 'bg-accent text-white hover:bg-accent-dim'
+                                    }
+                `}
+                            >
+                                {isConnected ? '✓ Connected' : isConnecting ? 'Connecting...' : 'Connect'}
+                            </button>
+                        </div>
+
+                        {/* Status message */}
+                        {status === 'error' && (
+                            <p className="text-[11px] text-amber-400 text-center">
+                                Daemon not running. Make sure your AI agent has started gitnexus-mcp.
+                            </p>
+                        )}
+
+                        {/* Help link */}
+                        <a
+                            href="https://github.com/abhigyanpatwari/GitNexus#mcp-integration"
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="flex items-center justify-center gap-1.5 text-[11px] text-text-muted hover:text-accent transition-colors"
+                        >
+                            <span>Learn more</span>
+                            <ExternalLink className="w-3 h-3" />
+                        </a>
+                    </div>
+                </div>
+            )}
+
+            {/* Onboarding Tip */}
+            {showTip && !isConnected && !showPopup && (
+                <div className="absolute top-full right-0 mt-3 w-72 p-4 bg-surface/95 backdrop-blur-xl border border-accent/30 rounded-xl shadow-2xl z-50 animate-in fade-in slide-in-from-top-2">
+                    <button
+                        onClick={dismissTip}
+                        className="absolute top-2 right-2 p-1 text-text-muted hover:text-text-primary rounded transition-colors"
+                    >
+                        <X className="w-3.5 h-3.5" />
+                    </button>
+                    <div className="flex items-start gap-3">
+                        <div className="p-2 bg-accent/20 rounded-lg flex-shrink-0">
+                            <Sparkles className="w-4 h-4 text-accent" />
+                        </div>
+                        <div>
+                            <h4 className="text-sm font-semibold text-text-primary mb-1">
+                                Connect your AI tools
+                            </h4>
+                            <p className="text-xs text-text-secondary leading-relaxed mb-3">
+                                Let Cursor or Claude access GitNexus code intelligence.
+                            </p>
+                            <button
+                                onClick={() => { dismissTip(); setShowPopup(true); }}
+                                className="px-3 py-1.5 text-xs font-medium bg-accent text-white rounded-lg hover:bg-accent-dim transition-colors"
+                            >
+                                Set up MCP
+                            </button>
+                        </div>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}
+```
+
+## components/MermaidDiagram.tsx
+
+```text
+import { useEffect, useRef, useState } from 'react';
+import mermaid from 'mermaid';
+import { AlertTriangle, Maximize2, Minimize2 } from 'lucide-react';
+
+// Initialize mermaid with dark theme
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'dark',
+  themeVariables: {
+    primaryColor: '#06b6d4',
+    primaryTextColor: '#e4e4ed',
+    primaryBorderColor: '#1e1e2a',
+    lineColor: '#3b3b54',
+    secondaryColor: '#1e1e2a',
+    tertiaryColor: '#0a0a10',
+    background: '#0a0a10',
+    mainBkg: '#0f0f18',
+    nodeBorder: '#3b3b54',
+    clusterBkg: '#1e1e2a',
+    titleColor: '#e4e4ed',
+    edgeLabelBackground: '#0f0f18',
+    nodeTextColor: '#e4e4ed',
+  },
+  flowchart: {
+    curve: 'basis',
+    padding: 15,
+    nodeSpacing: 50,
+    rankSpacing: 50,
+  },
+  sequence: {
+    actorMargin: 50,
+    boxMargin: 10,
+    boxTextMargin: 5,
+    noteMargin: 10,
+    messageMargin: 35,
+  },
+  fontFamily: '"JetBrains Mono", "Fira Code", monospace',
+  fontSize: 13,
+  suppressErrorRendering: true, // Prevent default error div appending
+});
+
+// Override the default error handler to prevent it from logging to UI
+mermaid.parseError = (_err) => {
+  // Silent catch
+};
+
+interface MermaidDiagramProps {
+  code: string;
+}
+
+export const MermaidDiagram = ({ code }: MermaidDiagramProps) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [svg, setSvg] = useState<string>('');
+
+  useEffect(() => {
+    const renderDiagram = async () => {
+      if (!containerRef.current) return;
+
+      try {
+        // Generate unique ID for this diagram
+        const id = `mermaid-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+        // Render the diagram
+        const { svg: renderedSvg } = await mermaid.render(id, code.trim());
+        setSvg(renderedSvg);
+        setError(null);
+      } catch (err) {
+        // Silent catch for streaming: 
+        // If render fails (common during partial streaming), we:
+        // 1. Log to console for debugging
+        // 2. Do NOT set error state (avoids flashing red box)
+        // 3. Do NOT clear existing SVG (keeps last valid state visible)
+        console.debug('Mermaid render skipped (incomplete):', err);
+      }
+    };
+
+    // Debounce rendering to prevent "jerking" during high-speed streaming
+    const timeoutId = setTimeout(() => {
+      renderDiagram();
+    }, 300);
+
+    return () => clearTimeout(timeoutId);
+  }, [code]);
+
+  if (error) {
+    return (
+      <div className="my-3 p-4 bg-rose-500/10 border border-rose-500/30 rounded-lg">
+        <div className="flex items-center gap-2 text-rose-300 text-sm mb-2">
+          <AlertTriangle className="w-4 h-4" />
+          <span className="font-medium">Diagram Error</span>
+        </div>
+        <pre className="text-xs text-rose-200/70 font-mono whitespace-pre-wrap">{error}</pre>
+        <details className="mt-2">
+          <summary className="text-xs text-text-muted cursor-pointer hover:text-text-secondary">
+            Show source
+          </summary>
+          <pre className="mt-2 p-2 bg-surface rounded text-xs text-text-muted overflow-x-auto">
+            {code}
+          </pre>
+        </details>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`my-3 relative group ${isExpanded ? 'fixed inset-4 z-50' : ''}`}>
+      {/* Backdrop for expanded view */}
+      {isExpanded && (
+        <div
+          className="absolute inset-0 -m-4 bg-deep/95 backdrop-blur-sm"
+          onClick={() => setIsExpanded(false)}
+        />
+      )}
+
+      <div className={`
+        relative bg-gradient-to-b from-surface to-elevated 
+        border border-border-subtle rounded-xl overflow-hidden
+        ${isExpanded ? 'h-full' : ''}
+      `}>
+        {/* Header */}
+        <div className="flex items-center justify-between px-3 py-2 bg-surface/60 border-b border-border-subtle">
+          <span className="text-[10px] text-text-muted uppercase tracking-wider font-medium">
+            Diagram
+          </span>
+          <button
+            onClick={() => setIsExpanded(!isExpanded)}
+            className="p-1 text-text-muted hover:text-text-primary hover:bg-hover rounded transition-colors"
+            title={isExpanded ? 'Minimize' : 'Expand'}
+          >
+            {isExpanded ? (
+              <Minimize2 className="w-3.5 h-3.5" />
+            ) : (
+              <Maximize2 className="w-3.5 h-3.5" />
+            )}
+          </button>
+        </div>
+
+        {/* Diagram container */}
+        <div
+          ref={containerRef}
+          className={`
+            flex items-center justify-center p-4 overflow-auto
+            ${isExpanded ? 'h-[calc(100%-40px)]' : 'max-h-[400px]'}
+          `}
+          dangerouslySetInnerHTML={{ __html: svg }}
+        />
+      </div>
+    </div>
+  );
+};
+```
+
+## components/QueryFAB.tsx
+
+```text
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { Terminal, Play, X, ChevronDown, ChevronUp, Loader2, Sparkles, Table } from 'lucide-react';
+import { useAppState } from '../hooks/useAppState';
+
+const EXAMPLE_QUERIES = [
+  {
+    label: 'All Functions',
+    query: `MATCH (n:Function) RETURN n.id AS id, n.name AS name, n.filePath AS path LIMIT 50`,
+  },
+  {
+    label: 'All Classes',
+    query: `MATCH (n:Class) RETURN n.id AS id, n.name AS name, n.filePath AS path LIMIT 50`,
+  },
+  {
+    label: 'All Interfaces',
+    query: `MATCH (n:Interface) RETURN n.id AS id, n.name AS name, n.filePath AS path LIMIT 50`,
+  },
+  {
+    label: 'Function Calls',
+    query: `MATCH (a:File)-[r:CodeRelation {type: 'CALLS'}]->(b:Function) RETURN a.id AS id, a.name AS caller, b.name AS callee LIMIT 50`,
+  },
+  {
+    label: 'Import Dependencies',
+    query: `MATCH (a:File)-[r:CodeRelation {type: 'IMPORTS'}]->(b:File) RETURN a.id AS id, a.name AS from, b.name AS imports LIMIT 50`,
+  },
+];
+
+export const QueryFAB = () => {
+  const { setHighlightedNodeIds, setQueryResult, queryResult, clearQueryHighlights, graph, runQuery, isDatabaseReady } = useAppState();
+
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [query, setQuery] = useState('');
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [showExamples, setShowExamples] = useState(false);
+  const [showResults, setShowResults] = useState(true);
+
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isExpanded && textareaRef.current) {
+      textareaRef.current.focus();
+    }
+  }, [isExpanded]);
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (panelRef.current && !panelRef.current.contains(e.target as Node)) {
+        setShowExamples(false);
+      }
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && isExpanded) {
+        setIsExpanded(false);
+        setShowExamples(false);
+      }
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isExpanded]);
+
+  const handleRunQuery = useCallback(async () => {
+    if (!query.trim() || isRunning) return;
+
+    if (!graph) {
+      setError('No project loaded. Load a project first.');
+      return;
+    }
+
+    const ready = await isDatabaseReady();
+    if (!ready) {
+      setError('Database not ready. Please wait for loading to complete.');
+      return;
+    }
+
+    setIsRunning(true);
+    setError(null);
+
+    const startTime = performance.now();
+
+    try {
+      const rows = await runQuery(query);
+      const executionTime = performance.now() - startTime;
+
+      // Extract node IDs from results - handles various formats
+      // 1. Array format: first element if it looks like a node ID
+      // 2. Object format: any field ending with 'id' (case-insensitive)
+      // 3. Values matching node ID pattern: Label:path:name
+      const nodeIdPattern = /^(File|Function|Class|Method|Interface|Folder|CodeElement):/;
+
+      const nodeIds = rows
+        .flatMap(row => {
+          const ids: string[] = [];
+
+          if (Array.isArray(row)) {
+            // Array format - check all elements for node ID patterns
+            row.forEach(val => {
+              if (typeof val === 'string' && (nodeIdPattern.test(val) || val.includes(':'))) {
+                ids.push(val);
+              }
+            });
+          } else if (typeof row === 'object' && row !== null) {
+            // Object format - check fields ending with 'id' and values matching patterns
+            Object.entries(row).forEach(([key, val]) => {
+              const keyLower = key.toLowerCase();
+              if (typeof val === 'string') {
+                // Field name contains 'id'
+                if (keyLower.includes('id') || keyLower === 'id') {
+                  ids.push(val);
+                }
+                // Value matches node ID pattern
+                else if (nodeIdPattern.test(val)) {
+                  ids.push(val);
+                }
+              }
+            });
+          }
+
+          return ids;
+        })
+        .filter(Boolean)
+        .filter((id, index, arr) => arr.indexOf(id) === index);
+
+      setQueryResult({ rows, nodeIds, executionTime });
+      setHighlightedNodeIds(new Set(nodeIds));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Query execution failed');
+      setQueryResult(null);
+      setHighlightedNodeIds(new Set());
+    } finally {
+      setIsRunning(false);
+    }
+  }, [query, isRunning, graph, isDatabaseReady, runQuery, setHighlightedNodeIds, setQueryResult]);
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
+      e.preventDefault();
+      handleRunQuery();
+    }
+  };
+
+  const handleSelectExample = (exampleQuery: string) => {
+    setQuery(exampleQuery);
+    setShowExamples(false);
+    textareaRef.current?.focus();
+  };
+
+  const handleClose = () => {
+    setIsExpanded(false);
+    setShowExamples(false);
+    clearQueryHighlights();
+    setError(null);
+  };
+
+  const handleClear = () => {
+    setQuery('');
+    clearQueryHighlights();
+    setError(null);
+    textareaRef.current?.focus();
+  };
+
+  if (!isExpanded) {
+    return (
+      <button
+        onClick={() => setIsExpanded(true)}
+        className="
+          group absolute bottom-4 left-4 z-20
+          flex items-center gap-2 px-4 py-2.5
+          bg-gradient-to-r from-cyan-500 to-teal-500
+          rounded-xl text-white font-medium text-sm
+          shadow-[0_0_20px_rgba(6,182,212,0.4)]
+          hover:shadow-[0_0_30px_rgba(6,182,212,0.6)]
+          hover:-translate-y-0.5
+          transition-all duration-200
+        "
+      >
+        <Terminal className="w-4 h-4" />
+        <span>Query</span>
+        {queryResult && queryResult.nodeIds.length > 0 && (
+          <span className="
+            px-1.5 py-0.5 ml-1
+            bg-white/20 rounded-md
+            text-xs font-semibold
+          ">
+            {queryResult.nodeIds.length}
+          </span>
+        )}
+      </button>
+    );
+  }
+
+  return (
+    <div
+      ref={panelRef}
+      className="
+        absolute bottom-4 left-4 z-20
+        w-[480px] max-w-[calc(100%-2rem)]
+        bg-deep/95 backdrop-blur-md
+        border border-cyan-500/30
+        rounded-xl
+        shadow-[0_0_40px_rgba(6,182,212,0.2)]
+        animate-fade-in
+      "
+    >
+      <div className="flex items-center justify-between px-4 py-3 border-b border-border-subtle">
+        <div className="flex items-center gap-2">
+          <div className="w-7 h-7 flex items-center justify-center bg-gradient-to-br from-cyan-500 to-teal-500 rounded-lg">
+            <Terminal className="w-4 h-4 text-white" />
+          </div>
+          <span className="font-medium text-sm">Cypher Query</span>
+        </div>
+        <button
+          onClick={handleClose}
+          className="p-1.5 text-text-muted hover:text-text-primary hover:bg-hover rounded-md transition-colors"
+        >
+          <X className="w-4 h-4" />
+        </button>
+      </div>
+
+      <div className="p-3">
+        <div className="relative">
+          <textarea
+            ref={textareaRef}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder="MATCH (n:Function) RETURN n.name, n.filePath LIMIT 10"
+            rows={3}
+            className="
+              w-full px-3 py-2.5
+              bg-surface border border-border-subtle rounded-lg
+              text-sm font-mono text-text-primary
+              placeholder:text-text-muted
+              focus:border-cyan-500/50 focus:ring-2 focus:ring-cyan-500/20
+              outline-none resize-none
+              transition-all
+            "
+          />
+        </div>
+
+        <div className="flex items-center justify-between mt-3">
+          <div className="relative">
+            <button
+              onClick={() => setShowExamples(!showExamples)}
+              className="
+                flex items-center gap-1.5 px-3 py-1.5
+                text-xs text-text-secondary
+                hover:text-text-primary hover:bg-hover
+                rounded-md transition-colors
+              "
+            >
+              <Sparkles className="w-3.5 h-3.5" />
+              <span>Examples</span>
+              <ChevronDown className={`w-3.5 h-3.5 transition-transform ${showExamples ? 'rotate-180' : ''}`} />
+            </button>
+
+            {showExamples && (
+              <div className="
+                absolute bottom-full left-0 mb-2
+                w-64 py-1
+                bg-surface border border-border-subtle rounded-lg
+                shadow-xl
+                animate-fade-in
+              ">
+                {EXAMPLE_QUERIES.map((example) => (
+                  <button
+                    key={example.label}
+                    onClick={() => handleSelectExample(example.query)}
+                    className="
+                      w-full px-3 py-2 text-left
+                      text-sm text-text-secondary
+                      hover:bg-hover hover:text-text-primary
+                      transition-colors
+                    "
+                  >
+                    {example.label}
+                  </button>
+                ))}
+              </div>
+            )}
+          </div>
+
+          <div className="flex items-center gap-2">
+            {query && (
+              <button
+                onClick={handleClear}
+                className="
+                  px-3 py-1.5
+                  text-xs text-text-secondary
+                  hover:text-text-primary hover:bg-hover
+                  rounded-md transition-colors
+                "
+              >
+                Clear
+              </button>
+            )}
+            <button
+              onClick={handleRunQuery}
+              disabled={!query.trim() || isRunning}
+              className="
+                flex items-center gap-1.5 px-4 py-1.5
+                bg-gradient-to-r from-cyan-500 to-teal-500
+                rounded-md text-white text-sm font-medium
+                shadow-[0_0_15px_rgba(6,182,212,0.3)]
+                hover:shadow-[0_0_20px_rgba(6,182,212,0.5)]
+                disabled:opacity-50 disabled:cursor-not-allowed disabled:shadow-none
+                transition-all
+              "
+            >
+              {isRunning ? (
+                <Loader2 className="w-3.5 h-3.5 animate-spin" />
+              ) : (
+                <Play className="w-3.5 h-3.5" />
+              )}
+              <span>Run</span>
+              <kbd className="ml-1 px-1 py-0.5 bg-white/20 rounded text-[10px]">⌘↵</kbd>
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {error && (
+        <div className="px-4 py-2 bg-red-500/10 border-t border-red-500/20">
+          <p className="text-xs text-red-400 font-mono">{error}</p>
+        </div>
+      )}
+
+      {queryResult && !error && (
+        <div className="border-t border-cyan-500/20">
+          <div className="px-4 py-2.5 bg-cyan-500/5 flex items-center justify-between">
+            <div className="flex items-center gap-3 text-xs">
+              <span className="text-text-secondary">
+                <span className="text-cyan-400 font-semibold">{queryResult.rows.length}</span> rows
+              </span>
+              {queryResult.nodeIds.length > 0 && (
+                <span className="text-text-secondary">
+                  <span className="text-cyan-400 font-semibold">{queryResult.nodeIds.length}</span> highlighted
+                </span>
+              )}
+              <span className="text-text-muted">
+                {queryResult.executionTime.toFixed(1)}ms
+              </span>
+            </div>
+            <div className="flex items-center gap-2">
+              {queryResult.nodeIds.length > 0 && (
+                <button
+                  onClick={clearQueryHighlights}
+                  className="text-xs text-text-muted hover:text-text-primary transition-colors"
+                >
+                  Clear
+                </button>
+              )}
+              <button
+                onClick={() => setShowResults(!showResults)}
+                className="flex items-center gap-1 text-xs text-text-muted hover:text-text-primary transition-colors"
+              >
+                <Table className="w-3 h-3" />
+                {showResults ? <ChevronDown className="w-3 h-3" /> : <ChevronUp className="w-3 h-3" />}
+              </button>
+            </div>
+          </div>
+
+          {showResults && queryResult.rows.length > 0 && (
+            <div className="max-h-48 overflow-auto scrollbar-thin border-t border-border-subtle">
+              <table className="w-full text-xs">
+                <thead className="bg-surface sticky top-0">
+                  <tr>
+                    {Object.keys(queryResult.rows[0]).map((key) => (
+                      <th key={key} className="px-3 py-2 text-left text-text-muted font-medium border-b border-border-subtle">
+                        {key}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {queryResult.rows.slice(0, 50).map((row, i) => (
+                    <tr key={i} className="hover:bg-hover/50 transition-colors">
+                      {Object.values(row).map((val, j) => (
+                        <td key={j} className="px-3 py-1.5 text-text-secondary border-b border-border-subtle/50 font-mono truncate max-w-[200px]">
+                          {typeof val === 'object' ? JSON.stringify(val) : String(val ?? '')}
+                        </td>
+                      ))}
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+              {queryResult.rows.length > 50 && (
+                <div className="px-3 py-2 text-xs text-text-muted bg-surface border-t border-border-subtle">
+                  Showing 50 of {queryResult.rows.length} rows
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+## components/RightPanel.tsx
+
+```text
+import { useState, useRef, useEffect, useCallback } from 'react';
+import {
+  Send, Sparkles, User,
+  PanelRightClose, Loader2, AlertTriangle, Activity
+} from 'lucide-react';
+import { useAppState } from '../hooks/useAppState';
+import { ToolCallCard } from './ToolCallCard';
+import { isProviderConfigured } from '../core/llm/settings-service';
+import { ActivityFeed } from './ActivityFeed';
+import { MarkdownRenderer } from './MarkdownRenderer';
+export const RightPanel = () => {
+  const {
+    isRightPanelOpen,
+    setRightPanelOpen,
+    fileContents,
+    graph,
+    addCodeReference,
+    // LLM / chat state
+    chatMessages,
+    isChatLoading,
+    currentToolCalls,
+    agentError,
+    isAgentReady,
+    isAgentInitializing,
+    sendChatMessage,
+    clearChat,
+  } = useAppState();
+
+  const [chatInput, setChatInput] = useState('');
+  const [activeTab, setActiveTab] = useState<'chat' | 'activity'>('chat');
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+
+  // Auto-scroll to bottom when messages update or while streaming
+  useEffect(() => {
+    if (messagesEndRef.current) {
+      messagesEndRef.current.scrollIntoView({ behavior: 'smooth' });
+    }
+  }, [chatMessages, isChatLoading]);
+
+  const resolveFilePathForUI = useCallback((requestedPath: string): string | null => {
+    const req = requestedPath.replace(/\\/g, '/').replace(/^\.?\//, '').toLowerCase();
+    if (!req) return null;
+
+    // Exact match first (case-insensitive)
+    for (const key of fileContents.keys()) {
+      const norm = key.replace(/\\/g, '/').replace(/^\.?\//, '').toLowerCase();
+      if (norm === req) return key;
+    }
+
+    // Ends-with match (best for partial paths)
+    let best: { path: string; score: number } | null = null;
+    for (const key of fileContents.keys()) {
+      const norm = key.replace(/\\/g, '/').replace(/^\.?\//, '').toLowerCase();
+      if (norm.endsWith(req)) {
+        const score = 1000 - norm.length;
+        if (!best || score > best.score) best = { path: key, score };
+      }
+    }
+    return best?.path ?? null;
+  }, [fileContents]);
+
+  const findFileNodeIdForUI = useCallback((filePath: string): string | undefined => {
+    if (!graph) return undefined;
+    const target = filePath.replace(/\\/g, '/').replace(/^\.?\//, '');
+    const node = graph.nodes.find(
+      (n) => n.label === 'File' && n.properties.filePath.replace(/\\/g, '/').replace(/^\.?\//, '') === target
+    );
+    return node?.id;
+  }, [graph]);
+
+  const handleGroundingClick = useCallback((inner: string) => {
+    const raw = inner.trim();
+    if (!raw) return;
+
+    let rawPath = raw;
+    let startLine1: number | undefined;
+    let endLine1: number | undefined;
+
+    // Match line:num or line:num-num (supports both hyphen - and en dash –)
+    const lineMatch = raw.match(/^(.*):(\d+)(?:[-–](\d+))?$/);
+    if (lineMatch) {
+      rawPath = lineMatch[1].trim();
+      startLine1 = parseInt(lineMatch[2], 10);
+      endLine1 = parseInt(lineMatch[3] || lineMatch[2], 10);
+    }
+
+    const resolvedPath = resolveFilePathForUI(rawPath);
+    if (!resolvedPath) return;
+
+    const nodeId = findFileNodeIdForUI(resolvedPath);
+
+    addCodeReference({
+      filePath: resolvedPath,
+      startLine: startLine1 ? Math.max(0, startLine1 - 1) : undefined,
+      endLine: endLine1 ? Math.max(0, endLine1 - 1) : (startLine1 ? Math.max(0, startLine1 - 1) : undefined),
+      nodeId,
+      label: 'File',
+      name: resolvedPath.split('/').pop() ?? resolvedPath,
+      source: 'ai',
+    });
+  }, [addCodeReference, findFileNodeIdForUI, resolveFilePathForUI]);
+
+  // Handler for node grounding: [[Class:View]], [[Function:trigger]], etc.
+  const handleNodeGroundingClick = useCallback((nodeTypeAndName: string) => {
+    const raw = nodeTypeAndName.trim();
+    if (!raw || !graph) return;
+
+    // Parse Type:Name format
+    const match = raw.match(/^(Class|Function|Method|Interface|File|Folder|Variable|Enum|Type|CodeElement):(.+)$/);
+    if (!match) return;
+
+    const [, nodeType, nodeName] = match;
+    const trimmedName = nodeName.trim();
+
+    // Find node in graph by type + name
+    const node = graph.nodes.find(n =>
+      n.label === nodeType &&
+      n.properties.name === trimmedName
+    );
+
+    if (!node) {
+      console.warn(`Node not found: ${nodeType}:${trimmedName}`);
+      return;
+    }
+
+    // 1. Highlight in graph (add to AI citation highlights)
+    // Note: This requires accessing the state setter from parent context
+    // For now, we'll add to code references which triggers the highlight
+
+    // 2. Add to Code Panel (if node has file/line info)
+    if (node.properties.filePath) {
+      const resolvedPath = resolveFilePathForUI(node.properties.filePath);
+      if (resolvedPath) {
+        addCodeReference({
+          filePath: resolvedPath,
+          startLine: node.properties.startLine ? node.properties.startLine - 1 : undefined,
+          endLine: node.properties.endLine ? node.properties.endLine - 1 : undefined,
+          nodeId: node.id,
+          label: node.label,
+          name: node.properties.name,
+          source: 'ai',
+        });
+      }
+    }
+  }, [graph, resolveFilePathForUI, addCodeReference]);
+
+  const handleLinkClick = useCallback((href: string) => {
+    if (href.startsWith('code-ref:')) {
+      const inner = decodeURIComponent(href.slice('code-ref:'.length));
+      handleGroundingClick(inner);
+    } else if (href.startsWith('node-ref:')) {
+      const inner = decodeURIComponent(href.slice('node-ref:'.length));
+      handleNodeGroundingClick(inner);
+    }
+  }, [handleGroundingClick, handleNodeGroundingClick]);
+
+
+
+  // Auto-resize textarea as user types
+  const adjustTextareaHeight = useCallback(() => {
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+
+    // Reset height to get accurate scrollHeight
+    textarea.style.height = 'auto';
+    // Set to scrollHeight, capped at max
+    const maxHeight = 160; // ~6 lines
+    const newHeight = Math.min(textarea.scrollHeight, maxHeight);
+    textarea.style.height = `${newHeight}px`;
+    // Show scrollbar if content exceeds max
+    textarea.style.overflowY = textarea.scrollHeight > maxHeight ? 'auto' : 'hidden';
+  }, []);
+
+  // Adjust height when input changes
+  useEffect(() => {
+    adjustTextareaHeight();
+  }, [chatInput, adjustTextareaHeight]);
+
+  // Chat handlers
+  const handleSendMessage = async () => {
+    if (!chatInput.trim()) return;
+    const text = chatInput.trim();
+    setChatInput('');
+    // Reset textarea height after sending
+    if (textareaRef.current) {
+      textareaRef.current.style.height = '36px';
+      textareaRef.current.style.overflowY = 'hidden';
+    }
+    await sendChatMessage(text);
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleSendMessage();
+    }
+  };
+
+  const chatSuggestions = [
+    'Explain the project architecture',
+    'What does this project do?',
+    'Show me the most important files',
+    'Find all API handlers',
+  ];
+
+  if (!isRightPanelOpen) return null;
+
+  return (
+    <aside className="w-[40%] min-w-[400px] max-w-[600px] flex flex-col bg-deep border-l border-border-subtle animate-slide-in relative z-30 flex-shrink-0">
+      {/* Header with Tabs */}
+      <div className="flex items-center justify-between px-4 py-2 bg-surface border-b border-border-subtle">
+        <div className="flex items-center gap-1">
+          {/* Chat Tab */}
+          <button
+            onClick={() => setActiveTab('chat')}
+            className={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm font-medium transition-colors ${activeTab === 'chat'
+              ? 'bg-accent/15 text-accent'
+              : 'text-text-muted hover:text-text-primary hover:bg-hover'
+              }`}
+          >
+            <Sparkles className="w-3.5 h-3.5" />
+            <span>Nexus AI</span>
+          </button>
+
+          {/* Activity Tab */}
+          <button
+            onClick={() => setActiveTab('activity')}
+            className={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm font-medium transition-colors ${activeTab === 'activity'
+              ? 'bg-accent/15 text-accent'
+              : 'text-text-muted hover:text-text-primary hover:bg-hover'
+              }`}
+          >
+            <Activity className="w-3.5 h-3.5" />
+            <span>Activity</span>
+          </button>
+        </div>
+
+        {/* Close button */}
+        <button
+          onClick={() => setRightPanelOpen(false)}
+          className="p-1.5 text-text-muted hover:text-text-primary hover:bg-hover rounded transition-colors"
+          title="Close Panel"
+        >
+          <PanelRightClose className="w-4 h-4" />
+        </button>
+      </div>
+
+      {/* Activity Feed Tab */}
+      {activeTab === 'activity' && (
+        <div className="flex-1 flex flex-col overflow-hidden">
+          <ActivityFeed />
+        </div>
+      )}
+
+      {/* Chat Content - only show when chat tab is active */}
+      {activeTab === 'chat' && (
+        <div className="flex-1 flex flex-col overflow-hidden">
+          {/* Status bar */}
+          <div className="flex items-center gap-2.5 px-4 py-3 bg-elevated/50 border-b border-border-subtle">
+            <div className="ml-auto flex items-center gap-2">
+              {!isAgentReady && (
+                <span className="text-[11px] px-2 py-1 rounded-full bg-amber-500/15 text-amber-300 border border-amber-500/30">
+                  Configure AI
+                </span>
+              )}
+              {isAgentInitializing && (
+                <span className="text-[11px] px-2 py-1 rounded-full bg-surface border border-border-subtle flex items-center gap-1 text-text-muted">
+                  <Loader2 className="w-3 h-3 animate-spin" /> Connecting
+                </span>
+              )}
+            </div>
+          </div>
+
+          {/* Status / errors */}
+          {agentError && (
+            <div className="px-4 py-3 bg-rose-500/10 border-b border-rose-500/30 text-rose-100 text-sm flex items-center gap-2">
+              <AlertTriangle className="w-4 h-4" />
+              <span>{agentError}</span>
+            </div>
+          )}
+
+
+
+          {/* Messages */}
+          <div className="flex-1 overflow-y-auto p-4 scrollbar-thin">
+            {chatMessages.length === 0 ? (
+              <div className="flex flex-col items-center justify-center h-full text-center px-4">
+                <div className="w-14 h-14 mb-4 flex items-center justify-center bg-gradient-to-br from-accent to-node-interface rounded-xl shadow-glow text-2xl">
+                  🧠
+                </div>
+                <h3 className="text-base font-medium mb-2">
+                  Ask me anything
+                </h3>
+                <p className="text-sm text-text-secondary leading-relaxed mb-5">
+                  I can help you understand the architecture, find functions, or explain connections.
+                </p>
+                <div className="flex flex-wrap gap-2 justify-center">
+                  {chatSuggestions.map((suggestion) => (
+                    <button
+                      key={suggestion}
+                      onClick={() => setChatInput(suggestion)}
+                      className="px-3 py-1.5 bg-elevated border border-border-subtle rounded-full text-xs text-text-secondary hover:border-accent hover:text-text-primary transition-colors"
+                    >
+                      {suggestion}
+                    </button>
+                  ))}
+                </div>
+              </div>
+            ) : (
+              <div className="flex flex-col gap-6">
+                {chatMessages.map((message) => (
+                  <div
+                    key={message.id}
+                    className="animate-fade-in"
+                  >
+                    {/* User message - compact label style */}
+                    {message.role === 'user' && (
+                      <div className="mb-4">
+                        <div className="flex items-center gap-2 mb-2">
+                          <User className="w-4 h-4 text-text-muted" />
+                          <span className="text-xs font-medium text-text-muted uppercase tracking-wide">You</span>
+                        </div>
+                        <div className="pl-6 text-sm text-text-primary">
+                          {message.content}
+                        </div>
+                      </div>
+                    )}
+
+                    {/* Assistant message - copilot style */}
+                    {message.role === 'assistant' && (
+                      <div>
+                        <div className="flex items-center gap-2 mb-3">
+                          <Sparkles className="w-4 h-4 text-accent" />
+                          <span className="text-xs font-medium text-text-muted uppercase tracking-wide">Nexus AI</span>
+                          {isChatLoading && message === chatMessages[chatMessages.length - 1] && (
+                            <Loader2 className="w-3 h-3 animate-spin text-accent" />
+                          )}
+                        </div>
+                        <div className="pl-6 chat-prose">
+                          {/* Render steps in order (reasoning, tool calls, content interleaved) */}
+                          {message.steps && message.steps.length > 0 ? (
+                            <div className="space-y-4">
+                              {message.steps.map((step) => (
+                                <div key={step.id}>
+                                  {step.type === 'reasoning' && step.content && (
+                                    <div className="text-text-secondary text-sm italic border-l-2 border-text-muted/30 pl-3 mb-3">
+                                      <MarkdownRenderer
+                                        content={step.content}
+                                        onLinkClick={handleLinkClick}
+                                      />
+                                    </div>
+                                  )}
+                                  {step.type === 'tool_call' && step.toolCall && (
+                                    <div className="mb-3">
+                                      <ToolCallCard toolCall={step.toolCall} defaultExpanded={false} />
+                                    </div>
+                                  )}
+                                  {step.type === 'content' && step.content && (
+                                    <MarkdownRenderer
+                                      content={step.content}
+                                      onLinkClick={handleLinkClick}
+                                    />
+                                  )}
+                                </div>
+                              ))}
+                            </div>
+                          ) : (
+                            // Fallback: render content + toolCalls separately (old format)
+                            <MarkdownRenderer
+                              content={message.content}
+                              onLinkClick={handleLinkClick}
+                              toolCalls={message.toolCalls}
+                            />
+                          )}
+                        </div>
+                      </div>
+                    )}
+                  </div>
+                ))}
+
+
+              </div>
+            )}
+            {/* Scroll anchor for auto-scroll */}
+            <div ref={messagesEndRef} />
+          </div>
+
+          {/* Input */}
+          <div className="p-3 bg-surface border-t border-border-subtle">
+            <div className="flex items-end gap-2 px-3 py-2 bg-elevated border border-border-subtle rounded-xl transition-all focus-within:border-accent focus-within:ring-2 focus-within:ring-accent/20">
+              <textarea
+                ref={textareaRef}
+                value={chatInput}
+                onChange={(e) => setChatInput(e.target.value)}
+                onKeyDown={handleKeyDown}
+                placeholder="Ask about the codebase..."
+                rows={1}
+                className="flex-1 bg-transparent border-none outline-none text-sm text-text-primary placeholder:text-text-muted resize-none min-h-[36px] scrollbar-thin"
+                style={{ height: '36px', overflowY: 'hidden' }}
+              />
+              <button
+                onClick={clearChat}
+                className="px-2 py-1 text-xs text-text-muted hover:text-text-primary transition-colors"
+                title="Clear chat"
+              >
+                Clear
+              </button>
+              <button
+                onClick={handleSendMessage}
+                disabled={!chatInput.trim() || isChatLoading || isAgentInitializing}
+                className="w-9 h-9 flex items-center justify-center bg-accent rounded-md text-white transition-all hover:bg-accent-dim disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                {isChatLoading ? <Loader2 className="w-4 h-4 animate-spin" /> : <Send className="w-3.5 h-3.5" />}
+              </button>
+            </div>
+            {!isAgentReady && !isAgentInitializing && (
+              <div className="mt-2 text-xs text-amber-200 flex items-center gap-2">
+                <AlertTriangle className="w-3.5 h-3.5" />
+                <span>
+                  {isProviderConfigured()
+                    ? 'Initializing AI agent...'
+                    : 'Configure an LLM provider to enable chat.'}
+                </span>
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </aside>
+  );
+};
+```
+
+## components/StatusBar.tsx
+
+```text
+import { useAppState } from '../hooks/useAppState';
+
+export const StatusBar = () => {
+  const { graph, progress } = useAppState();
+
+  const nodeCount = graph?.nodes.length ?? 0;
+  const edgeCount = graph?.relationships.length ?? 0;
+
+  // Detect primary language
+  const primaryLanguage = (() => {
+    if (!graph) return null;
+    const languages = graph.nodes
+      .map(n => n.properties.language)
+      .filter(Boolean);
+    if (languages.length === 0) return null;
+    
+    const counts = languages.reduce((acc, lang) => {
+      acc[lang!] = (acc[lang!] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+    
+    return Object.entries(counts).sort((a, b) => b[1] - a[1])[0]?.[0];
+  })();
+
+  return (
+    <footer className="flex items-center justify-between px-5 py-2 bg-deep border-t border-dashed border-border-subtle text-[11px] text-text-muted">
+      {/* Left - Status */}
+      <div className="flex items-center gap-4">
+        {progress && progress.phase !== 'complete' ? (
+          <>
+            <div className="w-28 h-1 bg-elevated rounded-full overflow-hidden">
+              <div 
+                className="h-full bg-gradient-to-r from-accent to-node-interface rounded-full transition-all duration-300"
+                style={{ width: `${progress.percent}%` }}
+              />
+            </div>
+            <span>{progress.message}</span>
+          </>
+        ) : (
+          <div className="flex items-center gap-1.5">
+            <span className="w-1.5 h-1.5 bg-node-function rounded-full" />
+            <span>Ready</span>
+          </div>
+        )}
+      </div>
+
+      {/* Right - Stats */}
+      <div className="flex items-center gap-3">
+        {graph && (
+          <>
+            <span>{nodeCount} nodes</span>
+            <span className="text-border-default">•</span>
+            <span>{edgeCount} edges</span>
+            {primaryLanguage && (
+              <>
+                <span className="text-border-default">•</span>
+                <span>{primaryLanguage}</span>
+              </>
+            )}
+          </>
+        )}
+      </div>
+    </footer>
+  );
+};
+```
+
+## components/ToolCallCard.tsx
+
+```text
+/**
+ * ToolCallCard Component
+ * 
+ * Displays a tool call with expand/collapse functionality.
+ * Shows the tool name, status, and when expanded, the query/args and result.
+ */
+
+import { useState, useCallback, useMemo } from 'react';
+import { ChevronDown, ChevronRight, Sparkles, Check, Loader2, AlertCircle, Eye, EyeOff } from 'lucide-react';
+import type { ToolCallInfo } from '../core/llm/types';
+import { useAppState } from '../hooks/useAppState';
+
+interface ToolCallCardProps {
+  toolCall: ToolCallInfo;
+  /** Start expanded (useful for in-progress calls) */
+  defaultExpanded?: boolean;
+}
+
+/**
+ * Format tool arguments for display
+ */
+const formatArgs = (args: Record<string, unknown>): string => {
+  if (!args || Object.keys(args).length === 0) {
+    return '';
+  }
+
+  // Special handling for Cypher queries
+  if ('query' in args && typeof args.query === 'string') {
+    return args.query;
+  }
+  if ('cypher' in args && typeof args.cypher === 'string') {
+    // For execute_vector_cypher, show both the natural language query and cypher
+    let result = '';
+    if ('query' in args) {
+      result += `Search: "${args.query}"\n\n`;
+    }
+    result += args.cypher;
+    return result;
+  }
+
+  // For other tools, show as formatted JSON
+  return JSON.stringify(args, null, 2);
+};
+
+/**
+ * Get status icon and color
+ */
+const getStatusDisplay = (status: ToolCallInfo['status']) => {
+  switch (status) {
+    case 'running':
+      return {
+        icon: <Loader2 className="w-3.5 h-3.5 animate-spin" />,
+        color: 'text-amber-400',
+        bgColor: 'bg-amber-500/10',
+        borderColor: 'border-amber-500/30',
+      };
+    case 'completed':
+      return {
+        icon: <Check className="w-3.5 h-3.5" />,
+        color: 'text-emerald-400',
+        bgColor: 'bg-emerald-500/10',
+        borderColor: 'border-emerald-500/30',
+      };
+    case 'error':
+      return {
+        icon: <AlertCircle className="w-3.5 h-3.5" />,
+        color: 'text-rose-400',
+        bgColor: 'bg-rose-500/10',
+        borderColor: 'border-rose-500/30',
+      };
+    default:
+      return {
+        icon: <Sparkles className="w-3.5 h-3.5" />,
+        color: 'text-text-muted',
+        bgColor: 'bg-surface',
+        borderColor: 'border-border-subtle',
+      };
+  }
+};
+
+/**
+ * Get a friendly display name for the tool
+ */
+const getToolDisplayName = (name: string): string => {
+  const names: Record<string, string> = {
+    // New consolidated tools
+    'search': '🔍 Search Code',
+    'cypher': '🔍 Cypher Query',
+    'grep': '🔎 Pattern Search',
+    'read': '📄 Read File',
+    'highlight': '✨ Highlight in Graph',
+    // Legacy names (for backwards compatibility)
+    'execute_cypher': '🔍 Cypher Query',
+    'execute_vector_cypher': '🧠 Semantic + Graph Query',
+    'highlight_in_graph': '✨ Highlight in Graph',
+    'grep_code': '🔎 Pattern Search',
+    'read_file': '📄 Read File',
+  };
+  return names[name] || name;
+};
+
+/**
+ * Extract node IDs from highlight tool result
+ */
+const extractHighlightNodeIds = (result: string | undefined): string[] => {
+  if (!result) return [];
+  const match = result.match(/\[HIGHLIGHT_NODES:([^\]]+)\]/);
+  if (match) {
+    return match[1].split(',').map(id => id.trim()).filter(Boolean);
+  }
+  return [];
+};
+
+export const ToolCallCard = ({ toolCall, defaultExpanded = false }: ToolCallCardProps) => {
+  const [isExpanded, setIsExpanded] = useState(defaultExpanded);
+  const { highlightedNodeIds, setHighlightedNodeIds, graph } = useAppState();
+  const status = getStatusDisplay(toolCall.status);
+  const formattedArgs = formatArgs(toolCall.args);
+
+  // Check if this is a highlight tool and extract node IDs
+  const isHighlightTool = toolCall.name === 'highlight_in_graph' || toolCall.name === 'highlight';
+  const rawHighlightNodeIds = isHighlightTool ? extractHighlightNodeIds(toolCall.result) : [];
+
+  // Resolve raw IDs to actual graph node IDs (handles partial ID matching)
+  const resolvedNodeIds = useMemo(() => {
+    if (rawHighlightNodeIds.length === 0 || !graph) return rawHighlightNodeIds;
+
+    const graphNodeIds = graph.nodes.map(n => n.id);
+    const resolved: string[] = [];
+
+    for (const rawId of rawHighlightNodeIds) {
+      if (graphNodeIds.includes(rawId)) {
+        resolved.push(rawId);
+      } else {
+        // Try partial match - find node whose ID ends with the raw ID
+        const found = graphNodeIds.find(gid =>
+          gid.endsWith(rawId) || gid.endsWith(':' + rawId)
+        );
+        if (found) resolved.push(found);
+      }
+    }
+    return resolved;
+  }, [rawHighlightNodeIds, graph]);
+
+  // Check if these specific nodes are currently highlighted
+  const isHighlightActive = resolvedNodeIds.length > 0 &&
+    resolvedNodeIds.some(id => highlightedNodeIds.has(id));
+
+  // Toggle highlight on/off
+  const toggleHighlight = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation(); // Don't trigger expand/collapse
+    if (isHighlightActive) {
+      // Turn off - clear highlights
+      setHighlightedNodeIds(new Set());
+    } else {
+      // Turn on - set these nodes as highlighted
+      setHighlightedNodeIds(new Set(resolvedNodeIds));
+    }
+  }, [isHighlightActive, resolvedNodeIds, setHighlightedNodeIds]);
+
+  return (
+    <div className={`rounded-lg border ${status.borderColor} ${status.bgColor} overflow-hidden transition-all`}>
+      {/* Header - always visible */}
+      <div
+        role="button"
+        tabIndex={0}
+        onClick={() => setIsExpanded(!isExpanded)}
+        onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setIsExpanded(!isExpanded); } }}
+        className="w-full flex items-center gap-2 px-3 py-2 text-left hover:bg-white/5 transition-colors cursor-pointer select-none"
+      >
+        {/* Expand/collapse icon */}
+        <span className="text-text-muted">
+          {isExpanded ? <ChevronDown className="w-4 h-4" /> : <ChevronRight className="w-4 h-4" />}
+        </span>
+
+        {/* Tool name */}
+        <span className="flex-1 text-sm font-medium text-text-primary">
+          {getToolDisplayName(toolCall.name)}
+        </span>
+
+        {/* Highlight toggle button - only for highlight_in_graph tool with results */}
+        {isHighlightTool && resolvedNodeIds.length > 0 && (
+          <button
+            onClick={toggleHighlight}
+            className={`flex items-center gap-1 px-2 py-0.5 rounded text-xs transition-colors ${isHighlightActive
+              ? 'bg-accent/20 text-accent hover:bg-accent/30'
+              : 'bg-surface/50 text-text-muted hover:bg-surface hover:text-text-primary'
+              }`}
+            title={isHighlightActive ? 'Turn off highlight' : 'Turn on highlight'}
+          >
+            {isHighlightActive ? (
+              <>
+                <Eye className="w-3 h-3" />
+                <span>On</span>
+              </>
+            ) : (
+              <>
+                <EyeOff className="w-3 h-3" />
+                <span>Off</span>
+              </>
+            )}
+          </button>
+        )}
+
+        {/* Status indicator */}
+        <span className={`flex items-center gap-1 text-xs ${status.color}`}>
+          {status.icon}
+          <span className="capitalize">{toolCall.status}</span>
+        </span>
+      </div>
+
+      {/* Expanded content */}
+      {isExpanded && (
+        <div className="border-t border-border-subtle/50">
+          {/* Arguments/Query */}
+          {formattedArgs && (
+            <div className="px-3 py-2 border-b border-border-subtle/50">
+              <div className="text-[10px] uppercase tracking-wider text-text-muted mb-1.5">
+                {toolCall.name.includes('cypher') ? 'Query' : 'Input'}
+              </div>
+              <pre className="text-xs text-text-secondary bg-surface/50 rounded p-2 overflow-x-auto whitespace-pre-wrap font-mono">
+                {formattedArgs}
+              </pre>
+            </div>
+          )}
+
+          {/* Result */}
+          {toolCall.result && (
+            <div className="px-3 py-2">
+              <div className="text-[10px] uppercase tracking-wider text-text-muted mb-1.5">
+                Result
+              </div>
+              <div className="max-h-[400px] overflow-y-auto bg-surface/50 rounded">
+                <pre className="text-xs text-text-secondary p-2 whitespace-pre-wrap font-mono">
+                  {toolCall.result.length > 3000
+                    ? toolCall.result.slice(0, 3000) + '\n\n... (truncated)'
+                    : toolCall.result
+                  }
+                </pre>
+              </div>
+            </div>
+          )}
+
+          {/* Loading state for in-progress */}
+          {toolCall.status === 'running' && !toolCall.result && (
+            <div className="px-3 py-3 flex items-center gap-2 text-xs text-text-muted">
+              <Loader2 className="w-3 h-3 animate-spin" />
+              <span>Executing...</span>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default ToolCallCard;
+```
+
+## components/WebGPUFallbackDialog.tsx
+
+```text
+import { useState, useEffect } from 'react';
+import { X, Snail, Rocket, SkipForward } from 'lucide-react';
+
+interface WebGPUFallbackDialogProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onUseCPU: () => void;
+  onSkip: () => void;
+  nodeCount: number;
+}
+
+/**
+ * Fun dialog shown when WebGPU isn't available
+ * Lets user choose: CPU fallback (slow) or skip embeddings
+ */
+export const WebGPUFallbackDialog = ({
+  isOpen,
+  onClose,
+  onUseCPU,
+  onSkip,
+  nodeCount,
+}: WebGPUFallbackDialogProps) => {
+  const [isAnimating, setIsAnimating] = useState(true);
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Trigger animation after mount
+      requestAnimationFrame(() => setIsVisible(true));
+    } else {
+      setIsVisible(false);
+    }
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  // Estimate time based on node count (rough: ~50ms per node on CPU)
+  const estimatedMinutes = Math.ceil((nodeCount * 50) / 60000);
+  const isSmallCodebase = nodeCount < 200;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      {/* Backdrop */}
+      <div 
+        className={`absolute inset-0 bg-black/60 backdrop-blur-sm transition-opacity duration-200 ${isVisible ? 'opacity-100' : 'opacity-0'}`}
+        onClick={onClose}
+      />
+      
+      {/* Dialog */}
+      <div 
+        className={`relative bg-surface border border-border-subtle rounded-2xl shadow-2xl max-w-md w-full mx-4 overflow-hidden transition-all duration-200 ${isVisible ? 'opacity-100 scale-100' : 'opacity-0 scale-95'}`}
+      >
+        {/* Header with scratching emoji */}
+        <div className="relative bg-gradient-to-r from-amber-500/20 to-orange-500/20 px-6 py-5 border-b border-border-subtle">
+          <button
+            onClick={onClose}
+            className="absolute top-4 right-4 p-1 text-text-muted hover:text-text-primary transition-colors"
+          >
+            <X className="w-5 h-5" />
+          </button>
+          
+          <div className="flex items-center gap-4">
+            {/* Animated emoji */}
+            <div 
+              className={`text-5xl ${isAnimating ? 'animate-bounce' : ''}`}
+              onAnimationEnd={() => setIsAnimating(false)}
+              onClick={() => setIsAnimating(true)}
+            >
+              🤔
+            </div>
+            <div>
+              <h2 className="text-lg font-semibold text-text-primary">
+                WebGPU said "nope"
+              </h2>
+              <p className="text-sm text-text-muted mt-0.5">
+                Your browser doesn't support GPU acceleration
+              </p>
+            </div>
+          </div>
+        </div>
+
+        {/* Content */}
+        <div className="px-6 py-5 space-y-4">
+          <p className="text-sm text-text-secondary leading-relaxed">
+            Couldn't create embeddings with WebGPU, so semantic search (Graph RAG) 
+            won't be as smart. The graph still works fine though! 
+          </p>
+          
+          <div className="bg-elevated/50 rounded-lg p-4 border border-border-subtle">
+            <p className="text-sm text-text-secondary">
+              <span className="font-medium text-text-primary">Your options:</span>
+            </p>
+            <ul className="mt-2 space-y-1.5 text-sm text-text-muted">
+              <li className="flex items-start gap-2">
+                <Snail className="w-4 h-4 mt-0.5 text-amber-400 flex-shrink-0" />
+                <span>
+                  <strong className="text-text-secondary">Use CPU</strong> — Works but {isSmallCodebase ? 'a bit' : 'way'} slower
+                  {nodeCount > 0 && (
+                    <span className="text-text-muted"> (~{estimatedMinutes} min for {nodeCount} nodes)</span>
+                  )}
+                </span>
+              </li>
+              <li className="flex items-start gap-2">
+                <SkipForward className="w-4 h-4 mt-0.5 text-blue-400 flex-shrink-0" />
+                <span>
+                  <strong className="text-text-secondary">Skip it</strong> — Graph works, just no AI semantic search
+                </span>
+              </li>
+            </ul>
+          </div>
+
+          {isSmallCodebase && (
+            <p className="text-xs text-node-function flex items-center gap-1.5 bg-node-function/10 px-3 py-2 rounded-lg">
+              <Rocket className="w-3.5 h-3.5" />
+              Small codebase detected! CPU should be fine.
+            </p>
+          )}
+
+          <p className="text-xs text-text-muted">
+            💡 Tip: Try Chrome or Edge for WebGPU support
+          </p>
+        </div>
+
+        {/* Actions */}
+        <div className="px-6 py-4 bg-elevated/30 border-t border-border-subtle flex gap-3">
+          <button
+            onClick={onSkip}
+            className="flex-1 px-4 py-2.5 text-sm font-medium text-text-secondary bg-surface border border-border-subtle rounded-lg hover:bg-hover hover:text-text-primary transition-all flex items-center justify-center gap-2"
+          >
+            <SkipForward className="w-4 h-4" />
+            Skip Embeddings
+          </button>
+          <button
+            onClick={onUseCPU}
+            className={`flex-1 px-4 py-2.5 text-sm font-medium rounded-lg transition-all flex items-center justify-center gap-2 ${
+              isSmallCodebase
+                ? 'bg-node-function text-white hover:bg-node-function/90'
+                : 'bg-amber-500/20 text-amber-300 border border-amber-500/30 hover:bg-amber-500/30'
+            }`}
+          >
+            <Snail className="w-4 h-4" />
+            Use CPU {isSmallCodebase ? '(Recommended)' : '(Slow)'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+## config/ignore-service.ts
+
+```typescript
+const DEFAULT_IGNORE_LIST = new Set([
+    // Version Control
+    '.git',
+    '.svn',
+    '.hg',
+    '.bzr',
+    
+    // IDEs & Editors
+    '.idea',
+    '.vscode',
+    '.vs',
+    '.eclipse',
+    '.settings',
+    '.DS_Store',
+    'Thumbs.db',
+  
+    // Dependencies
+    'node_modules',
+    'bower_components',
+    'jspm_packages',
+    'vendor',           // PHP/Go
+    // 'packages' removed - commonly used for monorepo source code (lerna, pnpm, yarn workspaces)
+    'venv',
+    '.venv',
+    'env',
+    '.env',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    'site-packages',
+    '.tox',
+    'eggs',
+    '.eggs',
+    'lib64',
+    'parts',
+    'sdist',
+    'wheels',
+  
+    // Build Outputs
+    'dist',
+    'build',
+    'out',
+    'output',
+    'bin',
+    'obj',
+    'target',           // Java/Rust
+    '.next',
+    '.nuxt',
+    '.output',
+    '.vercel',
+    '.netlify',
+    '.serverless',
+    '_build',
+    'public/build',
+    '.parcel-cache',
+    '.turbo',
+    '.svelte-kit',
+  
+    // Test & Coverage
+    'coverage',
+    '.nyc_output',
+    'htmlcov',
+    '.coverage',
+    '__tests__',        // Often just test files
+    '__mocks__',
+    '.jest',
+    
+    // Logs & Temp
+    'logs',
+    'log',
+    'tmp',
+    'temp',
+    'cache',
+    '.cache',
+    '.tmp',
+    '.temp',
+    
+    // Generated/Compiled
+    '.generated',
+    'generated',
+    'auto-generated',
+    '.terraform',
+    '.serverless',
+    
+    // Documentation (optional - might want to keep)
+    // 'docs',
+    // 'documentation',
+    
+    // Misc
+    '.husky',
+    '.github',          // GitHub config, not code
+    '.circleci',
+    '.gitlab',
+    'fixtures',         // Test fixtures
+    'snapshots',        // Jest snapshots
+    '__snapshots__',
+]);
+
+const IGNORED_EXTENSIONS = new Set([
+    // Images
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp', '.bmp', '.tiff', '.tif',
+    '.psd', '.ai', '.sketch', '.fig', '.xd',
+    
+    // Archives
+    '.zip', '.tar', '.gz', '.rar', '.7z', '.bz2', '.xz', '.tgz',
+    
+    // Binary/Compiled
+    '.exe', '.dll', '.so', '.dylib', '.a', '.lib', '.o', '.obj',
+    '.class', '.jar', '.war', '.ear',
+    '.pyc', '.pyo', '.pyd',
+    '.beam',            // Erlang
+    '.wasm',            // WebAssembly - important!
+    '.node',            // Native Node addons
+    
+    // Documents
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+    '.odt', '.ods', '.odp',
+    
+    // Media
+    '.mp4', '.mp3', '.wav', '.mov', '.avi', '.mkv', '.flv', '.wmv',
+    '.ogg', '.webm', '.flac', '.aac', '.m4a',
+    
+    // Fonts
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    
+    // Databases
+    '.db', '.sqlite', '.sqlite3', '.mdb', '.accdb',
+    
+    // Minified/Bundled files
+    '.min.js', '.min.css', '.bundle.js', '.chunk.js',
+    
+    // Source maps (debug files, not source)
+    '.map',
+    
+    // Lock files (handled separately, but also here)
+    '.lock',
+    
+    // Certificates & Keys (security - don't index!)
+    '.pem', '.key', '.crt', '.cer', '.p12', '.pfx',
+    
+    // Data files (often large/binary)
+    '.csv', '.tsv', '.parquet', '.avro', '.feather',
+    '.npy', '.npz', '.pkl', '.pickle', '.h5', '.hdf5',
+    
+    // Misc binary
+    '.bin', '.dat', '.data', '.raw',
+    '.iso', '.img', '.dmg',
+]);
+
+// Files to ignore by exact name
+const IGNORED_FILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'composer.lock',
+    'Gemfile.lock',
+    'poetry.lock',
+    'Cargo.lock',
+    'go.sum',
+    '.gitignore',
+    '.gitattributes',
+    '.npmrc',
+    '.yarnrc',
+    '.editorconfig',
+    '.prettierrc',
+    '.prettierignore',
+    '.eslintignore',
+    '.dockerignore',
+    'Thumbs.db',
+    '.DS_Store',
+    'LICENSE',
+    'LICENSE.md',
+    'LICENSE.txt',
+    'CHANGELOG.md',
+    'CHANGELOG',
+    'CONTRIBUTING.md',
+    'CODE_OF_CONDUCT.md',
+    'SECURITY.md',
+    '.env',
+    '.env.local',
+    '.env.development',
+    '.env.production',
+    '.env.test',
+    '.env.example',
+]);
+
+
+
+export const shouldIgnorePath = (filePath: string): boolean => {
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const parts = normalizedPath.split('/');
+  const fileName = parts[parts.length - 1];
+  const fileNameLower = fileName.toLowerCase();
+
+  // Check if any path segment is in ignore list
+  for (const part of parts) {
+    if (DEFAULT_IGNORE_LIST.has(part)) {
+      return true;
+    }
+  }
+
+  // Check exact filename matches
+  if (IGNORED_FILES.has(fileName) || IGNORED_FILES.has(fileNameLower)) {
+    return true;
+  }
+
+  // Check extension
+  const lastDotIndex = fileNameLower.lastIndexOf('.');
+  if (lastDotIndex !== -1) {
+    const ext = fileNameLower.substring(lastDotIndex);
+    if (IGNORED_EXTENSIONS.has(ext)) return true;
+    
+    // Handle compound extensions like .min.js, .bundle.js
+    const secondLastDot = fileNameLower.lastIndexOf('.', lastDotIndex - 1);
+    if (secondLastDot !== -1) {
+      const compoundExt = fileNameLower.substring(secondLastDot);
+      if (IGNORED_EXTENSIONS.has(compoundExt)) return true;
+    }
+  }
+
+  // Ignore hidden files (starting with .)
+  if (fileName.startsWith('.') && fileName !== '.') {
+    // But allow some important config files
+    const allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
+    // Actually, let's NOT ignore all dot files - many are important configs
+    // Just rely on the explicit lists above
+  }
+
+  // Ignore files that look like generated/bundled code
+  if (fileNameLower.includes('.bundle.') || 
+      fileNameLower.includes('.chunk.') ||
+      fileNameLower.includes('.generated.') ||
+      fileNameLower.endsWith('.d.ts')) { // TypeScript declaration files
+    return true;
+  }
+
+  return false;
+}
+```
+
+## config/supported-languages.ts
+
+```typescript
+export enum SupportedLanguages {
+    JavaScript = 'javascript',
+    TypeScript = 'typescript',
+    Python = 'python',
+    // Java = 'java',
+    // C = 'c',
+    // CPlusPlus = 'cpp',
+    // CSharp = 'csharp',
+    // Go = 'go',
+    // Rust = 'rust',
+    // PHP = 'php',
+    // Ruby = 'ruby',
+    // Swift = 'swift',
+}
+```
+
+## core/embeddings/embedder.ts
+
+```typescript
+/**
+ * Embedder Module
+ * 
+ * Singleton factory for transformers.js embedding pipeline.
+ * Handles model loading, caching, and both single and batch embedding operations.
+ * 
+ * Uses snowflake-arctic-embed-xs by default (22M params, 384 dims, ~90MB)
+ */
+
+import { pipeline, env, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig, type ModelProgress } from './types';
+
+// Module-level state for singleton pattern
+let embedderInstance: FeatureExtractionPipeline | null = null;
+let isInitializing = false;
+let initPromise: Promise<FeatureExtractionPipeline> | null = null;
+let currentDevice: 'webgpu' | 'wasm' | null = null;
+
+/**
+ * Progress callback type for model loading
+ */
+export type ModelProgressCallback = (progress: ModelProgress) => void;
+
+/**
+ * Custom error thrown when WebGPU is not available
+ * Allows UI to prompt user for fallback choice
+ */
+export class WebGPUNotAvailableError extends Error {
+  constructor(originalError?: Error) {
+    super('WebGPU not available in this browser');
+    this.name = 'WebGPUNotAvailableError';
+    this.cause = originalError;
+  }
+}
+
+/**
+ * Check if WebGPU is available in this browser
+ * Quick check without loading the model
+ */
+export const checkWebGPUAvailability = async (): Promise<boolean> => {
+  try {
+    // Cast to any to avoid WebGPU types not being available in all TS configs
+    const nav = navigator as any;
+    if (!nav.gpu) {
+      return false;
+    }
+    const adapter = await nav.gpu.requestAdapter();
+    if (!adapter) {
+      return false;
+    }
+    // Try to get a device - this is where it usually fails
+    const device = await adapter.requestDevice();
+    device.destroy(); // Clean up
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Get the current device being used for inference
+ */
+export const getCurrentDevice = (): 'webgpu' | 'wasm' | null => currentDevice;
+
+/**
+ * Initialize the embedding model
+ * Uses singleton pattern - only loads once, subsequent calls return cached instance
+ * 
+ * @param onProgress - Optional callback for model download progress
+ * @param config - Optional configuration override
+ * @param forceDevice - Force a specific device (bypasses WebGPU check)
+ * @returns Promise resolving to the embedder pipeline
+ * @throws WebGPUNotAvailableError if WebGPU is requested but unavailable
+ */
+export const initEmbedder = async (
+  onProgress?: ModelProgressCallback,
+  config: Partial<EmbeddingConfig> = {},
+  forceDevice?: 'webgpu' | 'wasm'
+): Promise<FeatureExtractionPipeline> => {
+  // Return existing instance if available
+  if (embedderInstance) {
+    return embedderInstance;
+  }
+
+  // If already initializing, wait for that promise
+  if (isInitializing && initPromise) {
+    return initPromise;
+  }
+
+  isInitializing = true;
+  
+  const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
+  const requestedDevice = forceDevice || finalConfig.device;
+
+  initPromise = (async () => {
+    try {
+      // Configure transformers.js environment
+      env.allowLocalModels = false;
+      
+      if (import.meta.env.DEV) {
+        console.log(`🧠 Loading embedding model: ${finalConfig.modelId}`);
+      }
+
+      const progressCallback = onProgress ? (data: any) => {
+        const progress: ModelProgress = {
+          status: data.status || 'progress',
+          file: data.file,
+          progress: data.progress,
+          loaded: data.loaded,
+          total: data.total,
+        };
+        onProgress(progress);
+      } : undefined;
+
+      // If WebGPU is requested (default), check availability first
+      if (requestedDevice === 'webgpu') {
+        if (import.meta.env.DEV) {
+          console.log('🔧 Checking WebGPU availability...');
+        }
+        
+        const webgpuAvailable = await checkWebGPUAvailability();
+        
+        if (!webgpuAvailable) {
+          if (import.meta.env.DEV) {
+            console.warn('⚠️ WebGPU not available');
+          }
+          isInitializing = false;
+          initPromise = null;
+          throw new WebGPUNotAvailableError();
+        }
+        
+        // Try WebGPU
+        try {
+          if (import.meta.env.DEV) {
+            console.log('🔧 Initializing WebGPU backend...');
+          }
+          
+          // Type assertion needed due to complex union types in transformers.js
+          embedderInstance = await (pipeline as any)(
+            'feature-extraction',
+            finalConfig.modelId,
+            {
+              device: 'webgpu',
+              dtype: 'fp32',
+              progress_callback: progressCallback,
+            }
+          );
+          currentDevice = 'webgpu';
+          
+          if (import.meta.env.DEV) {
+            console.log('✅ Using WebGPU backend');
+          }
+        } catch (err) {
+          if (import.meta.env.DEV) {
+            console.warn('⚠️ WebGPU initialization failed:', err);
+          }
+          isInitializing = false;
+          initPromise = null;
+          embedderInstance = null;
+          throw new WebGPUNotAvailableError(err as Error);
+        }
+      } else {
+        // WASM mode requested (user chose fallback)
+        if (import.meta.env.DEV) {
+          console.log('🔧 Initializing WASM backend (this will be slower)...');
+        }
+        
+        // Type assertion needed due to complex union types in transformers.js
+        embedderInstance = await (pipeline as any)(
+          'feature-extraction',
+          finalConfig.modelId,
+          {
+            device: 'wasm', // WASM-based CPU execution
+            dtype: 'fp32',
+            progress_callback: progressCallback,
+          }
+        );
+        currentDevice = 'wasm';
+        
+        if (import.meta.env.DEV) {
+          console.log('✅ Using WASM backend');
+        }
+      }
+
+      if (import.meta.env.DEV) {
+        console.log('✅ Embedding model loaded successfully');
+      }
+
+      return embedderInstance!;
+    } catch (error) {
+      // Re-throw WebGPUNotAvailableError as-is
+      if (error instanceof WebGPUNotAvailableError) {
+        throw error;
+      }
+      isInitializing = false;
+      initPromise = null;
+      embedderInstance = null;
+      throw error;
+    } finally {
+      isInitializing = false;
+    }
+  })();
+
+  return initPromise;
+};
+
+/**
+ * Check if the embedder is initialized and ready
+ */
+export const isEmbedderReady = (): boolean => {
+  return embedderInstance !== null;
+};
+
+/**
+ * Get the embedder instance (throws if not initialized)
+ */
+export const getEmbedder = (): FeatureExtractionPipeline => {
+  if (!embedderInstance) {
+    throw new Error('Embedder not initialized. Call initEmbedder() first.');
+  }
+  return embedderInstance;
+};
+
+/**
+ * Embed a single text string
+ * 
+ * @param text - Text to embed
+ * @returns Float32Array of embedding vector (384 dimensions)
+ */
+export const embedText = async (text: string): Promise<Float32Array> => {
+  const embedder = getEmbedder();
+  
+  const result = await embedder(text, {
+    pooling: 'mean',
+    normalize: true,
+  });
+  
+  // Result is a Tensor, convert to Float32Array
+  return new Float32Array(result.data as ArrayLike<number>);
+};
+
+/**
+ * Embed multiple texts in a single batch
+ * More efficient than calling embedText multiple times
+ * 
+ * @param texts - Array of texts to embed
+ * @returns Array of Float32Array embedding vectors
+ */
+export const embedBatch = async (texts: string[]): Promise<Float32Array[]> => {
+  if (texts.length === 0) {
+    return [];
+  }
+
+  const embedder = getEmbedder();
+  
+  // Process batch
+  const result = await embedder(texts, {
+    pooling: 'mean',
+    normalize: true,
+  });
+  
+  // Result shape is [batch_size, dimensions]
+  // Need to split into individual vectors
+  const data = result.data as ArrayLike<number>;
+  const dimensions = DEFAULT_EMBEDDING_CONFIG.dimensions;
+  const embeddings: Float32Array[] = [];
+  
+  for (let i = 0; i < texts.length; i++) {
+    const start = i * dimensions;
+    const end = start + dimensions;
+    embeddings.push(new Float32Array(Array.prototype.slice.call(data, start, end)));
+  }
+  
+  return embeddings;
+};
+
+/**
+ * Convert Float32Array to regular number array (for KuzuDB storage)
+ */
+export const embeddingToArray = (embedding: Float32Array): number[] => {
+  return Array.from(embedding);
+};
+
+/**
+ * Cleanup the embedder (free memory)
+ * Call this when done with embeddings
+ */
+export const disposeEmbedder = async (): Promise<void> => {
+  if (embedderInstance) {
+    // transformers.js pipelines may have a dispose method
+    try {
+      if ('dispose' in embedderInstance && typeof embedderInstance.dispose === 'function') {
+        await embedderInstance.dispose();
+      }
+    } catch {
+      // Ignore disposal errors
+    }
+    embedderInstance = null;
+    initPromise = null;
+  }
+};
+```
+
+## core/embeddings/embedding-pipeline.ts
+
+```typescript
+/**
+ * Embedding Pipeline Module
+ * 
+ * Orchestrates the background embedding process:
+ * 1. Query embeddable nodes from KuzuDB
+ * 2. Generate text representations
+ * 3. Batch embed using transformers.js
+ * 4. Update KuzuDB with embeddings
+ * 5. Create vector index for semantic search
+ */
+
+import { initEmbedder, embedBatch, embedText, embeddingToArray, isEmbedderReady } from './embedder';
+import { generateBatchEmbeddingTexts, generateEmbeddingText } from './text-generator';
+import {
+  type EmbeddingProgress,
+  type EmbeddingConfig,
+  type EmbeddableNode,
+  type SemanticSearchResult,
+  type ModelProgress,
+  DEFAULT_EMBEDDING_CONFIG,
+  EMBEDDABLE_LABELS,
+} from './types';
+
+/**
+ * Progress callback type
+ */
+export type EmbeddingProgressCallback = (progress: EmbeddingProgress) => void;
+
+/**
+ * Query all embeddable nodes from KuzuDB
+ * Uses table-specific queries (File has different schema than code elements)
+ */
+const queryEmbeddableNodes = async (
+  executeQuery: (cypher: string) => Promise<any[]>
+): Promise<EmbeddableNode[]> => {
+  const allNodes: EmbeddableNode[] = [];
+  
+  // Query each embeddable table with table-specific columns
+  for (const label of EMBEDDABLE_LABELS) {
+    try {
+      let query: string;
+      
+      if (label === 'File') {
+        // File nodes don't have startLine/endLine
+        query = `
+          MATCH (n:File)
+          RETURN n.id AS id, n.name AS name, 'File' AS label, 
+                 n.filePath AS filePath, n.content AS content
+        `;
+      } else {
+        // Code elements have startLine/endLine
+        query = `
+          MATCH (n:${label})
+          RETURN n.id AS id, n.name AS name, '${label}' AS label, 
+                 n.filePath AS filePath, n.content AS content,
+                 n.startLine AS startLine, n.endLine AS endLine
+        `;
+      }
+      
+      const rows = await executeQuery(query);
+      for (const row of rows) {
+        allNodes.push({
+          id: row.id ?? row[0],
+          name: row.name ?? row[1],
+          label: row.label ?? row[2],
+          filePath: row.filePath ?? row[3],
+          content: row.content ?? row[4] ?? '',
+          startLine: row.startLine ?? row[5],
+          endLine: row.endLine ?? row[6],
+        });
+      }
+    } catch (error) {
+      // Table might not exist or be empty, continue
+      if (import.meta.env.DEV) {
+        console.warn(`Query for ${label} nodes failed:`, error);
+      }
+    }
+  }
+
+  return allNodes;
+};
+
+/**
+ * Batch INSERT embeddings into separate CodeEmbedding table
+ * Using a separate lightweight table avoids copy-on-write overhead
+ * that occurs when UPDATEing nodes with large content fields
+ */
+const batchInsertEmbeddings = async (
+  executeWithReusedStatement: (
+    cypher: string,
+    paramsList: Array<Record<string, any>>
+  ) => Promise<void>,
+  updates: Array<{ id: string; embedding: number[] }>
+): Promise<void> => {
+  // INSERT into separate embedding table - much more memory efficient!
+  const cypher = `CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`;
+  const paramsList = updates.map(u => ({ nodeId: u.id, embedding: u.embedding }));
+  await executeWithReusedStatement(cypher, paramsList);
+};
+
+/**
+ * Create the vector index for semantic search
+ * Now indexes the separate CodeEmbedding table
+ */
+const createVectorIndex = async (
+  executeQuery: (cypher: string) => Promise<any[]>
+): Promise<void> => {
+  const cypher = `
+    CALL CREATE_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 'embedding', metric := 'cosine')
+  `;
+
+  try {
+    await executeQuery(cypher);
+  } catch (error) {
+    // Index might already exist
+    if (import.meta.env.DEV) {
+      console.warn('Vector index creation warning:', error);
+    }
+  }
+};
+
+/**
+ * Run the embedding pipeline
+ * 
+ * @param executeQuery - Function to execute Cypher queries against KuzuDB
+ * @param executeWithReusedStatement - Function to execute with reused prepared statement
+ * @param onProgress - Callback for progress updates
+ * @param config - Optional configuration override
+ */
+export const runEmbeddingPipeline = async (
+  executeQuery: (cypher: string) => Promise<any[]>,
+  executeWithReusedStatement: (cypher: string, paramsList: Array<Record<string, any>>) => Promise<void>,
+  onProgress: EmbeddingProgressCallback,
+  config: Partial<EmbeddingConfig> = {}
+): Promise<void> => {
+  const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
+
+  try {
+    // Phase 1: Load embedding model
+    onProgress({
+      phase: 'loading-model',
+      percent: 0,
+      modelDownloadPercent: 0,
+    });
+
+    await initEmbedder((modelProgress: ModelProgress) => {
+      // Report model download progress
+      const downloadPercent = modelProgress.progress ?? 0;
+      onProgress({
+        phase: 'loading-model',
+        percent: Math.round(downloadPercent * 0.2), // 0-20% for model loading
+        modelDownloadPercent: downloadPercent,
+      });
+    }, finalConfig);
+
+    onProgress({
+      phase: 'loading-model',
+      percent: 20,
+      modelDownloadPercent: 100,
+    });
+
+    if (import.meta.env.DEV) {
+      console.log('🔍 Querying embeddable nodes...');
+    }
+
+    // Phase 2: Query embeddable nodes
+    const nodes = await queryEmbeddableNodes(executeQuery);
+    const totalNodes = nodes.length;
+
+    if (import.meta.env.DEV) {
+      console.log(`📊 Found ${totalNodes} embeddable nodes`);
+    }
+
+    if (totalNodes === 0) {
+      onProgress({
+        phase: 'ready',
+        percent: 100,
+        nodesProcessed: 0,
+        totalNodes: 0,
+      });
+      return;
+    }
+
+    // Phase 3: Batch embed nodes
+    const batchSize = finalConfig.batchSize;
+    const totalBatches = Math.ceil(totalNodes / batchSize);
+    let processedNodes = 0;
+
+    onProgress({
+      phase: 'embedding',
+      percent: 20,
+      nodesProcessed: 0,
+      totalNodes,
+      currentBatch: 0,
+      totalBatches,
+    });
+
+    for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
+      const start = batchIndex * batchSize;
+      const end = Math.min(start + batchSize, totalNodes);
+      const batch = nodes.slice(start, end);
+
+      // Generate texts for this batch
+      const texts = generateBatchEmbeddingTexts(batch, finalConfig);
+
+      // Embed the batch
+      const embeddings = await embedBatch(texts);
+
+      // Update KuzuDB with embeddings
+      const updates = batch.map((node, i) => ({
+        id: node.id,
+        embedding: embeddingToArray(embeddings[i]),
+      }));
+
+      await batchInsertEmbeddings(executeWithReusedStatement, updates);
+
+      processedNodes += batch.length;
+
+      // Report progress (20-90% for embedding phase)
+      const embeddingProgress = 20 + ((processedNodes / totalNodes) * 70);
+      onProgress({
+        phase: 'embedding',
+        percent: Math.round(embeddingProgress),
+        nodesProcessed: processedNodes,
+        totalNodes,
+        currentBatch: batchIndex + 1,
+        totalBatches,
+      });
+    }
+
+    // Phase 4: Create vector index
+    onProgress({
+      phase: 'indexing',
+      percent: 90,
+      nodesProcessed: totalNodes,
+      totalNodes,
+    });
+
+    if (import.meta.env.DEV) {
+      console.log('📇 Creating vector index...');
+    }
+
+    await createVectorIndex(executeQuery);
+
+    // Complete
+    onProgress({
+      phase: 'ready',
+      percent: 100,
+      nodesProcessed: totalNodes,
+      totalNodes,
+    });
+
+    if (import.meta.env.DEV) {
+      console.log('✅ Embedding pipeline complete!');
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    
+    if (import.meta.env.DEV) {
+      console.error('❌ Embedding pipeline error:', error);
+    }
+
+    onProgress({
+      phase: 'error',
+      percent: 0,
+      error: errorMessage,
+    });
+
+    throw error;
+  }
+};
+
+/**
+ * Perform semantic search using the vector index
+ * 
+ * Uses CodeEmbedding table and queries each node table to get metadata
+ * 
+ * @param executeQuery - Function to execute Cypher queries
+ * @param query - Search query text
+ * @param k - Number of results to return (default: 10)
+ * @param maxDistance - Maximum distance threshold (default: 0.5)
+ * @returns Array of search results ordered by relevance
+ */
+export const semanticSearch = async (
+  executeQuery: (cypher: string) => Promise<any[]>,
+  query: string,
+  k: number = 10,
+  maxDistance: number = 0.5
+): Promise<SemanticSearchResult[]> => {
+  if (!isEmbedderReady()) {
+    throw new Error('Embedding model not initialized. Run embedding pipeline first.');
+  }
+
+  // Embed the query
+  const queryEmbedding = await embedText(query);
+  const queryVec = embeddingToArray(queryEmbedding);
+  const queryVecStr = `[${queryVec.join(',')}]`;
+
+  // Query the vector index on CodeEmbedding to get nodeIds and distances
+  const vectorQuery = `
+    CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
+      CAST(${queryVecStr} AS FLOAT[384]), ${k})
+    YIELD node AS emb, distance
+    WITH emb, distance
+    WHERE distance < ${maxDistance}
+    RETURN emb.nodeId AS nodeId, distance
+    ORDER BY distance
+  `;
+
+  const embResults = await executeQuery(vectorQuery);
+  
+  if (embResults.length === 0) {
+    return [];
+  }
+
+  // Get metadata for each result by querying each node table
+  const results: SemanticSearchResult[] = [];
+  
+  for (const embRow of embResults) {
+    const nodeId = embRow.nodeId ?? embRow[0];
+    const distance = embRow.distance ?? embRow[1];
+    
+    // Extract label from node ID (format: Label:path:name)
+    const labelEndIdx = nodeId.indexOf(':');
+    const label = labelEndIdx > 0 ? nodeId.substring(0, labelEndIdx) : 'Unknown';
+    
+    // Query the specific table for this node
+    // File nodes don't have startLine/endLine
+    try {
+      let nodeQuery: string;
+      if (label === 'File') {
+        nodeQuery = `
+          MATCH (n:File {id: '${nodeId.replace(/'/g, "''")}'}) 
+          RETURN n.name AS name, n.filePath AS filePath
+        `;
+      } else {
+        nodeQuery = `
+          MATCH (n:${label} {id: '${nodeId.replace(/'/g, "''")}'}) 
+          RETURN n.name AS name, n.filePath AS filePath, 
+                 n.startLine AS startLine, n.endLine AS endLine
+        `;
+      }
+      const nodeRows = await executeQuery(nodeQuery);
+      if (nodeRows.length > 0) {
+        const nodeRow = nodeRows[0];
+        results.push({
+          nodeId,
+          name: nodeRow.name ?? nodeRow[0] ?? '',
+          label,
+          filePath: nodeRow.filePath ?? nodeRow[1] ?? '',
+          distance,
+          startLine: label !== 'File' ? (nodeRow.startLine ?? nodeRow[2]) : undefined,
+          endLine: label !== 'File' ? (nodeRow.endLine ?? nodeRow[3]) : undefined,
+        });
+      }
+    } catch {
+      // Table might not exist, skip
+    }
+  }
+
+  return results;
+};
+
+/**
+ * Semantic search with graph expansion (flattened results)
+ * 
+ * Note: With multi-table schema, graph traversal is simplified.
+ * Returns semantic matches with their metadata.
+ * For full graph traversal, use execute_vector_cypher tool directly.
+ * 
+ * @param executeQuery - Function to execute Cypher queries
+ * @param query - Search query text
+ * @param k - Number of initial semantic matches (default: 5)
+ * @param _hops - Unused (kept for API compatibility).
+ * @returns Semantic matches with metadata
+ */
+export const semanticSearchWithContext = async (
+  executeQuery: (cypher: string) => Promise<any[]>,
+  query: string,
+  k: number = 5,
+  _hops: number = 1
+): Promise<any[]> => {
+  // For multi-table schema, just return semantic search results
+  // Graph traversal is complex with separate tables - use execute_vector_cypher instead
+  const results = await semanticSearch(executeQuery, query, k, 0.5);
+  
+  return results.map(r => ({
+    matchId: r.nodeId,
+    matchName: r.name,
+    matchLabel: r.label,
+    matchPath: r.filePath,
+    distance: r.distance,
+    connectedId: null,
+    connectedName: null,
+    connectedLabel: null,
+    relationType: null,
+  }));
+};
+```
+
+## core/embeddings/index.ts
+
+```typescript
+/**
+ * Embeddings Module
+ * 
+ * Re-exports for the embedding pipeline system.
+ */
+
+export * from './types';
+export * from './embedder';
+export * from './text-generator';
+export * from './embedding-pipeline';
+```
+
+## core/embeddings/text-generator.ts
+
+```typescript
+/**
+ * Text Generator Module
+ * 
+ * Pure functions to generate embedding text from code nodes.
+ * Combines node metadata with code snippets for semantic matching.
+ */
+
+import type { EmbeddableNode, EmbeddingConfig } from './types';
+import { DEFAULT_EMBEDDING_CONFIG } from './types';
+
+/**
+ * Extract the filename from a file path
+ */
+const getFileName = (filePath: string): string => {
+  const parts = filePath.split('/');
+  return parts[parts.length - 1] || filePath;
+};
+
+/**
+ * Extract the directory path from a file path
+ */
+const getDirectory = (filePath: string): string => {
+  const parts = filePath.split('/');
+  parts.pop();
+  return parts.join('/') || '';
+};
+
+/**
+ * Truncate content to max length, preserving word boundaries
+ */
+const truncateContent = (content: string, maxLength: number): string => {
+  if (content.length <= maxLength) {
+    return content;
+  }
+  
+  // Find last space before maxLength to avoid cutting words
+  const truncated = content.slice(0, maxLength);
+  const lastSpace = truncated.lastIndexOf(' ');
+  
+  if (lastSpace > maxLength * 0.8) {
+    return truncated.slice(0, lastSpace) + '...';
+  }
+  
+  return truncated + '...';
+};
+
+/**
+ * Clean code content for embedding
+ * Removes excessive whitespace while preserving structure
+ */
+const cleanContent = (content: string): string => {
+  return content
+    // Normalize line endings
+    .replace(/\r\n/g, '\n')
+    // Remove excessive blank lines (more than 2)
+    .replace(/\n{3,}/g, '\n\n')
+    // Trim each line
+    .split('\n')
+    .map(line => line.trimEnd())
+    .join('\n')
+    .trim();
+};
+
+/**
+ * Generate embedding text for a Function node
+ */
+const generateFunctionText = (
+  node: EmbeddableNode,
+  maxSnippetLength: number
+): string => {
+  const parts: string[] = [
+    `Function: ${node.name}`,
+    `File: ${getFileName(node.filePath)}`,
+  ];
+
+  const dir = getDirectory(node.filePath);
+  if (dir) {
+    parts.push(`Directory: ${dir}`);
+  }
+
+  if (node.content) {
+    const cleanedContent = cleanContent(node.content);
+    const snippet = truncateContent(cleanedContent, maxSnippetLength);
+    parts.push('', snippet);
+  }
+
+  return parts.join('\n');
+};
+
+/**
+ * Generate embedding text for a Class node
+ */
+const generateClassText = (
+  node: EmbeddableNode,
+  maxSnippetLength: number
+): string => {
+  const parts: string[] = [
+    `Class: ${node.name}`,
+    `File: ${getFileName(node.filePath)}`,
+  ];
+
+  const dir = getDirectory(node.filePath);
+  if (dir) {
+    parts.push(`Directory: ${dir}`);
+  }
+
+  if (node.content) {
+    const cleanedContent = cleanContent(node.content);
+    const snippet = truncateContent(cleanedContent, maxSnippetLength);
+    parts.push('', snippet);
+  }
+
+  return parts.join('\n');
+};
+
+/**
+ * Generate embedding text for a Method node
+ */
+const generateMethodText = (
+  node: EmbeddableNode,
+  maxSnippetLength: number
+): string => {
+  const parts: string[] = [
+    `Method: ${node.name}`,
+    `File: ${getFileName(node.filePath)}`,
+  ];
+
+  const dir = getDirectory(node.filePath);
+  if (dir) {
+    parts.push(`Directory: ${dir}`);
+  }
+
+  if (node.content) {
+    const cleanedContent = cleanContent(node.content);
+    const snippet = truncateContent(cleanedContent, maxSnippetLength);
+    parts.push('', snippet);
+  }
+
+  return parts.join('\n');
+};
+
+/**
+ * Generate embedding text for an Interface node
+ */
+const generateInterfaceText = (
+  node: EmbeddableNode,
+  maxSnippetLength: number
+): string => {
+  const parts: string[] = [
+    `Interface: ${node.name}`,
+    `File: ${getFileName(node.filePath)}`,
+  ];
+
+  const dir = getDirectory(node.filePath);
+  if (dir) {
+    parts.push(`Directory: ${dir}`);
+  }
+
+  if (node.content) {
+    const cleanedContent = cleanContent(node.content);
+    const snippet = truncateContent(cleanedContent, maxSnippetLength);
+    parts.push('', snippet);
+  }
+
+  return parts.join('\n');
+};
+
+/**
+ * Generate embedding text for a File node
+ * Uses file name and first N characters of content
+ */
+const generateFileText = (
+  node: EmbeddableNode,
+  maxSnippetLength: number
+): string => {
+  const parts: string[] = [
+    `File: ${node.name}`,
+    `Path: ${node.filePath}`,
+  ];
+
+  if (node.content) {
+    const cleanedContent = cleanContent(node.content);
+    // For files, use a shorter snippet since they can be very long
+    const snippet = truncateContent(cleanedContent, Math.min(maxSnippetLength, 300));
+    parts.push('', snippet);
+  }
+
+  return parts.join('\n');
+};
+
+/**
+ * Generate embedding text for any embeddable node
+ * Dispatches to the appropriate generator based on node label
+ * 
+ * @param node - The node to generate text for
+ * @param config - Optional configuration for max snippet length
+ * @returns Text suitable for embedding
+ */
+export const generateEmbeddingText = (
+  node: EmbeddableNode,
+  config: Partial<EmbeddingConfig> = {}
+): string => {
+  const maxSnippetLength = config.maxSnippetLength ?? DEFAULT_EMBEDDING_CONFIG.maxSnippetLength;
+
+  switch (node.label) {
+    case 'Function':
+      return generateFunctionText(node, maxSnippetLength);
+    case 'Class':
+      return generateClassText(node, maxSnippetLength);
+    case 'Method':
+      return generateMethodText(node, maxSnippetLength);
+    case 'Interface':
+      return generateInterfaceText(node, maxSnippetLength);
+    case 'File':
+      return generateFileText(node, maxSnippetLength);
+    default:
+      // Fallback for any other embeddable type
+      return `${node.label}: ${node.name}\nPath: ${node.filePath}`;
+  }
+};
+
+/**
+ * Generate embedding texts for a batch of nodes
+ * 
+ * @param nodes - Array of nodes to generate text for
+ * @param config - Optional configuration
+ * @returns Array of texts in the same order as input nodes
+ */
+export const generateBatchEmbeddingTexts = (
+  nodes: EmbeddableNode[],
+  config: Partial<EmbeddingConfig> = {}
+): string[] => {
+  return nodes.map(node => generateEmbeddingText(node, config));
+};
+```
+
+## core/embeddings/types.ts
+
+```typescript
+/**
+ * Embedding Pipeline Types
+ * 
+ * Type definitions for the embedding generation and semantic search system.
+ */
+
+/**
+ * Node labels that should be embedded for semantic search
+ * These are code elements that benefit from semantic matching
+ */
+export const EMBEDDABLE_LABELS = [
+  'Function',
+  'Class', 
+  'Method',
+  'Interface',
+  'File',
+] as const;
+
+export type EmbeddableLabel = typeof EMBEDDABLE_LABELS[number];
+
+/**
+ * Check if a label should be embedded
+ */
+export const isEmbeddableLabel = (label: string): label is EmbeddableLabel =>
+  EMBEDDABLE_LABELS.includes(label as EmbeddableLabel);
+
+/**
+ * Embedding pipeline phases
+ */
+export type EmbeddingPhase = 
+  | 'idle'
+  | 'loading-model'
+  | 'embedding'
+  | 'indexing'
+  | 'ready'
+  | 'error';
+
+/**
+ * Progress information for the embedding pipeline
+ */
+export interface EmbeddingProgress {
+  phase: EmbeddingPhase;
+  percent: number;
+  modelDownloadPercent?: number;
+  nodesProcessed?: number;
+  totalNodes?: number;
+  currentBatch?: number;
+  totalBatches?: number;
+  error?: string;
+}
+
+/**
+ * Configuration for the embedding pipeline
+ */
+export interface EmbeddingConfig {
+  /** Model identifier for transformers.js */
+  modelId: string;
+  /** Number of nodes to embed in each batch */
+  batchSize: number;
+  /** Embedding vector dimensions */
+  dimensions: number;
+  /** Device to use for inference: 'webgpu' for GPU acceleration, 'wasm' for WASM-based CPU */
+  device: 'webgpu' | 'wasm';
+  /** Maximum characters of code snippet to include */
+  maxSnippetLength: number;
+}
+
+/**
+ * Default embedding configuration
+ * Uses snowflake-arctic-embed-xs for browser efficiency
+ * Tries WebGPU first (fast), user can choose WASM fallback if unavailable
+ */
+export const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig = {
+  modelId: 'Snowflake/snowflake-arctic-embed-xs',
+  batchSize: 16,
+  dimensions: 384,
+  device: 'webgpu', // WebGPU preferred, WASM fallback available if user chooses
+  maxSnippetLength: 500,
+};
+
+/**
+ * Result from semantic search
+ */
+export interface SemanticSearchResult {
+  nodeId: string;
+  name: string;
+  label: string;
+  filePath: string;
+  distance: number;
+  startLine?: number;
+  endLine?: number;
+}
+
+/**
+ * Node data for embedding (minimal structure from KuzuDB query)
+ */
+export interface EmbeddableNode {
+  id: string;
+  name: string;
+  label: string;
+  filePath: string;
+  content: string;
+  startLine?: number;
+  endLine?: number;
+}
+
+/**
+ * Model download progress from transformers.js
+ */
+export interface ModelProgress {
+  status: 'initiate' | 'download' | 'progress' | 'done' | 'ready';
+  file?: string;
+  progress?: number;
+  loaded?: number;
+  total?: number;
+}
+```
+
+## core/graph/graph.ts
+
+```typescript
+import { GraphNode, GraphRelationship, KnowledgeGraph } from './types'
+
+export const createKnowledgeGraph = (): KnowledgeGraph => {
+  const nodeMap = new Map<string, GraphNode>();
+  const relationshipMap = new Map<string, GraphRelationship>();
+
+  const addNode = (node: GraphNode) => {
+    if(!nodeMap.has(node.id)) {
+      nodeMap.set(node.id, node);
+    }
+  };
+
+  const addRelationship = (relationship: GraphRelationship) => {
+    if (!relationshipMap.has(relationship.id)) {
+      relationshipMap.set(relationship.id, relationship);
+    }
+  };
+
+  return{
+    get nodes(){
+      return Array.from(nodeMap.values())
+    },
+  
+    get relationships(){
+      return Array.from(relationshipMap.values())
+    },
+
+    // O(1) count getters - avoid creating arrays just for length
+    get nodeCount() {
+      return nodeMap.size;
+    },
+
+    get relationshipCount() {
+      return relationshipMap.size;
+    },
+
+    addNode,
+    addRelationship,
+
+  };
+};
+```
+
+## core/graph/types.ts
+
+```typescript
+export type NodeLabel =
+  | 'Project'
+  | 'Package'
+  | 'Module'
+  | 'Folder'
+  | 'File'
+  | 'Class'
+  | 'Function'
+  | 'Method'
+  | 'Variable'
+  | 'Interface'
+  | 'Enum'
+  | 'Decorator'
+  | 'Import'
+  | 'Type'
+  | 'CodeElement'
+  | 'Community';
+
+
+export type NodeProperties = {
+  name: string,
+  filePath: string,
+  startLine?: number,
+  endLine?: number,
+  language?: string,
+  isExported?: boolean,
+  // Community-specific properties
+  heuristicLabel?: string,
+  cohesion?: number,
+  symbolCount?: number,
+}
+
+export type RelationshipType = 
+  | 'CONTAINS' 
+  | 'CALLS' 
+  | 'INHERITS' 
+  | 'OVERRIDES' 
+  | 'IMPORTS'
+  | 'USES'
+  | 'DEFINES'
+  | 'DECORATES'
+  | 'IMPLEMENTS'
+  | 'EXTENDS'
+  | 'MEMBER_OF'
+
+export interface GraphNode {
+  id:  string,
+  label: NodeLabel,
+  properties: NodeProperties,  
+}
+
+export interface GraphRelationship {
+  id: string,
+  sourceId: string,
+  targetId: string,
+  type: RelationshipType,
+  /** Confidence score 0-1 (1.0 = certain, lower = uncertain resolution) */
+  confidence: number,
+  /** Resolution reason: 'import-resolved', 'same-file', 'fuzzy-global', or empty for non-CALLS */
+  reason: string,
+}
+
+export interface KnowledgeGraph {
+  nodes: GraphNode[],
+  relationships: GraphRelationship[],
+  nodeCount: number,
+  relationshipCount: number,
+  addNode: (node: GraphNode) => void,
+  addRelationship: (relationship: GraphRelationship) => void,
+}
+```
+
+## core/ingestion/ast-cache.ts
+
+```typescript
+import { LRUCache } from 'lru-cache';
+import Parser from 'web-tree-sitter';
+
+// Define the interface for the Cache
+export interface ASTCache {
+  get: (filePath: string) => Parser.Tree | undefined;
+  set: (filePath: string, tree: Parser.Tree) => void;
+  clear: () => void;
+  stats: () => { size: number; maxSize: number };
+}
+
+export const createASTCache = (maxSize: number = 50): ASTCache => {
+  // Initialize the cache with a 'dispose' handler
+  // This is the magic: When an item is evicted (dropped), this runs automatically.
+  const cache = new LRUCache<string, Parser.Tree>({
+    max: maxSize,
+    dispose: (tree) => {
+      try {
+        // CRITICAL: Free the WASM memory when the tree leaves the cache
+        tree.delete();
+      } catch (e) {
+        console.warn('Failed to delete tree from WASM memory', e);
+      }
+    }
+  });
+
+  return {
+    get: (filePath: string) => {
+      const tree = cache.get(filePath);
+      return tree; // Returns undefined if not found
+    },
+    
+    set: (filePath: string, tree: Parser.Tree) => {
+      cache.set(filePath, tree);
+    },
+    
+    clear: () => {
+      cache.clear();
+    },
+
+    stats: () => ({
+      size: cache.size,
+      maxSize: maxSize
+    })
+  };
+};
+```
+
+## core/ingestion/call-processor.ts
+
+```typescript
+import { KnowledgeGraph } from '../graph/types';
+import { ASTCache } from './ast-cache';
+import { SymbolTable } from './symbol-table';
+import { ImportMap } from './import-processor';
+import { loadParser, loadLanguage } from '../tree-sitter/parser-loader';
+import { LANGUAGE_QUERIES } from './tree-sitter-queries';
+import { generateId } from '../../lib/utils';
+import { getLanguageFromFilename } from './utils';
+
+/**
+ * Node types that represent function/method definitions across languages.
+ * Used to find the enclosing function for a call site.
+ */
+const FUNCTION_NODE_TYPES = new Set([
+  // TypeScript/JavaScript
+  'function_declaration',
+  'arrow_function',
+  'function_expression',
+  'method_definition',
+  'generator_function_declaration',
+  // Python
+  'function_definition',
+  // Common async variants
+  'async_function_declaration',
+  'async_arrow_function',
+]);
+
+/**
+ * Walk up the AST from a node to find the enclosing function/method.
+ * Returns null if the call is at module/file level (top-level code).
+ */
+const findEnclosingFunction = (
+  node: any,
+  filePath: string,
+  symbolTable: SymbolTable
+): string | null => {
+  let current = node.parent;
+  
+  while (current) {
+    if (FUNCTION_NODE_TYPES.has(current.type)) {
+      // Found enclosing function - try to get its name
+      let funcName: string | null = null;
+      
+      // Different node types have different name locations
+      if (current.type === 'function_declaration' || 
+          current.type === 'function_definition' ||
+          current.type === 'async_function_declaration' ||
+          current.type === 'generator_function_declaration') {
+        // Named function: function foo() {}
+        const nameNode = current.childForFieldName?.('name') || 
+                         current.children?.find((c: any) => c.type === 'identifier' || c.type === 'property_identifier');
+        funcName = nameNode?.text;
+      } else if (current.type === 'method_definition') {
+        // Method: foo() {} inside class
+        const nameNode = current.childForFieldName?.('name') ||
+                         current.children?.find((c: any) => c.type === 'property_identifier');
+        funcName = nameNode?.text;
+      } else if (current.type === 'arrow_function' || current.type === 'function_expression') {
+        // Arrow/expression: const foo = () => {} - check parent variable declarator
+        const parent = current.parent;
+        if (parent?.type === 'variable_declarator') {
+          const nameNode = parent.childForFieldName?.('name') ||
+                           parent.children?.find((c: any) => c.type === 'identifier');
+          funcName = nameNode?.text;
+        }
+      }
+      
+      if (funcName) {
+        // Look up the function in symbol table to get its node ID
+        const nodeId = symbolTable.lookupExact(filePath, funcName);
+        if (nodeId) return nodeId;
+        
+        // Fallback: generate ID based on name and file
+        const fallbackLabel = current.type === 'method_definition' ? 'Method' : 'Function';
+        return generateId(fallbackLabel, `${filePath}:${funcName}`);
+      }
+      
+      // Couldn't determine function name - try parent (might be nested)
+    }
+    current = current.parent;
+  }
+  
+  return null; // Top-level call (not inside any function)
+};
+
+export const processCalls = async (
+  graph: KnowledgeGraph,
+  files: { path: string; content: string }[],
+  astCache: ASTCache,
+  symbolTable: SymbolTable,
+  importMap: ImportMap,
+  onProgress?: (current: number, total: number) => void
+) => {
+  const parser = await loadParser();
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    onProgress?.(i + 1, files.length);
+
+    // 1. Check language support first
+    const language = getLanguageFromFilename(file.path);
+    if (!language) continue;
+
+    const queryStr = LANGUAGE_QUERIES[language];
+    if (!queryStr) continue;
+
+    // 2. ALWAYS load the language before querying (parser is stateful)
+    await loadLanguage(language, file.path);
+
+    // 3. Get AST (Try Cache First)
+    let tree = astCache.get(file.path);
+    let wasReparsed = false;
+
+    if (!tree) {
+      // Cache Miss: Re-parse
+      tree = parser.parse(file.content);
+      wasReparsed = true;
+    }
+
+    let query;
+    let matches;
+    try {
+      query = parser.getLanguage().query(queryStr);
+      matches = query.matches(tree.rootNode);
+    } catch (queryError) {
+      console.warn(`Query error for ${file.path}:`, queryError);
+      if (wasReparsed) tree.delete();
+      continue;
+    }
+
+    // 3. Process each call match
+    matches.forEach(match => {
+      const captureMap: Record<string, any> = {};
+      match.captures.forEach(c => captureMap[c.name] = c.node);
+
+      // Only process @call captures
+      if (!captureMap['call']) return;
+
+      const nameNode = captureMap['call.name'];
+      if (!nameNode) return;
+
+      const calledName = nameNode.text;
+
+      // Skip common built-ins and noise
+      if (isBuiltInOrNoise(calledName)) return;
+
+      // 4. Resolve the target using priority strategy (returns confidence)
+      const resolved = resolveCallTarget(
+        calledName,
+        file.path,
+        symbolTable,
+        importMap
+      );
+
+      if (!resolved) return;
+
+      // 5. Find the enclosing function (caller)
+      const callNode = captureMap['call'];
+      const enclosingFuncId = findEnclosingFunction(callNode, file.path, symbolTable);
+      
+      // Use enclosing function as source, fallback to file for top-level calls
+      const sourceId = enclosingFuncId || generateId('File', file.path);
+      
+      const relId = generateId('CALLS', `${sourceId}:${calledName}->${resolved.nodeId}`);
+
+      graph.addRelationship({
+        id: relId,
+        sourceId,
+        targetId: resolved.nodeId,
+        type: 'CALLS',
+        confidence: resolved.confidence,
+        reason: resolved.reason,
+      });
+    });
+
+    // Cleanup if re-parsed
+    if (wasReparsed) {
+      tree.delete();
+    }
+  }
+};
+
+/**
+ * Resolution result with confidence scoring
+ */
+interface ResolveResult {
+  nodeId: string;
+  confidence: number;  // 0-1: how sure are we?
+  reason: string;      // 'import-resolved' | 'same-file' | 'fuzzy-global'
+}
+
+/**
+ * Resolve a function call to its target node ID using priority strategy:
+ * A. Check imported files first (highest confidence)
+ * B. Check local file definitions
+ * C. Fuzzy global search (lowest confidence)
+ * 
+ * Returns confidence score so agents know what to trust.
+ */
+const resolveCallTarget = (
+  calledName: string,
+  currentFile: string,
+  symbolTable: SymbolTable,
+  importMap: ImportMap
+): ResolveResult | null => {
+  // Strategy A: Check imported files (HIGH confidence - we know the import chain)
+  const importedFiles = importMap.get(currentFile);
+  if (importedFiles) {
+    for (const importedFile of importedFiles) {
+      const nodeId = symbolTable.lookupExact(importedFile, calledName);
+      if (nodeId) {
+        return { nodeId, confidence: 0.9, reason: 'import-resolved' };
+      }
+    }
+  }
+
+  // Strategy B: Check local file (HIGH confidence - same file definition)
+  const localNodeId = symbolTable.lookupExact(currentFile, calledName);
+  if (localNodeId) {
+    return { nodeId: localNodeId, confidence: 0.85, reason: 'same-file' };
+  }
+
+  // Strategy C: Fuzzy global search (LOW confidence - just matching by name)
+  const fuzzyMatches = symbolTable.lookupFuzzy(calledName);
+  if (fuzzyMatches.length > 0) {
+    // Lower confidence if multiple matches exist (more ambiguous)
+    const confidence = fuzzyMatches.length === 1 ? 0.5 : 0.3;
+    return { nodeId: fuzzyMatches[0].nodeId, confidence, reason: 'fuzzy-global' };
+  }
+
+  return null;
+};
+
+/**
+ * Filter out common built-in functions and noise
+ * that shouldn't be tracked as calls
+ */
+const isBuiltInOrNoise = (name: string): boolean => {
+  const builtIns = new Set([
+    // JavaScript/TypeScript built-ins
+    'console', 'log', 'warn', 'error', 'info', 'debug',
+    'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
+    'parseInt', 'parseFloat', 'isNaN', 'isFinite',
+    'encodeURI', 'decodeURI', 'encodeURIComponent', 'decodeURIComponent',
+    'JSON', 'parse', 'stringify',
+    'Object', 'Array', 'String', 'Number', 'Boolean', 'Symbol', 'BigInt',
+    'Map', 'Set', 'WeakMap', 'WeakSet',
+    'Promise', 'resolve', 'reject', 'then', 'catch', 'finally',
+    'Math', 'Date', 'RegExp', 'Error',
+    'require', 'import', 'export',
+    'fetch', 'Response', 'Request',
+    // React hooks and common functions
+    'useState', 'useEffect', 'useCallback', 'useMemo', 'useRef', 'useContext',
+    'useReducer', 'useLayoutEffect', 'useImperativeHandle', 'useDebugValue',
+    'createElement', 'createContext', 'createRef', 'forwardRef', 'memo', 'lazy',
+    // Common array/object methods
+    'map', 'filter', 'reduce', 'forEach', 'find', 'findIndex', 'some', 'every',
+    'includes', 'indexOf', 'slice', 'splice', 'concat', 'join', 'split',
+    'push', 'pop', 'shift', 'unshift', 'sort', 'reverse',
+    'keys', 'values', 'entries', 'assign', 'freeze', 'seal',
+    'hasOwnProperty', 'toString', 'valueOf',
+    // Python built-ins
+    'print', 'len', 'range', 'str', 'int', 'float', 'list', 'dict', 'set', 'tuple',
+    'open', 'read', 'write', 'close', 'append', 'extend', 'update',
+    'super', 'type', 'isinstance', 'issubclass', 'getattr', 'setattr', 'hasattr',
+    'enumerate', 'zip', 'sorted', 'reversed', 'min', 'max', 'sum', 'abs',
+  ]);
+
+  return builtIns.has(name);
+};
+```
+
+## core/ingestion/cluster-enricher.ts
+
+```typescript
+/**
+ * Cluster Enricher
+ * 
+ * LLM-based enrichment for community clusters.
+ * Generates semantic names, keywords, and descriptions using an LLM.
+ */
+
+import { CommunityNode } from './community-processor';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ClusterEnrichment {
+  name: string;
+  keywords: string[];
+  description: string;
+}
+
+export interface EnrichmentResult {
+  enrichments: Map<string, ClusterEnrichment>;
+  tokensUsed: number;
+}
+
+export interface LLMClient {
+  generate: (prompt: string) => Promise<string>;
+}
+
+export interface ClusterMemberInfo {
+  name: string;
+  filePath: string;
+  type: string; // 'Function' | 'Class' | 'Method' | 'Interface'
+}
+
+// ============================================================================
+// PROMPT TEMPLATE
+// ============================================================================
+
+const buildEnrichmentPrompt = (
+  members: ClusterMemberInfo[],
+  heuristicLabel: string
+): string => {
+  // Limit to first 30 members to control token usage
+  const limitedMembers = members.slice(0, 30);
+  
+  const memberList = limitedMembers
+    .map(m => `- ${m.name} (${m.type}, ${m.filePath})`)
+    .join('\n');
+  
+  return `You are analyzing a code cluster. Generate a semantic name, keywords, and description.
+
+Current heuristic label: "${heuristicLabel}"
+
+Members (${members.length} total, showing ${limitedMembers.length}):
+${memberList}
+
+Output JSON only:
+{
+  "name": "1-3 word semantic name",
+  "keywords": ["5-10 search terms"],
+  "description": "1 sentence describing what this code does"
+}`;
+};
+
+// ============================================================================
+// PARSE LLM RESPONSE
+// ============================================================================
+
+const parseEnrichmentResponse = (
+  response: string,
+  fallbackLabel: string
+): ClusterEnrichment => {
+  try {
+    // Extract JSON from response (handles markdown code blocks)
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      throw new Error('No JSON found in response');
+    }
+    
+    const parsed = JSON.parse(jsonMatch[0]);
+    
+    return {
+      name: parsed.name || fallbackLabel,
+      keywords: Array.isArray(parsed.keywords) ? parsed.keywords : [],
+      description: parsed.description || '',
+    };
+  } catch {
+    // Fallback if parsing fails
+    return {
+      name: fallbackLabel,
+      keywords: [],
+      description: '',
+    };
+  }
+};
+
+// ============================================================================
+// MAIN ENRICHMENT FUNCTION
+// ============================================================================
+
+/**
+ * Enrich clusters with LLM-generated names, keywords, and descriptions
+ * 
+ * @param communities - Community nodes to enrich
+ * @param memberMap - Map of communityId -> member info
+ * @param llmClient - LLM client for generation
+ * @param onProgress - Progress callback
+ */
+export const enrichClusters = async (
+  communities: CommunityNode[],
+  memberMap: Map<string, ClusterMemberInfo[]>,
+  llmClient: LLMClient,
+  onProgress?: (current: number, total: number) => void
+): Promise<EnrichmentResult> => {
+  const enrichments = new Map<string, ClusterEnrichment>();
+  let tokensUsed = 0;
+  
+  for (let i = 0; i < communities.length; i++) {
+    const community = communities[i];
+    const members = memberMap.get(community.id) || [];
+    
+    onProgress?.(i + 1, communities.length);
+    
+    if (members.length === 0) {
+      // No members, use heuristic
+      enrichments.set(community.id, {
+        name: community.heuristicLabel,
+        keywords: [],
+        description: '',
+      });
+      continue;
+    }
+    
+    try {
+      const prompt = buildEnrichmentPrompt(members, community.heuristicLabel);
+      const response = await llmClient.generate(prompt);
+      
+      // Rough token estimate
+      tokensUsed += prompt.length / 4 + response.length / 4;
+      
+      const enrichment = parseEnrichmentResponse(response, community.heuristicLabel);
+      enrichments.set(community.id, enrichment);
+    } catch (error) {
+      // On error, fallback to heuristic
+      console.warn(`Failed to enrich cluster ${community.id}:`, error);
+      enrichments.set(community.id, {
+        name: community.heuristicLabel,
+        keywords: [],
+        description: '',
+      });
+    }
+  }
+  
+  return { enrichments, tokensUsed };
+};
+
+// ============================================================================
+// BATCH ENRICHMENT (more efficient)
+// ============================================================================
+
+/**
+ * Enrich multiple clusters in a single LLM call (batch mode)
+ * More efficient for token usage but requires larger context window
+ */
+export const enrichClustersBatch = async (
+  communities: CommunityNode[],
+  memberMap: Map<string, ClusterMemberInfo[]>,
+  llmClient: LLMClient,
+  batchSize: number = 5
+): Promise<EnrichmentResult> => {
+  const enrichments = new Map<string, ClusterEnrichment>();
+  let tokensUsed = 0;
+  
+  // Process in batches
+  for (let i = 0; i < communities.length; i += batchSize) {
+    const batch = communities.slice(i, i + batchSize);
+    
+    const batchPrompt = batch.map((community, idx) => {
+      const members = memberMap.get(community.id) || [];
+      const limitedMembers = members.slice(0, 15);
+      const memberList = limitedMembers
+        .map(m => `${m.name} (${m.type})`)
+        .join(', ');
+      
+      return `Cluster ${idx + 1} (id: ${community.id}):
+Heuristic: "${community.heuristicLabel}"
+Members: ${memberList}`;
+    }).join('\n\n');
+    
+    const prompt = `Analyze these code clusters and generate semantic names, keywords, and descriptions.
+
+${batchPrompt}
+
+Output JSON array:
+[
+  {"id": "comm_X", "name": "...", "keywords": [...], "description": "..."},
+  ...
+]`;
+    
+    try {
+      const response = await llmClient.generate(prompt);
+      tokensUsed += prompt.length / 4 + response.length / 4;
+      
+      // Parse batch response
+      const jsonMatch = response.match(/\[[\s\S]*\]/);
+      if (jsonMatch) {
+        const parsed = JSON.parse(jsonMatch[0]) as Array<{
+          id: string;
+          name: string;
+          keywords: string[];
+          description: string;
+        }>;
+        
+        for (const item of parsed) {
+          enrichments.set(item.id, {
+            name: item.name,
+            keywords: item.keywords || [],
+            description: item.description || '',
+          });
+        }
+      }
+    } catch (error) {
+      console.warn('Batch enrichment failed, falling back to heuristics:', error);
+      // Fallback for this batch
+      for (const community of batch) {
+        enrichments.set(community.id, {
+          name: community.heuristicLabel,
+          keywords: [],
+          description: '',
+        });
+      }
+    }
+  }
+  
+  // Fill in any missing communities
+  for (const community of communities) {
+    if (!enrichments.has(community.id)) {
+      enrichments.set(community.id, {
+        name: community.heuristicLabel,
+        keywords: [],
+        description: '',
+      });
+    }
+  }
+  
+  return { enrichments, tokensUsed };
+};
+```
+
+## core/ingestion/community-processor.ts
+
+```typescript
+/**
+ * Community Detection Processor
+ * 
+ * Uses the Leiden algorithm (via graphology-communities-louvain) to detect
+ * communities/clusters in the code graph based on CALLS relationships.
+ * 
+ * Communities represent groups of code that work together frequently,
+ * helping agents navigate the codebase by functional area rather than file structure.
+ */
+
+import Graph from 'graphology';
+import louvain from 'graphology-communities-louvain';
+import { KnowledgeGraph, NodeLabel } from '../graph/types';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface CommunityNode {
+  id: string;
+  label: string;
+  heuristicLabel: string;
+  cohesion: number;
+  symbolCount: number;
+}
+
+export interface CommunityMembership {
+  nodeId: string;
+  communityId: string;
+}
+
+export interface CommunityDetectionResult {
+  communities: CommunityNode[];
+  memberships: CommunityMembership[];
+  stats: {
+    totalCommunities: number;
+    modularity: number;
+    nodesProcessed: number;
+  };
+}
+
+// ============================================================================
+// COMMUNITY COLORS (for visualization)
+// ============================================================================
+
+export const COMMUNITY_COLORS = [
+  '#ef4444', // red
+  '#f97316', // orange
+  '#eab308', // yellow
+  '#22c55e', // green
+  '#06b6d4', // cyan
+  '#3b82f6', // blue
+  '#8b5cf6', // violet
+  '#d946ef', // fuchsia
+  '#ec4899', // pink
+  '#f43f5e', // rose
+  '#14b8a6', // teal
+  '#84cc16', // lime
+];
+
+export const getCommunityColor = (communityIndex: number): string => {
+  return COMMUNITY_COLORS[communityIndex % COMMUNITY_COLORS.length];
+};
+
+// ============================================================================
+// MAIN PROCESSOR
+// ============================================================================
+
+/**
+ * Detect communities in the knowledge graph using Leiden algorithm
+ * 
+ * This runs AFTER all relationships (CALLS, IMPORTS, etc.) have been built.
+ * It uses primarily CALLS edges to cluster code that works together.
+ */
+export const processCommunities = async (
+  knowledgeGraph: KnowledgeGraph,
+  onProgress?: (message: string, progress: number) => void
+): Promise<CommunityDetectionResult> => {
+  onProgress?.('Building graph for community detection...', 0);
+
+  // Step 1: Build a graphology graph from the knowledge graph
+  // We only include symbol nodes (Function, Class, Method) and CALLS edges
+  const graph = buildGraphologyGraph(knowledgeGraph);
+  
+  if (graph.order === 0) {
+    // No nodes to cluster
+    return {
+      communities: [],
+      memberships: [],
+      stats: { totalCommunities: 0, modularity: 0, nodesProcessed: 0 }
+    };
+  }
+
+  onProgress?.(`Running Leiden algorithm on ${graph.order} nodes...`, 30);
+
+  // Step 2: Run Leiden (via Louvain implementation with refinement)
+  const details = louvain.detailed(graph, {
+    resolution: 1.0,  // Default resolution, can be tuned
+    randomWalk: true,
+  });
+
+  onProgress?.(`Found ${details.count} communities...`, 60);
+
+  // Step 3: Create community nodes with heuristic labels
+  const communityNodes = createCommunityNodes(
+    details.communities as Record<string, number>,
+    details.count,
+    graph,
+    knowledgeGraph
+  );
+
+  onProgress?.('Creating membership edges...', 80);
+
+  // Step 4: Create membership mappings
+  const memberships: CommunityMembership[] = [];
+  Object.entries(details.communities).forEach(([nodeId, communityNum]) => {
+    memberships.push({
+      nodeId,
+      communityId: `comm_${communityNum}`,
+    });
+  });
+
+  onProgress?.('Community detection complete!', 100);
+
+  return {
+    communities: communityNodes,
+    memberships,
+    stats: {
+      totalCommunities: details.count,
+      modularity: details.modularity,
+      nodesProcessed: graph.order,
+    }
+  };
+};
+
+// ============================================================================
+// HELPER: Build graphology graph from knowledge graph
+// ============================================================================
+
+/**
+ * Build a graphology graph containing only symbol nodes and CALLS edges
+ * This is what the Leiden algorithm will cluster
+ */
+const buildGraphologyGraph = (knowledgeGraph: KnowledgeGraph): Graph => {
+  // Use undirected graph for Leiden - it looks at edge density, not direction
+  const graph = new Graph({ type: 'undirected', allowSelfLoops: false });
+
+  // Symbol types that should be clustered
+  const symbolTypes = new Set<NodeLabel>(['Function', 'Class', 'Method', 'Interface']);
+  
+  // Add symbol nodes
+  knowledgeGraph.nodes.forEach(node => {
+    if (symbolTypes.has(node.label)) {
+      graph.addNode(node.id, {
+        name: node.properties.name,
+        filePath: node.properties.filePath,
+        type: node.label,
+      });
+    }
+  });
+
+  // Add CALLS edges (primary clustering signal)
+  // We can also include EXTENDS/IMPLEMENTS for OOP clustering
+  const clusteringRelTypes = new Set(['CALLS', 'EXTENDS', 'IMPLEMENTS']);
+  
+  knowledgeGraph.relationships.forEach(rel => {
+    if (clusteringRelTypes.has(rel.type)) {
+      // Only add edge if both nodes exist in our symbol graph
+      // Also skip self-loops (recursive calls) - not allowed in undirected graph
+      if (graph.hasNode(rel.sourceId) && graph.hasNode(rel.targetId) && rel.sourceId !== rel.targetId) {
+        // Avoid duplicate edges
+        if (!graph.hasEdge(rel.sourceId, rel.targetId)) {
+          graph.addEdge(rel.sourceId, rel.targetId);
+        }
+      }
+    }
+  });
+
+  return graph;
+};
+
+// ============================================================================
+// HELPER: Create community nodes with heuristic labels
+// ============================================================================
+
+/**
+ * Create Community nodes with auto-generated labels based on member file paths
+ */
+const createCommunityNodes = (
+  communities: Record<string, number>,
+  communityCount: number,
+  graph: Graph,
+  knowledgeGraph: KnowledgeGraph
+): CommunityNode[] => {
+  // Group node IDs by community
+  const communityMembers = new Map<number, string[]>();
+  
+  Object.entries(communities).forEach(([nodeId, commNum]) => {
+    if (!communityMembers.has(commNum)) {
+      communityMembers.set(commNum, []);
+    }
+    communityMembers.get(commNum)!.push(nodeId);
+  });
+
+  // Build node lookup for file paths
+  const nodePathMap = new Map<string, string>();
+  knowledgeGraph.nodes.forEach(node => {
+    if (node.properties.filePath) {
+      nodePathMap.set(node.id, node.properties.filePath);
+    }
+  });
+
+  // Create community nodes - SKIP SINGLETONS (isolated nodes)
+  const communityNodes: CommunityNode[] = [];
+  
+  communityMembers.forEach((memberIds, commNum) => {
+    // Skip singleton communities - they're just isolated nodes
+    if (memberIds.length < 2) return;
+    
+    const heuristicLabel = generateHeuristicLabel(memberIds, nodePathMap, graph, commNum);
+    
+    communityNodes.push({
+      id: `comm_${commNum}`,
+      label: heuristicLabel,
+      heuristicLabel,
+      cohesion: calculateCohesion(memberIds, graph),
+      symbolCount: memberIds.length,
+    });
+  });
+
+  // Sort by size descending
+  communityNodes.sort((a, b) => b.symbolCount - a.symbolCount);
+
+  return communityNodes;
+};
+
+// ============================================================================
+// HELPER: Generate heuristic label from folder patterns
+// ============================================================================
+
+/**
+ * Generate a human-readable label from the most common folder name in the community
+ */
+const generateHeuristicLabel = (
+  memberIds: string[],
+  nodePathMap: Map<string, string>,
+  graph: Graph,
+  commNum: number
+): string => {
+  // Collect folder names from file paths
+  const folderCounts = new Map<string, number>();
+  
+  memberIds.forEach(nodeId => {
+    const filePath = nodePathMap.get(nodeId) || '';
+    const parts = filePath.split('/').filter(Boolean);
+    
+    // Get the most specific folder (parent directory)
+    if (parts.length >= 2) {
+      const folder = parts[parts.length - 2];
+      // Skip generic folder names
+      if (!['src', 'lib', 'core', 'utils', 'common', 'shared', 'helpers'].includes(folder.toLowerCase())) {
+        folderCounts.set(folder, (folderCounts.get(folder) || 0) + 1);
+      }
+    }
+  });
+
+  // Find most common folder
+  let maxCount = 0;
+  let bestFolder = '';
+  
+  folderCounts.forEach((count, folder) => {
+    if (count > maxCount) {
+      maxCount = count;
+      bestFolder = folder;
+    }
+  });
+
+  if (bestFolder) {
+    // Capitalize first letter
+    return bestFolder.charAt(0).toUpperCase() + bestFolder.slice(1);
+  }
+
+  // Fallback: use function names to detect patterns
+  const names: string[] = [];
+  memberIds.forEach(nodeId => {
+    const name = graph.getNodeAttribute(nodeId, 'name');
+    if (name) names.push(name);
+  });
+
+  // Look for common prefixes
+  if (names.length > 2) {
+    const commonPrefix = findCommonPrefix(names);
+    if (commonPrefix.length > 2) {
+      return commonPrefix.charAt(0).toUpperCase() + commonPrefix.slice(1);
+    }
+  }
+
+  // Last resort: generic name with community ID for uniqueness
+  return `Cluster_${commNum}`;
+};
+
+/**
+ * Find common prefix among strings
+ */
+const findCommonPrefix = (strings: string[]): string => {
+  if (strings.length === 0) return '';
+  
+  const sorted = strings.slice().sort();
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  
+  let i = 0;
+  while (i < first.length && first[i] === last[i]) {
+    i++;
+  }
+  
+  return first.substring(0, i);
+};
+
+// ============================================================================
+// HELPER: Calculate community cohesion
+// ============================================================================
+
+/**
+ * Calculate cohesion score (0-1) based on internal edge density
+ * Higher cohesion = more internal connections relative to size
+ */
+const calculateCohesion = (memberIds: string[], graph: Graph): number => {
+  if (memberIds.length <= 1) return 1.0;
+
+  const memberSet = new Set(memberIds);
+  let internalEdges = 0;
+  
+  // Count edges within the community
+  memberIds.forEach(nodeId => {
+    if (graph.hasNode(nodeId)) {
+      graph.forEachNeighbor(nodeId, neighbor => {
+        if (memberSet.has(neighbor)) {
+          internalEdges++;
+        }
+      });
+    }
+  });
+  
+  // Each edge is counted twice (once from each end), so divide by 2
+  internalEdges = internalEdges / 2;
+  
+  // Maximum possible internal edges for n nodes: n*(n-1)/2
+  const maxPossibleEdges = (memberIds.length * (memberIds.length - 1)) / 2;
+  
+  if (maxPossibleEdges === 0) return 1.0;
+  
+  return Math.min(1.0, internalEdges / maxPossibleEdges);
+};
+```
+
+## core/ingestion/heritage-processor.ts
+
+```typescript
+/**
+ * Heritage Processor
+ * 
+ * Extracts class inheritance relationships:
+ * - EXTENDS: Class extends another Class (TS, JS, Python)
+ * - IMPLEMENTS: Class implements an Interface (TS only)
+ */
+
+import { KnowledgeGraph } from '../graph/types';
+import { ASTCache } from './ast-cache';
+import { SymbolTable } from './symbol-table';
+import { loadParser, loadLanguage } from '../tree-sitter/parser-loader';
+import { LANGUAGE_QUERIES } from './tree-sitter-queries';
+import { generateId } from '../../lib/utils';
+import { getLanguageFromFilename } from './utils';
+
+export const processHeritage = async (
+  graph: KnowledgeGraph,
+  files: { path: string; content: string }[],
+  astCache: ASTCache,
+  symbolTable: SymbolTable,
+  onProgress?: (current: number, total: number) => void
+) => {
+  const parser = await loadParser();
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    onProgress?.(i + 1, files.length);
+
+    // 1. Check language support
+    const language = getLanguageFromFilename(file.path);
+    if (!language) continue;
+
+    const queryStr = LANGUAGE_QUERIES[language];
+    if (!queryStr) continue;
+
+    // 2. Load the language
+    await loadLanguage(language, file.path);
+
+    // 3. Get AST
+    let tree = astCache.get(file.path);
+    let wasReparsed = false;
+
+    if (!tree) {
+      tree = parser.parse(file.content);
+      wasReparsed = true;
+    }
+
+    let query;
+    let matches;
+    try {
+      query = parser.getLanguage().query(queryStr);
+      matches = query.matches(tree.rootNode);
+    } catch (queryError) {
+      console.warn(`Heritage query error for ${file.path}:`, queryError);
+      if (wasReparsed) tree.delete();
+      continue;
+    }
+
+    // 4. Process heritage matches
+    matches.forEach(match => {
+      const captureMap: Record<string, any> = {};
+      match.captures.forEach(c => {
+        captureMap[c.name] = c.node;
+      });
+
+      // EXTENDS: Class extends another Class
+      if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
+        const className = captureMap['heritage.class'].text;
+        const parentClassName = captureMap['heritage.extends'].text;
+
+        // Resolve both class IDs
+        const childId = symbolTable.lookupExact(file.path, className) ||
+                        symbolTable.lookupFuzzy(className)[0]?.nodeId ||
+                        generateId('Class', `${file.path}:${className}`);
+        
+        const parentId = symbolTable.lookupFuzzy(parentClassName)[0]?.nodeId ||
+                         generateId('Class', `${parentClassName}`);
+
+        if (childId && parentId && childId !== parentId) {
+          const relId = generateId('EXTENDS', `${childId}->${parentId}`);
+          
+          graph.addRelationship({
+            id: relId,
+            sourceId: childId,
+            targetId: parentId,
+            type: 'EXTENDS',
+            confidence: 1.0,
+            reason: '',
+          });
+        }
+      }
+
+      // IMPLEMENTS: Class implements Interface (TypeScript only)
+      if (captureMap['heritage.class'] && captureMap['heritage.implements']) {
+        const className = captureMap['heritage.class'].text;
+        const interfaceName = captureMap['heritage.implements'].text;
+
+        // Resolve class and interface IDs
+        const classId = symbolTable.lookupExact(file.path, className) ||
+                        symbolTable.lookupFuzzy(className)[0]?.nodeId ||
+                        generateId('Class', `${file.path}:${className}`);
+        
+        const interfaceId = symbolTable.lookupFuzzy(interfaceName)[0]?.nodeId ||
+                            generateId('Interface', `${interfaceName}`);
+
+        if (classId && interfaceId) {
+          const relId = generateId('IMPLEMENTS', `${classId}->${interfaceId}`);
+          
+          graph.addRelationship({
+            id: relId,
+            sourceId: classId,
+            targetId: interfaceId,
+            type: 'IMPLEMENTS',
+            confidence: 1.0,
+            reason: '',
+          });
+        }
+      }
+    });
+
+    // Cleanup
+    if (wasReparsed) {
+      tree.delete();
+    }
+  }
+};
+```
+
+## core/ingestion/import-processor.ts
+
+```typescript
+import { KnowledgeGraph } from '../graph/types';
+import { ASTCache } from './ast-cache';
+import { loadParser, loadLanguage } from '../tree-sitter/parser-loader';
+import { LANGUAGE_QUERIES } from './tree-sitter-queries';
+import { generateId } from '../../lib/utils';
+import { getLanguageFromFilename } from './utils';
+
+// Type: Map<FilePath, Set<ResolvedFilePath>>
+// Stores all files that a given file imports from
+export type ImportMap = Map<string, Set<string>>;
+
+export const createImportMap = (): ImportMap => new Map();
+
+// Helper: Resolve relative paths (e.g. "../utils" -> "src/lib/utils.ts")
+const resolveImportPath = (
+  currentFile: string, 
+  importPath: string, 
+  allFiles: Set<string>
+): string | null => {
+  // 1. Handle non-relative imports (libraries like 'react')
+  if (!importPath.startsWith('.')) return null; // We skip node_modules for now
+
+  // 2. Resolve '..' and '.'
+  const currentDir = currentFile.split('/').slice(0, -1);
+  const parts = importPath.split('/');
+  
+  for (const part of parts) {
+    if (part === '.') continue;
+    if (part === '..') {
+      currentDir.pop();
+    } else {
+      currentDir.push(part);
+    }
+  }
+  
+  const basePath = currentDir.join('/');
+
+  // 3. Try extensions (prioritize .tsx for React projects)
+  const extensions = ['', '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js'];
+  
+  for (const ext of extensions) {
+    const candidate = basePath + ext;
+    if (allFiles.has(candidate)) return candidate;
+  }
+
+  return null;
+};
+
+export const processImports = async (
+  graph: KnowledgeGraph,
+  files: { path: string; content: string }[],
+  astCache: ASTCache,
+  importMap: ImportMap,
+  onProgress?: (current: number, total: number) => void
+) => {
+  // Create a Set of all file paths for fast lookup during resolution
+  const allFilePaths = new Set(files.map(f => f.path));
+  const parser = await loadParser();
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    onProgress?.(i + 1, files.length);
+
+    // 1. Check language support first
+    const language = getLanguageFromFilename(file.path);
+    if (!language) continue;
+    
+    const queryStr = LANGUAGE_QUERIES[language];
+    if (!queryStr) continue;
+
+    // 2. ALWAYS load the language before querying (parser is stateful)
+    await loadLanguage(language, file.path);
+
+    // 3. Get AST (Try Cache First)
+    let tree = astCache.get(file.path);
+    let wasReparsed = false;
+    
+    if (!tree) {
+      // Cache Miss: Re-parse (slower, but necessary if evicted)
+      tree = parser.parse(file.content);
+      wasReparsed = true;
+    }
+
+    let query;
+    let matches;
+    try {
+      query = parser.getLanguage().query(queryStr);
+      matches = query.matches(tree.rootNode);
+    } catch (queryError: any) {
+      // Detailed debug logging for query failures
+      console.group(`🔴 Query Error: ${file.path}`);
+      console.log('Language:', language);
+      console.log('Query (first 200 chars):', queryStr.substring(0, 200) + '...');
+      console.log('Error:', queryError?.message || queryError);
+      console.log('File content (first 300 chars):', file.content.substring(0, 300));
+      console.log('AST root type:', tree.rootNode?.type);
+      console.log('AST has errors:', tree.rootNode?.hasError);
+      console.groupEnd();
+      
+      if (wasReparsed) tree.delete();
+      continue;
+    }
+
+    matches.forEach(match => {
+      const captureMap: Record<string, any> = {};
+      match.captures.forEach(c => captureMap[c.name] = c.node);
+
+      if (captureMap['import']) {
+        const sourceNode = captureMap['import.source'];
+        if (!sourceNode) return;
+
+        // Clean path (remove quotes)
+        const rawImportPath = sourceNode.text.replace(/['"]/g, '');
+        
+        // Resolve to actual file in the system
+        const resolvedPath = resolveImportPath(file.path, rawImportPath, allFilePaths);
+
+        if (resolvedPath) {
+          // A. Update Graph (File -> IMPORTS -> File)
+          const sourceId = generateId('File', file.path);
+          const targetId = generateId('File', resolvedPath);
+          const relId = generateId('IMPORTS', `${file.path}->${resolvedPath}`);
+
+          graph.addRelationship({
+            id: relId,
+            sourceId,
+            targetId,
+            type: 'IMPORTS',
+            confidence: 1.0,
+            reason: '',
+          });
+
+          // B. Update Import Map (For Pass 4)
+          // Store all resolved import paths for this file
+          if (!importMap.has(file.path)) {
+            importMap.set(file.path, new Set());
+          }
+          importMap.get(file.path)!.add(resolvedPath);
+        }
+      }
+    });
+
+    // If re-parsed just for this, delete the tree to save memory
+    if (wasReparsed) {
+      tree.delete();
+    }
+  }
+};
+```
+
+## core/ingestion/parsing-processor.ts
+
+```typescript
+import { KnowledgeGraph, GraphNode, GraphRelationship } from '../graph/types';
+import { loadParser, loadLanguage } from '../tree-sitter/parser-loader';
+import { LANGUAGE_QUERIES } from './tree-sitter-queries';
+import { generateId } from '../../lib/utils';
+import { SymbolTable } from './symbol-table';
+import { ASTCache } from './ast-cache';
+import { getLanguageFromFilename } from './utils';
+
+export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
+
+export const processParsing = async (
+  graph: KnowledgeGraph, 
+  files: { path: string; content: string }[],
+  symbolTable: SymbolTable,
+  astCache: ASTCache,
+  onFileProgress?: FileProgressCallback
+) => {
+ 
+  const parser = await loadParser();
+  const total = files.length;
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    
+    // Report progress for each file
+    onFileProgress?.(i + 1, total, file.path);
+    
+    const language = getLanguageFromFilename(file.path);
+
+    if (!language) continue;
+
+    await loadLanguage(language, file.path);
+    
+    // 3. Parse the text content into an AST
+    const tree = parser.parse(file.content);
+    
+    // Store in cache immediately (this might evict an old one)
+    astCache.set(file.path, tree);
+    
+    // 4. Get the specific query string for this language
+    const queryString = LANGUAGE_QUERIES[language];
+    if (!queryString) {
+      continue;
+    }
+
+    // 5. Run the query against the AST root node
+    // This looks for patterns like (function_declaration)
+    let query;
+    let matches;
+    try {
+      query = parser.getLanguage().query(queryString);
+      matches = query.matches(tree.rootNode);
+    } catch (queryError) {
+      console.warn(`Query error for ${file.path}:`, queryError);
+      continue;
+    }
+
+    // 6. Process every match found
+    matches.forEach(match => {
+      const captureMap: Record<string, any> = {};
+      
+      match.captures.forEach(c => {
+        captureMap[c.name] = c.node;
+      });
+
+      // Skip imports here - they are handled by import-processor.ts
+      // which creates proper File -> IMPORTS -> File relationships
+      if (captureMap['import']) {
+        return;
+      }
+
+      // Skip call expressions - they are handled by call-processor.ts
+      if (captureMap['call']) {
+        return;
+      }
+
+      const nameNode = captureMap['name'];
+      if (!nameNode) return;
+
+      const nodeName = nameNode.text;
+      
+      let nodeLabel = 'CodeElement';
+      
+      if (captureMap['definition.function']) nodeLabel = 'Function';
+      else if (captureMap['definition.class']) nodeLabel = 'Class';
+      else if (captureMap['definition.interface']) nodeLabel = 'Interface';
+      else if (captureMap['definition.method']) nodeLabel = 'Method';
+
+      const nodeId = generateId(nodeLabel, `${file.path}:${nodeName}`);
+      
+      const node: GraphNode = {
+        id: nodeId,
+        label: nodeLabel as any,
+        properties: {
+          name: nodeName,
+          filePath: file.path,
+          startLine: nameNode.startPosition.row,
+          endLine: nameNode.endPosition.row,
+          language: language
+        }
+      };
+
+      graph.addNode(node);
+
+      // Register in Symbol Table (only definitions, not imports)
+      symbolTable.add(file.path, nodeName, nodeId, nodeLabel);
+
+      const fileId = generateId('File', file.path);
+      
+      const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
+      
+      const relationship: GraphRelationship = {
+        id: relId,
+        sourceId: fileId,
+        targetId: nodeId,
+        type: 'DEFINES',
+        confidence: 1.0,
+        reason: '',
+      };
+
+      graph.addRelationship(relationship);
+    });
+    
+    // Don't delete tree here - LRU cache handles cleanup when evicted
+  }
+};
+```
+
+## core/ingestion/pipeline.ts
+
+```typescript
+import { createKnowledgeGraph } from '../graph/graph';
+import { extractZip, FileEntry } from '../../services/zip';
+import { processStructure } from './structure-processor';
+import { processParsing } from './parsing-processor';
+import { processImports, createImportMap } from './import-processor';
+import { processCalls } from './call-processor';
+import { processHeritage } from './heritage-processor';
+import { processCommunities, CommunityDetectionResult } from './community-processor';
+import { createSymbolTable } from './symbol-table';
+import { createASTCache } from './ast-cache';
+import { PipelineProgress, PipelineResult } from '../../types/pipeline';
+
+/**
+ * Run the ingestion pipeline from a ZIP file
+ */
+export const runIngestionPipeline = async ( file: File, onProgress: (progress: PipelineProgress) => void): Promise<PipelineResult> => {
+  // Phase 1: Extracting (0-15%)
+  onProgress({
+    phase: 'extracting',
+    percent: 0,
+    message: 'Extracting ZIP file...',
+  });
+  
+  // Fake progress for extraction (JSZip doesn't expose progress)
+  const fakeExtractionProgress = setInterval(() => {
+    onProgress({
+      phase: 'extracting',
+      percent: Math.min(14, Math.random() * 10 + 5),
+      message: 'Extracting ZIP file...',
+    });
+  }, 200);
+  
+  const files = await extractZip(file);
+  clearInterval(fakeExtractionProgress);
+  
+  // Continue with common pipeline
+  return runPipelineFromFiles(files, onProgress);
+};
+
+/**
+ * Run the ingestion pipeline from pre-extracted files (e.g., from git clone)
+ */
+export const runPipelineFromFiles = async (
+  files: FileEntry[],
+  onProgress: (progress: PipelineProgress) => void
+): Promise<PipelineResult> => {
+  const graph = createKnowledgeGraph();
+  const fileContents = new Map<string, string>();
+  const symbolTable = createSymbolTable();
+  const astCache = createASTCache(50); // Keep last 50 files hot
+  const importMap = createImportMap();
+
+  // Cleanup function for error handling
+  const cleanup = () => {
+    astCache.clear();
+    symbolTable.clear();
+  };
+  
+  try {
+  // Store file contents for code panel
+  files.forEach(f => fileContents.set(f.path, f.content));
+  
+  onProgress({
+    phase: 'extracting',
+    percent: 15,
+    message: 'ZIP extracted successfully',
+    stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: 0 },
+  });
+  
+  // Phase 2: Structure (15-30%)
+  onProgress({
+    phase: 'structure',
+    percent: 15,
+    message: 'Analyzing project structure...',
+    stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: 0 },
+  });
+  
+  const filePaths = files.map(f => f.path);
+  processStructure(graph, filePaths);
+  
+  onProgress({
+    phase: 'structure',
+    percent: 30,
+    message: 'Project structure analyzed',
+    stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+  
+  // Phase 3: Parsing (30-70%)
+  onProgress({
+    phase: 'parsing',
+    percent: 30,
+    message: 'Parsing code definitions...',
+    stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+  
+  await processParsing(graph, files, symbolTable, astCache, (current, total, filePath) => {
+    const parsingProgress = 30 + ((current / total) * 40);
+    onProgress({
+      phase: 'parsing',
+      percent: Math.round(parsingProgress),
+      message: 'Parsing code definitions...',
+      detail: filePath,
+      stats: { filesProcessed: current, totalFiles: total, nodesCreated: graph.nodeCount },
+    });
+  });
+
+
+  // Phase 4: Imports (70-82%)
+  onProgress({
+    phase: 'imports',
+    percent: 70,
+    message: 'Resolving imports...',
+    stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+
+  await processImports(graph, files, astCache, importMap, (current, total) => {
+    const importProgress = 70 + ((current / total) * 12);
+    onProgress({
+      phase: 'imports',
+      percent: Math.round(importProgress),
+      message: 'Resolving imports...',
+      stats: { filesProcessed: current, totalFiles: total, nodesCreated: graph.nodeCount },
+    });
+  });
+
+
+  // Phase 5: Calls (82-98%)
+  onProgress({
+    phase: 'calls',
+    percent: 82,
+    message: 'Tracing function calls...',
+    stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+
+  await processCalls(graph, files, astCache, symbolTable, importMap, (current, total) => {
+    const callProgress = 82 + ((current / total) * 10);
+    onProgress({
+      phase: 'calls',
+      percent: Math.round(callProgress),
+      message: 'Tracing function calls...',
+      stats: { filesProcessed: current, totalFiles: total, nodesCreated: graph.nodeCount },
+    });
+  });
+
+  // Phase 6: Heritage - Class inheritance (92-98%)
+  onProgress({
+    phase: 'heritage',
+    percent: 92,
+    message: 'Extracting class inheritance...',
+    stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+
+  await processHeritage(graph, files, astCache, symbolTable, (current, total) => {
+    const heritageProgress = 88 + ((current / total) * 4);
+    onProgress({
+      phase: 'heritage',
+      percent: Math.round(heritageProgress),
+      message: 'Extracting class inheritance...',
+      stats: { filesProcessed: current, totalFiles: total, nodesCreated: graph.nodeCount },
+    });
+  });
+
+  // Phase 7: Community Detection (92-98%)
+  onProgress({
+    phase: 'communities',
+    percent: 92,
+    message: 'Detecting code communities...',
+    stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
+  });
+
+  const communityResult = await processCommunities(graph, (message, progress) => {
+    const communityProgress = 92 + (progress * 0.06);
+    onProgress({
+      phase: 'communities',
+      percent: Math.round(communityProgress),
+      message,
+      stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
+    });
+  });
+
+  // Log community detection results
+  if (import.meta.env.DEV) {
+    console.log(`🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`);
+  }
+
+  // Add community nodes to the graph
+  communityResult.communities.forEach(comm => {
+    graph.addNode({
+      id: comm.id,
+      label: 'Community' as const,
+      properties: {
+        name: comm.label,
+        filePath: '',
+        heuristicLabel: comm.heuristicLabel,
+        cohesion: comm.cohesion,
+        symbolCount: comm.symbolCount,
+      }
+    });
+  });
+
+  // Add MEMBER_OF relationships
+  communityResult.memberships.forEach(membership => {
+    graph.addRelationship({
+      id: `${membership.nodeId}_member_of_${membership.communityId}`,
+      type: 'MEMBER_OF',
+      sourceId: membership.nodeId,
+      targetId: membership.communityId,
+      confidence: 1.0,
+      reason: 'leiden-algorithm',
+    });
+  });
+
+  
+  // Phase 8: Complete (100%)
+  onProgress({
+    phase: 'complete',
+    percent: 100,
+    message: `Graph complete! ${communityResult.stats.totalCommunities} communities detected.`,
+    stats: { 
+      filesProcessed: files.length, 
+      totalFiles: files.length, 
+      nodesCreated: graph.nodeCount 
+    },
+  });
+
+  // Cleanup WASM memory before returning
+  astCache.clear();
+  
+  return { graph, fileContents, communityResult };
+
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+};
+```
+
+## core/ingestion/structure-processor.ts
+
+```typescript
+import { generateId } from "@/lib/utils";
+import { KnowledgeGraph, GraphNode, GraphRelationship } from "../graph/types";
+
+export const processStructure = ( graph: KnowledgeGraph, paths: string[])=>{
+    paths.forEach( path => {
+        const parts = path.split('/')
+        let currentPath = ''
+        let parentId = ''
+
+        parts.forEach( (part, index ) => {
+            const isFile = index === parts.length - 1
+            const label = isFile ? 'File' : 'Folder' 
+
+            currentPath = currentPath ? `${currentPath}/${part}` : part
+
+            const nodeId=generateId(label, currentPath)
+
+            const node: GraphNode = {
+                id: nodeId,
+                label: label,
+                properties: {
+                    name: part,
+                    filePath: currentPath
+                }
+            }
+            graph.addNode(node)
+
+            if(parentId){
+                const relId = generateId('CONTAINS', `${parentId}->${nodeId}`)
+
+                const relationship: GraphRelationship={
+                    id: relId,
+                    type: 'CONTAINS',
+                    sourceId: parentId,
+                    targetId: nodeId,
+                    confidence: 1.0,
+                    reason: '',
+                }
+
+                graph.addRelationship(relationship)
+            }
+
+            parentId = nodeId
+
+        })
+    })
+}
+```
+
+## core/ingestion/symbol-table.ts
+
+```typescript
+export interface SymbolDefinition {
+  nodeId: string;
+  filePath: string;
+  type: string; // 'Function', 'Class', etc.
+}
+
+export interface SymbolTable {
+  /**
+   * Register a new symbol definition
+   */
+  add: (filePath: string, name: string, nodeId: string, type: string) => void;
+  
+  /**
+   * High Confidence: Look for a symbol specifically inside a file
+   * Returns the Node ID if found
+   */
+  lookupExact: (filePath: string, name: string) => string | undefined;
+  
+  /**
+   * Low Confidence: Look for a symbol anywhere in the project
+   * Used when imports are missing or for framework magic
+   */
+  lookupFuzzy: (name: string) => SymbolDefinition[];
+  
+  /**
+   * Debugging: See how many symbols are tracked
+   */
+  getStats: () => { fileCount: number; globalSymbolCount: number };
+  
+  /**
+   * Cleanup memory
+   */
+  clear: () => void;
+}
+
+export const createSymbolTable = (): SymbolTable => {
+  // 1. File-Specific Index (The "Good" one)
+  // Structure: FilePath -> (SymbolName -> NodeID)
+  const fileIndex = new Map<string, Map<string, string>>();
+
+  // 2. Global Reverse Index (The "Backup")
+  // Structure: SymbolName -> [List of Definitions]
+  const globalIndex = new Map<string, SymbolDefinition[]>();
+
+  const add = (filePath: string, name: string, nodeId: string, type: string) => {
+    // A. Add to File Index
+    if (!fileIndex.has(filePath)) {
+      fileIndex.set(filePath, new Map());
+    }
+    fileIndex.get(filePath)!.set(name, nodeId);
+
+    // B. Add to Global Index
+    if (!globalIndex.has(name)) {
+      globalIndex.set(name, []);
+    }
+    globalIndex.get(name)!.push({ nodeId, filePath, type });
+  };
+
+  const lookupExact = (filePath: string, name: string): string | undefined => {
+    const fileSymbols = fileIndex.get(filePath);
+    if (!fileSymbols) return undefined;
+    return fileSymbols.get(name);
+  };
+
+  const lookupFuzzy = (name: string): SymbolDefinition[] => {
+    return globalIndex.get(name) || [];
+  };
+
+  const getStats = () => ({
+    fileCount: fileIndex.size,
+    globalSymbolCount: globalIndex.size
+  });
+
+  const clear = () => {
+    fileIndex.clear();
+    globalIndex.clear();
+  };
+
+  return { add, lookupExact, lookupFuzzy, getStats, clear };
+};
+```
+
+## core/ingestion/tree-sitter-queries.ts
+
+```typescript
+import { SupportedLanguages } from '../../config/supported-languages';
+
+/* 
+ * Tree-sitter queries for extracting code definitions.
+ * 
+ * Note: Different grammars (typescript vs tsx vs javascript) may have
+ * slightly different node types. These queries are designed to be 
+ * compatible with the standard tree-sitter grammars.
+ */
+
+// TypeScript queries - works with tree-sitter-typescript
+export const TYPESCRIPT_QUERIES = `
+(class_declaration
+  name: (type_identifier) @name) @definition.class
+
+(interface_declaration
+  name: (type_identifier) @name) @definition.interface
+
+(function_declaration
+  name: (identifier) @name) @definition.function
+
+(method_definition
+  name: (property_identifier) @name) @definition.method
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name
+    value: (arrow_function))) @definition.function
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name
+    value: (function_expression))) @definition.function
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: (arrow_function)))) @definition.function
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: (function_expression)))) @definition.function
+
+(import_statement
+  source: (string) @import.source) @import
+
+(call_expression
+  function: (identifier) @call.name) @call
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @call.name)) @call
+
+; Heritage queries - class extends
+(class_declaration
+  name: (type_identifier) @heritage.class
+  (class_heritage
+    (extends_clause
+      value: (identifier) @heritage.extends))) @heritage
+
+; Heritage queries - class implements interface
+(class_declaration
+  name: (type_identifier) @heritage.class
+  (class_heritage
+    (implements_clause
+      (type_identifier) @heritage.implements))) @heritage.impl
+`;
+
+// JavaScript queries - works with tree-sitter-javascript  
+export const JAVASCRIPT_QUERIES = `
+(class_declaration
+  name: (identifier) @name) @definition.class
+
+(function_declaration
+  name: (identifier) @name) @definition.function
+
+(method_definition
+  name: (property_identifier) @name) @definition.method
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name
+    value: (arrow_function))) @definition.function
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name
+    value: (function_expression))) @definition.function
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: (arrow_function)))) @definition.function
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: (function_expression)))) @definition.function
+
+(import_statement
+  source: (string) @import.source) @import
+
+(call_expression
+  function: (identifier) @call.name) @call
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @call.name)) @call
+
+; Heritage queries - class extends (JavaScript uses different AST than TypeScript)
+; In tree-sitter-javascript, class_heritage directly contains the parent identifier
+(class_declaration
+  name: (identifier) @heritage.class
+  (class_heritage
+    (identifier) @heritage.extends)) @heritage
+`;
+
+// Python queries - works with tree-sitter-python
+export const PYTHON_QUERIES = `
+(class_definition
+  name: (identifier) @name) @definition.class
+
+(function_definition
+  name: (identifier) @name) @definition.function
+
+(import_statement
+  name: (dotted_name) @import.source) @import
+
+(import_from_statement
+  module_name: (dotted_name) @import.source) @import
+
+(call
+  function: (identifier) @call.name) @call
+
+(call
+  function: (attribute
+    attribute: (identifier) @call.name)) @call
+
+; Heritage queries - Python class inheritance
+(class_definition
+  name: (identifier) @heritage.class
+  superclasses: (argument_list
+    (identifier) @heritage.extends)) @heritage
+`;
+
+export const LANGUAGE_QUERIES: Record<SupportedLanguages, string> = {
+  [SupportedLanguages.TypeScript]: TYPESCRIPT_QUERIES,
+  [SupportedLanguages.JavaScript]: JAVASCRIPT_QUERIES,
+  [SupportedLanguages.Python]: PYTHON_QUERIES,
+};
+```
+
+## core/ingestion/utils.ts
+
+```typescript
+import { SupportedLanguages } from '../../config/supported-languages';
+
+/**
+ * Map file extension to SupportedLanguage enum
+ */
+export const getLanguageFromFilename = (filename: string): SupportedLanguages | null => {
+  if (filename.endsWith('.tsx')) return SupportedLanguages.TypeScript;
+  if (filename.endsWith('.ts')) return SupportedLanguages.TypeScript;
+  if (filename.endsWith('.jsx')) return SupportedLanguages.JavaScript;
+  if (filename.endsWith('.js')) return SupportedLanguages.JavaScript;
+  if (filename.endsWith('.py')) return SupportedLanguages.Python;
+  return null;
+};
+```
+
+## core/kuzu/csv-generator.ts
+
+```typescript
+/**
+ * CSV Generator for KuzuDB Hybrid Schema
+ * 
+ * Generates separate CSV files for each node table and one relation CSV.
+ * This enables efficient bulk loading via COPY FROM for hybrid schema.
+ * 
+ * RFC 4180 Compliant:
+ * - Fields containing commas, double quotes, or newlines are enclosed in double quotes
+ * - Double quotes within fields are escaped by doubling them ("")
+ * - All fields are consistently quoted for safety with code content
+ */
+
+import { KnowledgeGraph, GraphNode, NodeLabel } from '../graph/types';
+import { NODE_TABLES, NodeTableName } from './schema';
+
+// ============================================================================
+// CSV ESCAPE UTILITIES
+// ============================================================================
+
+/**
+ * Sanitize string to ensure valid UTF-8
+ * Removes or replaces invalid characters that would break CSV parsing
+ */
+const sanitizeUTF8 = (str: string): string => {
+  return str
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '') // Remove control chars except \t \n \r
+    .replace(/[\uD800-\uDFFF]/g, '') // Remove surrogate pairs (invalid standalone)
+    .replace(/[\uFFFE\uFFFF]/g, ''); // Remove BOM and special chars
+};
+
+/**
+ * RFC 4180 compliant CSV field escaping
+ * ALWAYS wraps in double quotes for safety with code content
+ */
+const escapeCSVField = (value: string | number | undefined | null): string => {
+  if (value === undefined || value === null) {
+    return '""';
+  }
+  let str = String(value);
+  str = sanitizeUTF8(str);
+  return `"${str.replace(/"/g, '""')}"`;
+};
+
+/**
+ * Escape a numeric value (no quotes needed for numbers)
+ */
+const escapeCSVNumber = (value: number | undefined | null, defaultValue: number = -1): string => {
+  if (value === undefined || value === null) {
+    return String(defaultValue);
+  }
+  return String(value);
+};
+
+// ============================================================================
+// CONTENT EXTRACTION
+// ============================================================================
+
+/**
+ * Check if content looks like binary data
+ */
+const isBinaryContent = (content: string): boolean => {
+  if (!content || content.length === 0) return false;
+  const sample = content.slice(0, 1000);
+  let nonPrintable = 0;
+  for (let i = 0; i < sample.length; i++) {
+    const code = sample.charCodeAt(i);
+    if ((code < 9) || (code > 13 && code < 32) || code === 127) {
+      nonPrintable++;
+    }
+  }
+  return (nonPrintable / sample.length) > 0.1;
+};
+
+/**
+ * Extract code content for a node
+ */
+const extractContent = (
+  node: GraphNode,
+  fileContents: Map<string, string>
+): string => {
+  const filePath = node.properties.filePath;
+  const content = fileContents.get(filePath);
+  
+  if (!content) return '';
+  if (node.label === 'Folder') return '';
+  if (isBinaryContent(content)) return '[Binary file - content not stored]';
+  
+  // For File nodes, return content (limited)
+  if (node.label === 'File') {
+    const MAX_FILE_CONTENT = 10000;
+    if (content.length > MAX_FILE_CONTENT) {
+      return content.slice(0, MAX_FILE_CONTENT) + '\n... [truncated]';
+    }
+    return content;
+  }
+  
+  // For code elements, extract the relevant lines with context
+  const startLine = node.properties.startLine;
+  const endLine = node.properties.endLine;
+  
+  if (startLine === undefined || endLine === undefined) return '';
+  
+  const lines = content.split('\n');
+  const contextLines = 2;
+  const start = Math.max(0, startLine - contextLines);
+  const end = Math.min(lines.length - 1, endLine + contextLines);
+  
+  const snippet = lines.slice(start, end + 1).join('\n');
+  const MAX_SNIPPET = 5000;
+  if (snippet.length > MAX_SNIPPET) {
+    return snippet.slice(0, MAX_SNIPPET) + '\n... [truncated]';
+  }
+  return snippet;
+};
+
+// ============================================================================
+// CSV GENERATION RESULT TYPE
+// ============================================================================
+
+export interface CSVData {
+  nodes: Map<NodeTableName, string>;
+  relCSV: string;  // Single relation CSV with from,to,type,confidence,reason columns
+}
+
+// ============================================================================
+// NODE CSV GENERATORS
+// ============================================================================
+
+/**
+ * Generate CSV for File nodes
+ * Headers: id,name,filePath,content
+ */
+const generateFileCSV = (nodes: GraphNode[], fileContents: Map<string, string>): string => {
+  const headers = ['id', 'name', 'filePath', 'content'];
+  const rows: string[] = [headers.join(',')];
+  
+  for (const node of nodes) {
+    if (node.label !== 'File') continue;
+    const content = extractContent(node, fileContents);
+    rows.push([
+      escapeCSVField(node.id),
+      escapeCSVField(node.properties.name || ''),
+      escapeCSVField(node.properties.filePath || ''),
+      escapeCSVField(content),
+    ].join(','));
+  }
+  
+  return rows.join('\n');
+};
+
+/**
+ * Generate CSV for Folder nodes
+ * Headers: id,name,filePath
+ */
+const generateFolderCSV = (nodes: GraphNode[]): string => {
+  const headers = ['id', 'name', 'filePath'];
+  const rows: string[] = [headers.join(',')];
+  
+  for (const node of nodes) {
+    if (node.label !== 'Folder') continue;
+    rows.push([
+      escapeCSVField(node.id),
+      escapeCSVField(node.properties.name || ''),
+      escapeCSVField(node.properties.filePath || ''),
+    ].join(','));
+  }
+  
+  return rows.join('\n');
+};
+
+/**
+ * Generate CSV for code element nodes (Function, Class, Interface, Method, CodeElement)
+ * Headers: id,name,filePath,startLine,endLine,content
+ */
+const generateCodeElementCSV = (
+  nodes: GraphNode[],
+  label: NodeLabel,
+  fileContents: Map<string, string>
+): string => {
+  const headers = ['id', 'name', 'filePath', 'startLine', 'endLine', 'content'];
+  const rows: string[] = [headers.join(',')];
+  
+  for (const node of nodes) {
+    if (node.label !== label) continue;
+    const content = extractContent(node, fileContents);
+    rows.push([
+      escapeCSVField(node.id),
+      escapeCSVField(node.properties.name || ''),
+      escapeCSVField(node.properties.filePath || ''),
+      escapeCSVNumber(node.properties.startLine, -1),
+      escapeCSVNumber(node.properties.endLine, -1),
+      escapeCSVField(content),
+    ].join(','));
+  }
+  
+  return rows.join('\n');
+};
+
+/**
+ * Generate CSV for Community nodes (from Leiden algorithm)
+ * Headers: id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount
+ */
+const generateCommunityCSV = (nodes: GraphNode[]): string => {
+  const headers = ['id', 'label', 'heuristicLabel', 'keywords', 'description', 'enrichedBy', 'cohesion', 'symbolCount'];
+  const rows: string[] = [headers.join(',')];
+  
+  for (const node of nodes) {
+    if (node.label !== 'Community') continue;
+    
+    // Handle keywords array - convert to KuzuDB array format
+    const keywords = (node.properties as any).keywords || [];
+    const keywordsStr = `[${keywords.map((k: string) => `'${k.replace(/'/g, "''")}'`).join(',')}]`;
+    
+    rows.push([
+      escapeCSVField(node.id),
+      escapeCSVField(node.properties.name || ''),  // label is stored in name
+      escapeCSVField(node.properties.heuristicLabel || ''),
+      keywordsStr,  // Array format for KuzuDB
+      escapeCSVField((node.properties as any).description || ''),
+      escapeCSVField((node.properties as any).enrichedBy || 'heuristic'),
+      escapeCSVNumber(node.properties.cohesion, 0),
+      escapeCSVNumber(node.properties.symbolCount, 0),
+    ].join(','));
+  }
+  
+  return rows.join('\n');
+};
+
+// ============================================================================
+// RELATIONSHIP CSV GENERATOR (Single Table)
+// ============================================================================
+
+/**
+ * Generate CSV for the single CodeRelation table
+ * Headers: from,to,type,confidence,reason
+ * 
+ * confidence: 0-1 score for CALLS edges (how sure are we about the target?)
+ * reason: 'import-resolved' | 'same-file' | 'fuzzy-global' (or empty for non-CALLS)
+ */
+const generateRelationCSV = (graph: KnowledgeGraph): string => {
+  const headers = ['from', 'to', 'type', 'confidence', 'reason'];
+  const rows: string[] = [headers.join(',')];
+  
+  for (const rel of graph.relationships) {
+    rows.push([
+      escapeCSVField(rel.sourceId),
+      escapeCSVField(rel.targetId),
+      escapeCSVField(rel.type),
+      escapeCSVNumber(rel.confidence, 1.0),
+      escapeCSVField(rel.reason),
+    ].join(','));
+  }
+  
+  return rows.join('\n');
+};
+
+// ============================================================================
+// MAIN CSV GENERATION FUNCTION
+// ============================================================================
+
+/**
+ * Generate all CSV data for hybrid schema bulk loading
+ * Returns Maps of node table name -> CSV content, and single relation CSV
+ */
+export const generateAllCSVs = (
+  graph: KnowledgeGraph,
+  fileContents: Map<string, string>
+): CSVData => {
+  const nodes = Array.from(graph.nodes);
+  
+  // Generate node CSVs
+  const nodeCSVs = new Map<NodeTableName, string>();
+  nodeCSVs.set('File', generateFileCSV(nodes, fileContents));
+  nodeCSVs.set('Folder', generateFolderCSV(nodes));
+  nodeCSVs.set('Function', generateCodeElementCSV(nodes, 'Function', fileContents));
+  nodeCSVs.set('Class', generateCodeElementCSV(nodes, 'Class', fileContents));
+  nodeCSVs.set('Interface', generateCodeElementCSV(nodes, 'Interface', fileContents));
+  nodeCSVs.set('Method', generateCodeElementCSV(nodes, 'Method', fileContents));
+  nodeCSVs.set('CodeElement', generateCodeElementCSV(nodes, 'CodeElement', fileContents));
+  nodeCSVs.set('Community', generateCommunityCSV(nodes));
+  
+  // Generate single relation CSV
+  const relCSV = generateRelationCSV(graph);
+  
+  return { nodes: nodeCSVs, relCSV };
+};
+```
+
+## core/kuzu/kuzu-adapter.ts
+
+```typescript
+/**
+ * KuzuDB Adapter
+ * 
+ * Manages the KuzuDB WASM instance for client-side graph database operations.
+ * Uses the "Snapshot / Bulk Load" pattern with COPY FROM for performance.
+ * 
+ * Multi-table schema: separate tables for File, Function, Class, etc.
+ */
+
+import { KnowledgeGraph } from '../graph/types';
+import { 
+  NODE_TABLES, 
+  REL_TABLE_NAME,
+  SCHEMA_QUERIES, 
+  EMBEDDING_TABLE_NAME,
+  NodeTableName,
+} from './schema';
+import { generateAllCSVs } from './csv-generator';
+
+// Holds the reference to the dynamically loaded module
+let kuzu: any = null;
+let db: any = null;
+let conn: any = null;
+
+/**
+ * Initialize KuzuDB WASM module and create in-memory database
+ */
+export const initKuzu = async () => {
+  if (conn) return { db, conn, kuzu };
+
+  try {
+    if (import.meta.env.DEV) console.log('🚀 Initializing KuzuDB...');
+
+    // 1. Dynamic Import (Fixes the "not a function" bundler issue)
+    const kuzuModule = await import('kuzu-wasm');
+    
+    // 2. Handle Vite/Webpack "default" wrapping
+    kuzu = kuzuModule.default || kuzuModule;
+
+    // 3. Initialize WASM
+    await kuzu.init();
+    
+    // 4. Create Database with 512MB buffer pool
+    const BUFFER_POOL_SIZE = 512 * 1024 * 1024; // 512MB
+    db = new kuzu.Database(':memory:', BUFFER_POOL_SIZE);
+    conn = new kuzu.Connection(db);
+    
+    if (import.meta.env.DEV) console.log('✅ KuzuDB WASM Initialized');
+
+    // 5. Initialize Schema (all node tables, then rel tables, then embedding table)
+    for (const schemaQuery of SCHEMA_QUERIES) {
+      try {
+        await conn.query(schemaQuery);
+      } catch (e) {
+        // Schema might already exist, skip
+        if (import.meta.env.DEV) {
+          console.warn('Schema creation skipped (may already exist):', e);
+        }
+      }
+    }
+    
+    if (import.meta.env.DEV) console.log('✅ KuzuDB Multi-Table Schema Created');
+
+    return { db, conn, kuzu };
+  } catch (error) {
+    if (import.meta.env.DEV) console.error('❌ KuzuDB Initialization Failed:', error);
+    throw error;
+  }
+};
+
+/**
+ * Load a KnowledgeGraph into KuzuDB using COPY FROM (bulk load)
+ * Uses batched CSV writes and COPY statements for optimal performance
+ */
+export const loadGraphToKuzu = async (
+  graph: KnowledgeGraph, 
+  fileContents: Map<string, string>
+) => {
+  const { conn, kuzu } = await initKuzu();
+  
+  try {
+    if (import.meta.env.DEV) console.log(`KuzuDB: Generating CSVs for ${graph.nodeCount} nodes...`);
+    
+    // 1. Generate all CSVs (per-table)
+    const csvData = generateAllCSVs(graph, fileContents);
+    
+    const fs = kuzu.FS;
+    
+    // 2. Write all node CSVs to virtual filesystem
+    const nodeFiles: Array<{ table: NodeTableName; path: string }> = [];
+    for (const [tableName, csv] of csvData.nodes.entries()) {
+      // Skip empty CSVs (only header row)
+      if (csv.split('\n').length <= 1) continue;
+      
+      const path = `/${tableName.toLowerCase()}.csv`;
+      try { await fs.unlink(path); } catch {}
+      await fs.writeFile(path, csv);
+      nodeFiles.push({ table: tableName, path });
+    }
+    
+    // 3. Parse relation CSV and prepare for INSERT (COPY FROM doesn't work with multi-pair tables)
+    const relLines = csvData.relCSV.split('\n').slice(1).filter(line => line.trim());
+    const relCount = relLines.length;
+    
+    if (import.meta.env.DEV) {
+      console.log(`KuzuDB: Wrote ${nodeFiles.length} node CSVs, ${relCount} relations to insert`);
+    }
+    
+    // 4. COPY all node tables (must complete before rels due to FK constraints)
+    for (const { table, path } of nodeFiles) {
+      const copyQuery = getCopyQuery(table, path);
+      await conn.query(copyQuery);
+    }
+    
+    // 5. INSERT relations one by one (COPY doesn't work with multi-pair REL tables)
+    // Parse CSV format: "from","to","type",confidence,"reason"
+    let insertedRels = 0;
+    let skippedRels = 0;
+    const skippedRelStats = new Map<string, number>();
+    for (const line of relLines) {
+      try {
+        // Parse CSV - handle quoted fields and numeric confidence
+        // Format: "from","to","type",confidence,"reason"
+        const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)"/);
+        if (!match) continue;
+        
+        const [, fromId, toId, relType, confidenceStr, reason] = match;
+        const confidence = parseFloat(confidenceStr) || 1.0;
+        
+        // Extract labels from node IDs
+        // Community nodes have IDs like "comm_14" (no colon)
+        // Other nodes have IDs like "Label:path:name"
+        const getNodeLabel = (nodeId: string): string => {
+          if (nodeId.startsWith('comm_')) {
+            return 'Community';
+          }
+          return nodeId.split(':')[0];
+        };
+        
+        const fromLabel = getNodeLabel(fromId);
+        const toLabel = getNodeLabel(toId);
+        
+        // INSERT with explicit node matching (including confidence and reason)
+        const insertQuery = `
+          MATCH (a:${fromLabel} {id: '${fromId.replace(/'/g, "''")}'}),
+                (b:${toLabel} {id: '${toId.replace(/'/g, "''")}'})
+          CREATE (a)-[:${REL_TABLE_NAME} {type: '${relType}', confidence: ${confidence}, reason: '${reason.replace(/'/g, "''")}'}]->(b)
+        `;
+        await conn.query(insertQuery);
+        insertedRels++;
+      } catch {
+        // Skip failed insertions (nodes might not exist, or relation pair not allowed by schema)
+        skippedRels++;
+        if (import.meta.env.DEV) {
+          const match = line.match(/"([^"]*)","([^"]*)","([^"]*)",([0-9.]+),"([^"]*)"/);
+          if (match) {
+            const [, fromId, toId, relType] = match;
+            const getNodeLabel = (nodeId: string): string => {
+              if (nodeId.startsWith('comm_')) return 'Community';
+              return nodeId.split(':')[0];
+            };
+            const fromLabel = getNodeLabel(fromId);
+            const toLabel = getNodeLabel(toId);
+            const key = `${relType}:${fromLabel}->` + toLabel;
+            skippedRelStats.set(key, (skippedRelStats.get(key) || 0) + 1);
+          }
+        }
+      }
+    }
+    
+    if (import.meta.env.DEV) {
+      console.log(`KuzuDB: Inserted ${insertedRels}/${relCount} relations`);
+      if (skippedRels > 0) {
+        const topSkipped = Array.from(skippedRelStats.entries())
+          .sort((a, b) => b[1] - a[1])
+          .slice(0, 10);
+        console.warn(`KuzuDB: Skipped ${skippedRels}/${relCount} relations (top by kind/pair):`, topSkipped);
+      }
+    }
+    
+    // 6. Verify results
+    let totalNodes = 0;
+    for (const tableName of NODE_TABLES) {
+      try {
+        const countRes = await conn.query(`MATCH (n:${tableName}) RETURN count(n) AS cnt`);
+        const countRow = await countRes.getNext();
+        const count = countRow ? (countRow.cnt ?? countRow[0] ?? 0) : 0;
+        totalNodes += Number(count);
+      } catch {
+        // Table might be empty, skip
+      }
+    }
+    
+    if (import.meta.env.DEV) console.log(`✅ KuzuDB Bulk Load Complete. Total nodes: ${totalNodes}, edges: ${insertedRels}`);
+
+    // 7. Cleanup CSV files
+    for (const { path } of nodeFiles) {
+      try { await fs.unlink(path); } catch {}
+    }
+
+    return { success: true, count: totalNodes };
+
+  } catch (error) {
+    if (import.meta.env.DEV) console.error('❌ KuzuDB Bulk Load Failed:', error);
+    return { success: false, count: 0 };
+  }
+};
+
+/**
+ * Get the COPY query for a node table with correct column mapping
+ */
+const getCopyQuery = (table: NodeTableName, path: string): string => {
+  // File and Folder have different columns than code elements
+  if (table === 'File') {
+    return `COPY File(id, name, filePath, content) FROM "${path}" (HEADER=true, PARALLEL=false)`;
+  }
+  if (table === 'Folder') {
+    return `COPY Folder(id, name, filePath) FROM "${path}" (HEADER=true, PARALLEL=false)`;
+  }
+  if (table === 'Community') {
+    return `COPY Community(id, label, heuristicLabel, keywords, description, enrichedBy, cohesion, symbolCount) FROM "${path}" (HEADER=true, PARALLEL=false)`;
+  }
+  // All code element tables: Function, Class, Interface, Method, CodeElement
+  return `COPY ${table}(id, name, filePath, startLine, endLine, content) FROM "${path}" (HEADER=true, PARALLEL=false)`;
+};
+
+/**
+ * Execute a Cypher query against the database
+ * Returns results as named objects (not tuples) for better usability
+ */
+export const executeQuery = async (cypher: string): Promise<any[]> => {
+  if (!conn) {
+    await initKuzu();
+  }
+  
+  try {
+    const result = await conn.query(cypher);
+    
+    // Extract column names from RETURN clause
+    const returnMatch = cypher.match(/RETURN\s+(.+?)(?:\s+ORDER|\s+LIMIT|\s+SKIP|\s*$)/is);
+    let columnNames: string[] = [];
+    if (returnMatch) {
+      // Parse RETURN clause to get column names/aliases
+      // Handles: "a.name, b.filePath AS path, count(x) AS cnt"
+      const returnClause = returnMatch[1];
+      columnNames = returnClause.split(',').map(col => {
+        col = col.trim();
+        // Check for AS alias
+        const asMatch = col.match(/\s+AS\s+(\w+)\s*$/i);
+        if (asMatch) return asMatch[1];
+        // Check for property access like n.name
+        const propMatch = col.match(/\.(\w+)\s*$/);
+        if (propMatch) return propMatch[1];
+        // Check for function call like count(x)
+        const funcMatch = col.match(/^(\w+)\s*\(/);
+        if (funcMatch) return funcMatch[1];
+        // Just use as-is if simple identifier
+        return col.replace(/[^a-zA-Z0-9_]/g, '_');
+      });
+    }
+    
+    // Collect all rows
+    const rows: any[] = [];
+    while (await result.hasNext()) {
+      const row = await result.getNext();
+      
+      // Convert tuple to named object if we have column names and row is array
+      if (Array.isArray(row) && columnNames.length === row.length) {
+        const namedRow: Record<string, any> = {};
+        for (let i = 0; i < row.length; i++) {
+          namedRow[columnNames[i]] = row[i];
+        }
+        rows.push(namedRow);
+      } else {
+        // Already an object or column count doesn't match
+        rows.push(row);
+      }
+    }
+    
+    return rows;
+  } catch (error) {
+    if (import.meta.env.DEV) console.error('Query execution failed:', error);
+    throw error;
+  }
+};
+
+/**
+ * Get database statistics
+ */
+export const getKuzuStats = async (): Promise<{ nodes: number; edges: number }> => {
+  if (!conn) {
+    return { nodes: 0, edges: 0 };
+  }
+
+  try {
+    // Count nodes across all tables
+    let totalNodes = 0;
+    for (const tableName of NODE_TABLES) {
+      try {
+        const nodeResult = await conn.query(`MATCH (n:${tableName}) RETURN count(n) AS cnt`);
+        const nodeRow = await nodeResult.getNext();
+        totalNodes += Number(nodeRow?.cnt ?? nodeRow?.[0] ?? 0);
+      } catch {
+        // Table might not exist or be empty
+      }
+    }
+    
+    // Count edges from single relation table
+    let totalEdges = 0;
+    try {
+      const edgeResult = await conn.query(`MATCH ()-[r:${REL_TABLE_NAME}]->() RETURN count(r) AS cnt`);
+      const edgeRow = await edgeResult.getNext();
+      totalEdges = Number(edgeRow?.cnt ?? edgeRow?.[0] ?? 0);
+    } catch {
+      // Table might not exist or be empty
+    }
+    
+    return { nodes: totalNodes, edges: totalEdges };
+  } catch (error) {
+    if (import.meta.env.DEV) {
+      console.warn('Failed to get Kuzu stats:', error);
+    }
+    return { nodes: 0, edges: 0 };
+  }
+};
+
+/**
+ * Check if KuzuDB is initialized and has data
+ */
+export const isKuzuReady = (): boolean => {
+  return conn !== null && db !== null;
+};
+
+/**
+ * Close the database connection (cleanup)
+ */
+export const closeKuzu = async (): Promise<void> => {
+  if (conn) {
+    try {
+      await conn.close();
+    } catch {}
+    conn = null;
+  }
+  if (db) {
+    try {
+      await db.close();
+    } catch {}
+    db = null;
+  }
+  kuzu = null;
+};
+
+/**
+ * Execute a prepared statement with parameters
+ * @param cypher - Cypher query with $param placeholders
+ * @param params - Object mapping param names to values
+ * @returns Query results
+ */
+export const executePrepared = async (
+  cypher: string,
+  params: Record<string, any>
+): Promise<any[]> => {
+  if (!conn) {
+    await initKuzu();
+  }
+  
+  try {
+    const stmt = await conn.prepare(cypher);
+    if (!stmt.isSuccess()) {
+      const errMsg = await stmt.getErrorMessage();
+      throw new Error(`Prepare failed: ${errMsg}`);
+    }
+    
+    const result = await conn.execute(stmt, params);
+    
+    const rows: any[] = [];
+    while (await result.hasNext()) {
+      const row = await result.getNext();
+      rows.push(row);
+    }
+    
+    await stmt.close();
+    return rows;
+  } catch (error) {
+    if (import.meta.env.DEV) console.error('Prepared query failed:', error);
+    throw error;
+  }
+};
+
+/**
+ * Execute a prepared statement with multiple parameter sets in small sub-batches
+ */
+export const executeWithReusedStatement = async (
+  cypher: string,
+  paramsList: Array<Record<string, any>>
+): Promise<void> => {
+  if (!conn) {
+    await initKuzu();
+  }
+  
+  if (paramsList.length === 0) return;
+  
+  const SUB_BATCH_SIZE = 4;
+  
+  for (let i = 0; i < paramsList.length; i += SUB_BATCH_SIZE) {
+    const subBatch = paramsList.slice(i, i + SUB_BATCH_SIZE);
+    
+    const stmt = await conn.prepare(cypher);
+    if (!stmt.isSuccess()) {
+      const errMsg = await stmt.getErrorMessage();
+      throw new Error(`Prepare failed: ${errMsg}`);
+    }
+    
+    try {
+      for (const params of subBatch) {
+        await conn.execute(stmt, params);
+      }
+    } finally {
+      await stmt.close();
+    }
+    
+    if (i + SUB_BATCH_SIZE < paramsList.length) {
+      await new Promise(r => setTimeout(r, 0));
+    }
+  }
+};
+
+/**
+ * Test if array parameters work with prepared statements
+ */
+export const testArrayParams = async (): Promise<{ success: boolean; error?: string }> => {
+  if (!conn) {
+    await initKuzu();
+  }
+  
+  try {
+    const testEmbedding = new Array(384).fill(0).map((_, i) => i / 384);
+    
+    // Get any node ID to test with (try File first, then others)
+    let testNodeId: string | null = null;
+    for (const tableName of NODE_TABLES) {
+      try {
+        const nodeResult = await conn.query(`MATCH (n:${tableName}) RETURN n.id AS id LIMIT 1`);
+        const nodeRow = await nodeResult.getNext();
+        if (nodeRow) {
+          testNodeId = nodeRow.id ?? nodeRow[0];
+          break;
+        }
+      } catch {}
+    }
+    
+    if (!testNodeId) {
+      return { success: false, error: 'No nodes found to test with' };
+    }
+    
+    if (import.meta.env.DEV) {
+      console.log('🧪 Testing array params with node:', testNodeId);
+    }
+    
+    // First create an embedding entry
+    const createQuery = `CREATE (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId, embedding: $embedding})`;
+    const stmt = await conn.prepare(createQuery);
+    
+    if (!stmt.isSuccess()) {
+      const errMsg = await stmt.getErrorMessage();
+      return { success: false, error: `Prepare failed: ${errMsg}` };
+    }
+    
+    await conn.execute(stmt, {
+      nodeId: testNodeId,
+      embedding: testEmbedding,
+    });
+    
+    await stmt.close();
+    
+    // Verify it was stored
+    const verifyResult = await conn.query(
+      `MATCH (e:${EMBEDDING_TABLE_NAME} {nodeId: '${testNodeId}'}) RETURN e.embedding AS emb`
+    );
+    const verifyRow = await verifyResult.getNext();
+    const storedEmb = verifyRow?.emb ?? verifyRow?.[0];
+    
+    if (storedEmb && Array.isArray(storedEmb) && storedEmb.length === 384) {
+      if (import.meta.env.DEV) {
+        console.log('✅ Array params WORK! Stored embedding length:', storedEmb.length);
+      }
+      return { success: true };
+    } else {
+      return { 
+        success: false, 
+        error: `Embedding not stored correctly. Got: ${typeof storedEmb}, length: ${storedEmb?.length}` 
+      };
+    }
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    if (import.meta.env.DEV) {
+      console.error('❌ Array params test failed:', errorMsg);
+    }
+    return { success: false, error: errorMsg };
+  }
+};
+```
+
+## core/kuzu/schema.ts
+
+```typescript
+/**
+ * KuzuDB Schema Definitions
+ * 
+ * Hybrid Schema:
+ * - Separate node tables for each code element type (File, Function, Class, etc.)
+ * - Single CodeRelation table with 'type' property for all relationships
+ * 
+ * This allows LLMs to write natural Cypher queries like:
+ *   MATCH (f:Function)-[r:CodeRelation {type: 'CALLS'}]->(g:Function) RETURN f, g
+ */
+
+// ============================================================================
+// NODE TABLE NAMES
+// ============================================================================
+export const NODE_TABLES = ['File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement', 'Community'] as const;
+export type NodeTableName = typeof NODE_TABLES[number];
+
+// ============================================================================
+// RELATION TABLE
+// ============================================================================
+export const REL_TABLE_NAME = 'CodeRelation';
+
+// Valid relation types
+export const REL_TYPES = ['CONTAINS', 'DEFINES', 'IMPORTS', 'CALLS', 'EXTENDS', 'IMPLEMENTS', 'MEMBER_OF'] as const;
+export type RelType = typeof REL_TYPES[number];
+
+// ============================================================================
+// EMBEDDING TABLE
+// ============================================================================
+export const EMBEDDING_TABLE_NAME = 'CodeEmbedding';
+
+// ============================================================================
+// NODE TABLE SCHEMAS
+// ============================================================================
+
+export const FILE_SCHEMA = `
+CREATE NODE TABLE File (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const FOLDER_SCHEMA = `
+CREATE NODE TABLE Folder (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const FUNCTION_SCHEMA = `
+CREATE NODE TABLE Function (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const CLASS_SCHEMA = `
+CREATE NODE TABLE Class (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const INTERFACE_SCHEMA = `
+CREATE NODE TABLE Interface (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const METHOD_SCHEMA = `
+CREATE NODE TABLE Method (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+export const CODE_ELEMENT_SCHEMA = `
+CREATE NODE TABLE CodeElement (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  PRIMARY KEY (id)
+)`;
+
+// ============================================================================
+// COMMUNITY NODE TABLE (for Leiden algorithm clusters)
+// ============================================================================
+
+export const COMMUNITY_SCHEMA = `
+CREATE NODE TABLE Community (
+  id STRING,
+  label STRING,
+  heuristicLabel STRING,
+  keywords STRING[],
+  description STRING,
+  enrichedBy STRING,
+  cohesion DOUBLE,
+  symbolCount INT32,
+  PRIMARY KEY (id)
+)`;
+
+// ============================================================================
+// RELATION TABLE SCHEMA
+// Single table with 'type' property - connects all node tables
+// ============================================================================
+
+export const RELATION_SCHEMA = `
+CREATE REL TABLE ${REL_TABLE_NAME} (
+  FROM File TO File,
+  FROM File TO Folder,
+  FROM File TO Function,
+  FROM File TO Class,
+  FROM File TO Interface,
+  FROM File TO Method,
+  FROM File TO CodeElement,
+  FROM Folder TO Folder,
+  FROM Folder TO File,
+  FROM Function TO Function,
+  FROM Function TO Method,
+  FROM Function TO Class,
+  FROM Function TO Community,
+  FROM Class TO Method,
+  FROM Class TO Function,
+  FROM Class TO Class,
+  FROM Class TO Interface,
+  FROM Class TO Community,
+  FROM Method TO Function,
+  FROM Method TO Method,
+  FROM Method TO Class,
+  FROM Method TO Community,
+  FROM CodeElement TO Community,
+  FROM Interface TO Community,
+  type STRING,
+  confidence DOUBLE,
+  reason STRING
+)`;
+
+// ============================================================================
+// EMBEDDING TABLE SCHEMA
+// Separate table for vector storage to avoid copy-on-write overhead
+// ============================================================================
+
+export const EMBEDDING_SCHEMA = `
+CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
+  nodeId STRING,
+  embedding FLOAT[384],
+  PRIMARY KEY (nodeId)
+)`;
+
+/**
+ * Create vector index for semantic search
+ * Uses HNSW (Hierarchical Navigable Small World) algorithm with cosine similarity
+ */
+export const CREATE_VECTOR_INDEX_QUERY = `
+CALL CREATE_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', 'code_embedding_idx', 'embedding', metric := 'cosine')
+`;
+
+// ============================================================================
+// ALL SCHEMA QUERIES IN ORDER
+// Node tables must be created before relationship tables that reference them
+// ============================================================================
+
+export const NODE_SCHEMA_QUERIES = [
+  FILE_SCHEMA,
+  FOLDER_SCHEMA,
+  FUNCTION_SCHEMA,
+  CLASS_SCHEMA,
+  INTERFACE_SCHEMA,
+  METHOD_SCHEMA,
+  CODE_ELEMENT_SCHEMA,
+  COMMUNITY_SCHEMA,
+];
+
+export const REL_SCHEMA_QUERIES = [
+  RELATION_SCHEMA,
+];
+
+export const SCHEMA_QUERIES = [
+  ...NODE_SCHEMA_QUERIES,
+  ...REL_SCHEMA_QUERIES,
+  EMBEDDING_SCHEMA,
+];
+```
+
+## core/llm/agent.ts
+
+```typescript
+/**
+ * Graph RAG Agent Factory
+ * 
+ * Creates a LangChain agent configured for code graph analysis.
+ * Supports Azure OpenAI and Google Gemini providers.
+ */
+
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { SystemMessage } from '@langchain/core/messages';
+import { ChatOpenAI, AzureChatOpenAI } from '@langchain/openai';
+import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { ChatOllama } from '@langchain/ollama';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { createGraphRAGTools } from './tools';
+import type { 
+  ProviderConfig, 
+  OpenAIConfig,
+  AzureOpenAIConfig, 
+  GeminiConfig,
+  AnthropicConfig,
+  OllamaConfig,
+  AgentStreamChunk,
+} from './types';
+import { 
+  type CodebaseContext,
+  buildDynamicSystemPrompt,
+} from './context-builder';
+
+/**
+ * System prompt for the Graph RAG agent
+ * 
+ * Design principles (based on Aider/Cline research):
+ * - Short, punchy directives > long explanations
+ * - No template-inducing examples
+ * - Let LLM figure out HOW, just tell it WHAT behavior we want
+ * - Explicit progress reporting requirement
+ * - Anti-laziness directives
+ */
+/**
+ * Base system prompt - exported so it can be used with dynamic context injection
+ * 
+ * Structure (optimized for instruction following):
+ * 1. Identity + GROUNDING mandate (most important)
+ * 2. Core protocol (how to work)
+ * 3. Tools reference
+ * 4. Output format & rules
+ * 5. [Dynamic context appended at end]
+ */
+export const BASE_SYSTEM_PROMPT = `You are Nexus, a Code Analysis Agent with access to a Knowledge Graph. Your responses MUST be grounded.
+
+## ⚠️ MANDATORY: GROUNDING
+Every factual claim MUST include a citation.
+- File refs: [[src/auth.ts:45-60]] (line range with hyphen)
+- NO citation = NO claim. Say "I didn't find evidence" instead of guessing.
+
+## ⚠️ MANDATORY: VALIDATION
+Every output MUST be validated.
+- Use cypher to validate the results and confirm completeness of context before final output.
+- NO validation = NO claim. Say "I didn't find evidence" instead of guessing.
+- Do not blindly trust readme or single source of truth. Always validate and cross-reference. Never be lazy.
+
+## 🧠 CORE PROTOCOL
+You are an investigator. For each question:
+1. **Search** → Use cypher, search or grep to find relevant code
+2. **Read** → Use read to see the actual source
+3. **Trace** → Use cypher to follow connections in the graph
+4. **Cite** → Ground every finding with [[file:line]] or [[Type:Name]]
+5. **Validate** → Use cypher to validate the results and confirm completeness of context before final output. ( MUST DO )
+6. **Highlight** → Visualize key nodes with highlight
+
+## 🛠️ TOOLS
+- **\`search\`** — Hybrid search (keyword + semantic). Returns code matches with graph connections.
+- **\`cypher\`** — Cypher queries against the graph. Use \`{{QUERY_VECTOR}}\` for vector search.
+- **\`grep\`** — Regex search. Best for exact strings, TODOs, error codes.
+- **\`read\`** — Read file content. Always use after search/grep to see full code.
+- **\`highlight\`** — Highlight nodes in the visual graph.
+- **\`blastRadius\`** — Impact analysis. Output is graph-verified (trusted). Run optional grep for dynamic patterns if thoroughness needed.
+
+## 📊 GRAPH SCHEMA
+Nodes: File, Folder, Function, Class, Interface, Method, CodeElement
+Relation: \`CodeRelation\` with \`type\` property: CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS
+
+Cypher examples:
+- \`MATCH (f:Function) RETURN f.name LIMIT 10\`
+- \`MATCH (f:File)-[:CodeRelation {type: 'IMPORTS'}]->(g:File) RETURN f.name, g.name\`
+
+## 📝CRITICAL RULES
+- **blastRadius output is trusted.** Do NOT re-validate with cypher. Optionally run the suggested grep commands for dynamic patterns.
+- **Cite or retract.** Never state something you can't ground.
+- **Read before concluding.** Don't guess from names alone.
+- **Retry on failure.** If a tool fails, fix the input and try again.
+- **Cyfer tool validation** prefer using cyfer tool in anything that requires graph connections.
+- **OUTPUT STYLE** Prefer using tables and mermaid diagrams instead of long explanations.
+- ALWAYS USE MERMAID FOR VISUALIZATION AND STRUCTURING THE OUTPUT.
+
+## 🎯 OUTPUT STYLE
+Think like a senior architect. Be concise—no fluff, short, precise and to the point.
+- Use tables for comparisons/rankings
+- Use mermaid diagrams for flows/dependencies
+- Surface deep insights: patterns, coupling, design decisions
+- End with **TL;DR** (1-2 sentences)
+
+## MERMAID RULES
+When generating diagrams:
+- NO special characters in node labels: quotes, (), /, &, <, >
+- Wrap labels with spaces in quotes: A["My Label"]
+- Use simple IDs: A, B, C or auth, db, api
+- Flowchart: graph TD or graph LR (not flowchart)
+- Always test mentally: would this parse?
+
+BAD:  A[User's Data] --> B(Process & Save)
+GOOD: A["User Data"] --> B["Process and Save"]
+`;
+export const createChatModel = (config: ProviderConfig): BaseChatModel => {
+  switch (config.provider) {
+    case 'openai': {
+      const openaiConfig = config as OpenAIConfig;
+      return new ChatOpenAI({
+        openAIApiKey: openaiConfig.apiKey,
+        modelName: openaiConfig.model,
+        temperature: openaiConfig.temperature ?? 0.1,
+        maxTokens: openaiConfig.maxTokens,
+        configuration: openaiConfig.baseUrl ? {
+          baseURL: openaiConfig.baseUrl,
+        } : undefined,
+        streaming: true,
+      });
+    }
+    
+    case 'azure-openai': {
+      const azureConfig = config as AzureOpenAIConfig;
+      return new AzureChatOpenAI({
+        azureOpenAIApiKey: azureConfig.apiKey,
+        azureOpenAIApiInstanceName: extractInstanceName(azureConfig.endpoint),
+        azureOpenAIApiDeploymentName: azureConfig.deploymentName,
+        azureOpenAIApiVersion: azureConfig.apiVersion ?? '2024-12-01-preview',
+        // Note: gpt-5.2-chat only supports temperature=1 (default)
+        streaming: true,
+      });
+    }
+    
+    case 'gemini': {
+      const geminiConfig = config as GeminiConfig;
+      return new ChatGoogleGenerativeAI({
+        apiKey: geminiConfig.apiKey,
+        model: geminiConfig.model,
+        temperature: geminiConfig.temperature ?? 0.1,
+        maxOutputTokens: geminiConfig.maxTokens,
+        streaming: true,
+      });
+    }
+    
+    case 'anthropic': {
+      const anthropicConfig = config as AnthropicConfig;
+      return new ChatAnthropic({
+        anthropicApiKey: anthropicConfig.apiKey,
+        model: anthropicConfig.model,
+        temperature: anthropicConfig.temperature ?? 0.1,
+        maxTokens: anthropicConfig.maxTokens ?? 8192,
+        streaming: true,
+      });
+    }
+    
+    case 'ollama': {
+      const ollamaConfig = config as OllamaConfig;
+      return new ChatOllama({
+        baseUrl: ollamaConfig.baseUrl ?? 'http://localhost:11434',
+        model: ollamaConfig.model,
+        temperature: ollamaConfig.temperature ?? 0.1,
+        streaming: true,
+        // Allow longer responses (Ollama default is often 128-2048)
+        numPredict: 30000,
+        // Increase context window (Ollama default is only 2048!)
+        // This is critical for agentic workflows with tool calls
+        numCtx: 32768,
+      });
+    }
+    
+    default:
+      throw new Error(`Unsupported provider: ${(config as any).provider}`);
+  }
+};
+
+/**
+ * Extract instance name from Azure endpoint URL
+ * e.g., "https://my-resource.openai.azure.com" -> "my-resource"
+ */
+const extractInstanceName = (endpoint: string): string => {
+  try {
+    const url = new URL(endpoint);
+    const hostname = url.hostname;
+    // Extract the first part before .openai.azure.com
+    const match = hostname.match(/^([^.]+)\.openai\.azure\.com/);
+    if (match) {
+      return match[1];
+    }
+    // Fallback: just use the first part of hostname
+    return hostname.split('.')[0];
+  } catch {
+    return endpoint;
+  }
+};
+
+/**
+ * Create a Graph RAG agent
+ */
+export const createGraphRAGAgent = (
+  config: ProviderConfig,
+  executeQuery: (cypher: string) => Promise<any[]>,
+  semanticSearch: (query: string, k?: number, maxDistance?: number) => Promise<any[]>,
+  semanticSearchWithContext: (query: string, k?: number, hops?: number) => Promise<any[]>,
+  hybridSearch: (query: string, k?: number) => Promise<any[]>,
+  isEmbeddingReady: () => boolean,
+  isBM25Ready: () => boolean,
+  fileContents: Map<string, string>,
+  codebaseContext?: CodebaseContext
+) => {
+  const model = createChatModel(config);
+  const tools = createGraphRAGTools(
+    executeQuery,
+    semanticSearch,
+    semanticSearchWithContext,
+    hybridSearch,
+    isEmbeddingReady,
+    isBM25Ready,
+    fileContents
+  );
+  
+  // Use dynamic prompt if context is provided, otherwise use base prompt
+  const systemPrompt = codebaseContext 
+    ? buildDynamicSystemPrompt(BASE_SYSTEM_PROMPT, codebaseContext)
+    : BASE_SYSTEM_PROMPT;
+  
+  // Log the full prompt for debugging
+  if (import.meta.env.DEV) {
+    console.log('🤖 AGENT SYSTEM PROMPT:\n', systemPrompt);
+  }
+  
+  const agent = createReactAgent({
+    llm: model as any,
+    tools: tools as any,
+    messageModifier: new SystemMessage(systemPrompt) as any,
+  });
+  
+  return agent;
+};
+
+/**
+ * Message type for agent conversation
+ */
+export interface AgentMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Stream a response from the agent
+ * Uses BOTH streamModes for best of both worlds:
+ * - 'values' for state transitions (tool calls, results) in proper order
+ * - 'messages' for token-by-token text streaming
+ * 
+ * This preserves the natural progression: reasoning → tool → reasoning → tool → answer
+ */
+export async function* streamAgentResponse(
+  agent: ReturnType<typeof createReactAgent>,
+  messages: AgentMessage[]
+): AsyncGenerator<AgentStreamChunk> {
+  try {
+    const formattedMessages = messages.map(m => ({
+      role: m.role,
+      content: m.content,
+    }));
+    
+    // Use BOTH modes: 'values' for structure, 'messages' for token streaming
+    const stream = await agent.stream(
+      { messages: formattedMessages },
+      {
+        streamMode: ['values', 'messages'] as any,
+        // Allow longer tool/reasoning loops (more Cursor-like persistence)
+        recursionLimit: 50,
+      } as any
+    );
+    
+    // Track what we've yielded to avoid duplicates
+    const yieldedToolCalls = new Set<string>();
+    const yieldedToolResults = new Set<string>();
+    let lastProcessedMsgCount = formattedMessages.length;
+    // Track if all tools are done (for distinguishing reasoning vs final content)
+    let allToolsDone = true;
+    // Track if we've seen any tool calls in this response turn.
+    // Anything before the first tool call should be treated as "reasoning/narration"
+    // so the UI can show the Cursor-like loop: plan → tool → update → tool → answer.
+    let hasSeenToolCallThisTurn = false;
+    
+    for await (const event of stream) {
+      // Events come as [streamMode, data] tuples when using multiple modes
+      // or just data when using single mode
+      let mode: string;
+      let data: any;
+      
+      if (Array.isArray(event) && event.length === 2 && typeof event[0] === 'string') {
+        [mode, data] = event;
+      } else if (Array.isArray(event) && event[0]?._getType) {
+        // Single messages mode format: [message, metadata]
+        mode = 'messages';
+        data = event;
+      } else {
+        // Assume values mode
+        mode = 'values';
+        data = event;
+      }
+      
+      // DEBUG: Enhanced logging
+      if (import.meta.env.DEV) {
+        const msgType = mode === 'messages' && data?.[0]?._getType?.() || 'n/a';
+        const hasContent = mode === 'messages' && data?.[0]?.content;
+        const hasToolCalls = mode === 'messages' && data?.[0]?.tool_calls?.length > 0;
+        console.log(`🔄 [${mode}] type:${msgType} content:${!!hasContent} tools:${hasToolCalls}`);
+      }
+      // Handle 'messages' mode - token-by-token streaming
+      if (mode === 'messages') {
+        const [msg] = Array.isArray(data) ? data : [data];
+        if (!msg) continue;
+        
+        const msgType = msg._getType?.() || msg.type || msg.constructor?.name || 'unknown';
+        
+        // AIMessageChunk - streaming text tokens
+        if (msgType === 'ai' || msgType === 'AIMessage' || msgType === 'AIMessageChunk') {
+          const rawContent = msg.content;
+          const toolCalls = msg.tool_calls || [];
+          
+          // Handle content that can be string or array of content blocks
+          let content: string = '';
+          if (typeof rawContent === 'string') {
+            content = rawContent;
+          } else if (Array.isArray(rawContent)) {
+            // Content blocks format: [{type: 'text', text: '...'}, ...]
+            content = rawContent
+              .filter((block: any) => block.type === 'text' || typeof block === 'string')
+              .map((block: any) => typeof block === 'string' ? block : block.text || '')
+              .join('');
+          }
+          
+          // If chunk has content, stream it
+          if (content && content.length > 0) {
+            // Determine if this is reasoning/narration vs final answer content.
+            // - Before the first tool call: treat as reasoning (narration)
+            // - Between tool calls/results: treat as reasoning
+            // - After all tools are done: treat as final content
+            const isReasoning =
+              !hasSeenToolCallThisTurn ||
+              toolCalls.length > 0 ||
+              !allToolsDone;
+            yield {
+              type: isReasoning ? 'reasoning' : 'content',
+              [isReasoning ? 'reasoning' : 'content']: content,
+            };
+          }
+          
+          // Track tool calls from message chunks
+          if (toolCalls.length > 0) {
+            hasSeenToolCallThisTurn = true;
+            allToolsDone = false;
+            for (const tc of toolCalls) {
+              const toolId = tc.id || `tool-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+              if (!yieldedToolCalls.has(toolId)) {
+                yieldedToolCalls.add(toolId);
+                yield {
+                  type: 'tool_call',
+                  toolCall: {
+                    id: toolId,
+                    name: tc.name || tc.function?.name || 'unknown',
+                    args: tc.args || (tc.function?.arguments ? JSON.parse(tc.function.arguments) : {}),
+                    status: 'running',
+                  },
+                };
+              }
+            }
+          }
+        }
+        
+        // ToolMessage in messages mode
+        if (msgType === 'tool' || msgType === 'ToolMessage') {
+          const toolCallId = msg.tool_call_id || '';
+          if (toolCallId && !yieldedToolResults.has(toolCallId)) {
+            yieldedToolResults.add(toolCallId);
+            const result = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+            yield {
+              type: 'tool_result',
+              toolCall: {
+                id: toolCallId,
+                name: msg.name || 'tool',
+                args: {},
+                result: result,
+                status: 'completed',
+              },
+            };
+            // After tool result, next AI content could be reasoning or final
+            allToolsDone = true;
+          }
+        }
+      }
+      
+      // Handle 'values' mode - state snapshots for structure
+      if (mode === 'values' && data?.messages) {
+        const stepMessages = data.messages || [];
+        
+        // Process new messages for tool calls/results we might have missed
+        for (let i = lastProcessedMsgCount; i < stepMessages.length; i++) {
+          const msg = stepMessages[i];
+          const msgType = msg._getType?.() || msg.type || 'unknown';
+          
+          // Catch tool calls from values mode (backup)
+          if ((msgType === 'ai' || msgType === 'AIMessage') && !yieldedToolCalls.size) {
+            const toolCalls = msg.tool_calls || [];
+            for (const tc of toolCalls) {
+              const toolId = tc.id || `tool-${Date.now()}`;
+              if (!yieldedToolCalls.has(toolId)) {
+                allToolsDone = false;
+                yieldedToolCalls.add(toolId);
+                yield {
+                  type: 'tool_call',
+                  toolCall: {
+                    id: toolId,
+                    name: tc.name || 'unknown',
+                    args: tc.args || {},
+                    status: 'running',
+                  },
+                };
+              }
+            }
+          }
+          
+          // Catch tool results from values mode (backup)
+          if (msgType === 'tool' || msgType === 'ToolMessage') {
+            const toolCallId = msg.tool_call_id || '';
+            if (toolCallId && !yieldedToolResults.has(toolCallId)) {
+              yieldedToolResults.add(toolCallId);
+              const result = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+              yield {
+                type: 'tool_result',
+                toolCall: {
+                  id: toolCallId,
+                  name: msg.name || 'tool',
+                  args: {},
+                  result: result,
+                  status: 'completed',
+                },
+              };
+              allToolsDone = true;
+            }
+          }
+        }
+        
+        lastProcessedMsgCount = stepMessages.length;
+      }
+    }
+    
+    // DEBUG: Stream completed normally
+    if (import.meta.env.DEV) {
+      console.log('✅ Stream completed normally, yielding done');
+    }
+    yield { type: 'done' };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // DEBUG: Stream error
+    if (import.meta.env.DEV) {
+      console.error('❌ Stream error:', message, error);
+    }
+    yield { 
+      type: 'error', 
+      error: message,
+    };
+  }
+}
+
+/**
+ * Get a non-streaming response from the agent
+ * Simpler for cases where streaming isn't needed
+ */
+export const invokeAgent = async (
+  agent: ReturnType<typeof createReactAgent>,
+  messages: AgentMessage[]
+): Promise<string> => {
+  const formattedMessages = messages.map(m => ({
+    role: m.role,
+    content: m.content,
+  }));
+  
+  const result = await agent.invoke({ messages: formattedMessages });
+  
+  // result.messages is the full conversation state
+  const lastMessage = result.messages[result.messages.length - 1];
+  return lastMessage?.content?.toString() ?? 'No response generated.';
+};
+```
+
+## core/llm/context-builder.ts
+
+````typescript
+/**
+ * Context Builder for Graph RAG Agent
+ * 
+ * Generates dynamic context about the loaded codebase to inject into the system prompt.
+ * This helps the LLM understand the project structure, scale, and key entry points
+ * without needing to explore from scratch.
+ */
+
+/**
+ * Codebase statistics
+ */
+export interface CodebaseStats {
+  projectName: string;
+  fileCount: number;
+  functionCount: number;
+  classCount: number;
+  interfaceCount: number;
+  methodCount: number;
+}
+
+/**
+ * Hotspot - highly connected node
+ */
+export interface Hotspot {
+  name: string;
+  type: string;
+  filePath: string;
+  connections: number;
+}
+
+/**
+ * Folder info for tree rendering
+ */
+interface FolderInfo {
+  path: string;
+  name: string;
+  depth: number;
+  fileCount: number;
+  children: FolderInfo[];
+}
+
+/**
+ * Complete codebase context for prompt injection
+ * Simplified: stats + hotspots + folder tree (no entry points or language detection)
+ */
+export interface CodebaseContext {
+  stats: CodebaseStats;
+  hotspots: Hotspot[];
+  folderTree: string;
+}
+
+/**
+ * Get codebase statistics via Cypher queries
+ */
+export async function getCodebaseStats(
+  executeQuery: (cypher: string) => Promise<any[]>,
+  projectName: string
+): Promise<CodebaseStats> {
+  try {
+    // Count each node type
+    const countQueries = [
+      { type: 'files', query: 'MATCH (n:File) RETURN COUNT(n) AS count' },
+      { type: 'functions', query: 'MATCH (n:Function) RETURN COUNT(n) AS count' },
+      { type: 'classes', query: 'MATCH (n:Class) RETURN COUNT(n) AS count' },
+      { type: 'interfaces', query: 'MATCH (n:Interface) RETURN COUNT(n) AS count' },
+      { type: 'methods', query: 'MATCH (n:Method) RETURN COUNT(n) AS count' },
+    ];
+
+    const counts: Record<string, number> = {};
+    
+    for (const { type, query } of countQueries) {
+      try {
+        const result = await executeQuery(query);
+        // Handle both array and object result formats
+        const row = result[0];
+        counts[type] = Array.isArray(row) ? (row[0] ?? 0) : (row?.count ?? 0);
+      } catch {
+        counts[type] = 0;
+      }
+    }
+
+    return {
+      projectName,
+      fileCount: counts.files,
+      functionCount: counts.functions,
+      classCount: counts.classes,
+      interfaceCount: counts.interfaces,
+      methodCount: counts.methods,
+    };
+  } catch (error) {
+    console.error('Failed to get codebase stats:', error);
+    return {
+      projectName,
+      fileCount: 0,
+      functionCount: 0,
+      classCount: 0,
+      interfaceCount: 0,
+      methodCount: 0,
+    };
+  }
+}
+
+
+/**
+ * Find hotspots - nodes with the most connections
+ */
+export async function getHotspots(
+  executeQuery: (cypher: string) => Promise<any[]>,
+  limit: number = 8
+): Promise<Hotspot[]> {
+  try {
+    // Find nodes with most edges (both directions)
+    const query = `
+      MATCH (n)-[r:CodeRelation]-(m)
+      WHERE n.name IS NOT NULL
+      WITH n, COUNT(r) AS connections
+      ORDER BY connections DESC
+      LIMIT ${limit}
+      RETURN n.name AS name, LABEL(n) AS type, n.filePath AS filePath, connections
+    `;
+    
+    const results = await executeQuery(query);
+    
+    return results.map(row => {
+      if (Array.isArray(row)) {
+        return {
+          name: row[0],
+          type: row[1],
+          filePath: row[2],
+          connections: row[3],
+        };
+      }
+      return {
+        name: row.name,
+        type: row.type,
+        filePath: row.filePath,
+        connections: row.connections,
+      };
+    }).filter(h => h.name && h.type);
+  } catch (error) {
+    console.error('Failed to get hotspots:', error);
+    return [];
+  }
+}
+
+/**
+ * Build folder tree structure from file paths
+ * Returns ASCII tree format with smart truncation for readability
+ */
+export async function getFolderTree(
+  executeQuery: (cypher: string) => Promise<any[]>,
+  maxDepth: number = 10
+): Promise<string> {
+  try {
+    // Get all file paths
+    const query = 'MATCH (f:File) RETURN f.filePath AS path ORDER BY path';
+    const results = await executeQuery(query);
+    
+    const paths = results.map(row => {
+      if (Array.isArray(row)) return row[0];
+      return row.path;
+    }).filter(Boolean);
+
+    if (paths.length === 0) return '';
+
+    // Use hybrid ASCII format: clear hierarchy with smart truncation
+    return formatAsHybridAscii(paths, maxDepth);
+  } catch (error) {
+    console.error('Failed to get folder tree:', error);
+    return '';
+  }
+}
+
+/**
+ * Format paths as indented tree (TOON-style, no ASCII box chars)
+ * Uses indentation only for hierarchy - more token efficient than ASCII tree
+ * Shows complete structure with no truncation
+ * 
+ * Example output:
+ * src/
+ *   components/ (45 files)
+ *   hooks/
+ *     useAppState.tsx
+ *     useSigma.ts
+ *   core/ (15 files)
+ * test/ (12 files)
+ */
+function formatAsHybridAscii(paths: string[], maxDepth: number): string {
+  // Build tree structure
+  interface TreeNode {
+    isFile: boolean;
+    children: Map<string, TreeNode>;
+    fileCount: number;
+  }
+  
+  const root: TreeNode = { isFile: false, children: new Map(), fileCount: 0 };
+  
+  for (const path of paths) {
+    const normalized = path.replace(/\\/g, '/');
+    const parts = normalized.split('/').filter(Boolean);
+    
+    let current = root;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isFile = i === parts.length - 1;
+      
+      if (!current.children.has(part)) {
+        current.children.set(part, { isFile, children: new Map(), fileCount: 0 });
+      }
+      
+      current = current.children.get(part)!;
+      if (isFile) {
+        // Count files in parent directories
+        let parent = root;
+        for (let j = 0; j < i; j++) {
+          parent = parent.children.get(parts[j])!;
+          parent.fileCount++;
+        }
+      }
+    }
+  }
+  
+  // Render tree with indentation only (no ASCII box chars)
+  const lines: string[] = [];
+  
+  function renderNode(node: TreeNode, indent: string, depth: number): void {
+    const entries = [...node.children.entries()];
+    // Sort: folders first (by file count desc), then files alphabetically
+    entries.sort(([aName, aNode], [bName, bNode]) => {
+      if (aNode.isFile !== bNode.isFile) return aNode.isFile ? 1 : -1;
+      if (!aNode.isFile && !bNode.isFile) return bNode.fileCount - aNode.fileCount;
+      return aName.localeCompare(bName);
+    });
+    
+    for (const [name, childNode] of entries) {
+      if (childNode.isFile) {
+        // File
+        lines.push(`${indent}${name}`);
+      } else {
+        // Directory
+        const childCount = childNode.children.size;
+        const fileCount = childNode.fileCount;
+        
+        // Only collapse if beyond maxDepth
+        if (depth >= maxDepth) {
+          lines.push(`${indent}${name}/ (${fileCount} files)`);
+        } else {
+          lines.push(`${indent}${name}/`);
+          renderNode(childNode, indent + '  ', depth + 1);
+        }
+      }
+    }
+  }
+  
+  renderNode(root, '', 0);
+  
+  return lines.join('\n');
+}
+
+/**
+ * Build a tree structure from file paths
+ */
+function buildTreeFromPaths(paths: string[], maxDepth: number): Map<string, any> {
+  const root = new Map<string, any>();
+  
+  for (const fullPath of paths) {
+    // Normalize path separators
+    const normalizedPath = fullPath.replace(/\\/g, '/');
+    const parts = normalizedPath.split('/').filter(Boolean);
+    
+    let current = root;
+    const depth = Math.min(parts.length, maxDepth + 1); // +1 to include files at maxDepth
+    
+    for (let i = 0; i < depth; i++) {
+      const part = parts[i];
+      const isFile = i === parts.length - 1;
+      
+      if (!current.has(part)) {
+        current.set(part, isFile ? null : new Map<string, any>());
+      }
+      
+      const next = current.get(part);
+      if (next instanceof Map) {
+        current = next;
+      } else {
+        break;
+      }
+    }
+  }
+  
+  return root;
+}
+
+/**
+ * Format tree as ASCII (like VS Code sidebar)
+ */
+function formatTreeAsAscii(
+  tree: Map<string, any>,
+  prefix: string,
+  isLast: boolean = true
+): string {
+  const lines: string[] = [];
+  const entries = Array.from(tree.entries());
+  
+  // Sort: folders first, then files, alphabetically
+  entries.sort(([a, aVal], [b, bVal]) => {
+    const aIsDir = aVal instanceof Map;
+    const bIsDir = bVal instanceof Map;
+    if (aIsDir !== bIsDir) return bIsDir ? 1 : -1;
+    return a.localeCompare(b);
+  });
+  
+  entries.forEach(([name, subtree], index) => {
+    const isLastItem = index === entries.length - 1;
+    const connector = isLastItem ? '└── ' : '├── ';
+    const childPrefix = prefix + (isLastItem ? '    ' : '│   ');
+    
+    if (subtree instanceof Map && subtree.size > 0) {
+      // Folder with children
+      const childCount = countItems(subtree);
+      const annotation = childCount > 3 ? ` (${childCount} items)` : '';
+      lines.push(`${prefix}${connector}${name}/${annotation}`);
+      lines.push(formatTreeAsAscii(subtree, childPrefix, isLastItem));
+    } else if (subtree instanceof Map) {
+      // Empty folder
+      lines.push(`${prefix}${connector}${name}/`);
+    } else {
+      // File
+      lines.push(`${prefix}${connector}${name}`);
+    }
+  });
+  
+  return lines.filter(Boolean).join('\n');
+}
+
+/**
+ * Count items in a tree node
+ */
+function countItems(tree: Map<string, any>): number {
+  let count = 0;
+  for (const [, value] of tree) {
+    if (value instanceof Map) {
+      count += 1 + countItems(value);
+    } else {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Build complete codebase context
+ */
+export async function buildCodebaseContext(
+  executeQuery: (cypher: string) => Promise<any[]>,
+  projectName: string
+): Promise<CodebaseContext> {
+  // Run all queries in parallel for speed
+  const [stats, hotspots, folderTree] = await Promise.all([
+    getCodebaseStats(executeQuery, projectName),
+    getHotspots(executeQuery),
+    getFolderTree(executeQuery),
+  ]);
+
+  return {
+    stats,
+    hotspots,
+    folderTree,
+  };
+}
+
+/**
+ * Format context as markdown for prompt injection
+ */
+export function formatContextForPrompt(context: CodebaseContext): string {
+  const { stats, hotspots, folderTree } = context;
+  
+  const lines: string[] = [];
+  
+  // Project header with stats
+  lines.push(`### 📊 CODEBASE: ${stats.projectName}`);
+  
+  const statParts = [
+    `Files: ${stats.fileCount}`,
+    `Functions: ${stats.functionCount}`,
+    stats.classCount > 0 ? `Classes: ${stats.classCount}` : null,
+    stats.interfaceCount > 0 ? `Interfaces: ${stats.interfaceCount}` : null,
+  ].filter(Boolean);
+  lines.push(statParts.join(' | '));
+  lines.push('');
+  
+  // Hotspots
+  if (hotspots.length > 0) {
+    lines.push('**Hotspots** (most connected):');
+    hotspots.slice(0, 5).forEach(h => {
+      lines.push(`- \`${h.name}\` (${h.type}) — ${h.connections} edges`);
+    });
+    lines.push('');
+  }
+  
+  // Folder tree
+  if (folderTree) {
+    lines.push('### 📁 STRUCTURE');
+    lines.push('```');
+    lines.push(stats.projectName + '/');
+    lines.push(folderTree);
+    lines.push('```');
+  }
+  
+  return lines.join('\n');
+}
+
+/**
+ * Build the complete dynamic system prompt
+ * Context is appended at the END so core instructions remain at the top
+ */
+export function buildDynamicSystemPrompt(
+  basePrompt: string,
+  context: CodebaseContext
+): string {
+  const contextSection = formatContextForPrompt(context);
+  
+  // Append context at the END - keeps core instructions at top for better adherence
+  return `${basePrompt}
+
+---
+
+## 📦 CURRENT CODEBASE
+${contextSection}`;
+}
+````
+
+## core/llm/index.ts
+
+```typescript
+/**
+ * LLM Module Exports
+ * 
+ * Provides Graph RAG agent capabilities for code analysis.
+ */
+
+// Types
+export * from './types';
+
+// Settings management
+export {
+  loadSettings,
+  saveSettings,
+  updateProviderSettings,
+  setActiveProvider,
+  getActiveProviderConfig,
+  isProviderConfigured,
+  clearSettings,
+  getProviderDisplayName,
+  getAvailableModels,
+} from './settings-service';
+
+// Tools
+export { createGraphRAGTools } from './tools';
+
+// Context Builder
+export {
+  buildCodebaseContext,
+  formatContextForPrompt,
+  buildDynamicSystemPrompt,
+  type CodebaseContext,
+  type CodebaseStats,
+  type Hotspot,
+} from './context-builder';
+
+// Agent
+export {
+  createChatModel,
+  createGraphRAGAgent,
+  streamAgentResponse,
+  invokeAgent,
+  BASE_SYSTEM_PROMPT,
+  type AgentMessage,
+} from './agent';
+```
+
+## core/llm/settings-service.ts
+
+```typescript
+/**
+ * Settings Service
+ * 
+ * Handles localStorage persistence for LLM provider settings.
+ * All API keys are stored locally - never sent to any server except the LLM provider.
+ */
+
+import { 
+  LLMSettings, 
+  DEFAULT_LLM_SETTINGS, 
+  LLMProvider,
+  OpenAIConfig,
+  AzureOpenAIConfig,
+  GeminiConfig,
+  AnthropicConfig,
+  OllamaConfig,
+  ProviderConfig,
+} from './types';
+
+const STORAGE_KEY = 'gitnexus-llm-settings';
+
+/**
+ * Load settings from localStorage
+ */
+export const loadSettings = (): LLMSettings => {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (!stored) {
+      return DEFAULT_LLM_SETTINGS;
+    }
+    
+    const parsed = JSON.parse(stored) as Partial<LLMSettings>;
+    
+    // Merge with defaults to handle new fields
+    return {
+      ...DEFAULT_LLM_SETTINGS,
+      ...parsed,
+      openai: {
+        ...DEFAULT_LLM_SETTINGS.openai,
+        ...parsed.openai,
+      },
+      azureOpenAI: {
+        ...DEFAULT_LLM_SETTINGS.azureOpenAI,
+        ...parsed.azureOpenAI,
+      },
+      gemini: {
+        ...DEFAULT_LLM_SETTINGS.gemini,
+        ...parsed.gemini,
+      },
+      anthropic: {
+        ...DEFAULT_LLM_SETTINGS.anthropic,
+        ...parsed.anthropic,
+      },
+      ollama: {
+        ...DEFAULT_LLM_SETTINGS.ollama,
+        ...parsed.ollama,
+      },
+    };
+  } catch (error) {
+    console.warn('Failed to load LLM settings:', error);
+    return DEFAULT_LLM_SETTINGS;
+  }
+};
+
+/**
+ * Save settings to localStorage
+ */
+export const saveSettings = (settings: LLMSettings): void => {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+  } catch (error) {
+    console.error('Failed to save LLM settings:', error);
+  }
+};
+
+/**
+ * Update a specific provider's settings
+ */
+export const updateProviderSettings = <T extends LLMProvider>(
+  provider: T,
+  updates: Partial<
+    T extends 'openai' ? Partial<Omit<OpenAIConfig, 'provider'>> :
+    T extends 'azure-openai' ? Partial<Omit<AzureOpenAIConfig, 'provider'>> :
+    T extends 'gemini' ? Partial<Omit<GeminiConfig, 'provider'>> :
+    T extends 'anthropic' ? Partial<Omit<AnthropicConfig, 'provider'>> :
+    T extends 'ollama' ? Partial<Omit<OllamaConfig, 'provider'>> :
+    never
+  >
+): LLMSettings => {
+  const current = loadSettings();
+
+  // Avoid spreading unions like LLMSettings[keyof LLMSettings] (can be string/undefined)
+  switch (provider) {
+    case 'openai': {
+      const updated: LLMSettings = {
+        ...current,
+        openai: {
+          ...(current.openai ?? {}),
+          ...(updates as Partial<Omit<OpenAIConfig, 'provider'>>),
+        },
+      };
+      saveSettings(updated);
+      return updated;
+    }
+    case 'azure-openai': {
+      const updated: LLMSettings = {
+        ...current,
+        azureOpenAI: {
+          ...(current.azureOpenAI ?? {}),
+          ...(updates as Partial<Omit<AzureOpenAIConfig, 'provider'>>),
+        },
+      };
+      saveSettings(updated);
+      return updated;
+    }
+    case 'gemini': {
+      const updated: LLMSettings = {
+        ...current,
+        gemini: {
+          ...(current.gemini ?? {}),
+          ...(updates as Partial<Omit<GeminiConfig, 'provider'>>),
+        },
+      };
+      saveSettings(updated);
+      return updated;
+    }
+    case 'anthropic': {
+      const updated: LLMSettings = {
+        ...current,
+        anthropic: {
+          ...(current.anthropic ?? {}),
+          ...(updates as Partial<Omit<AnthropicConfig, 'provider'>>),
+        },
+      };
+      saveSettings(updated);
+      return updated;
+    }
+    case 'ollama': {
+      const updated: LLMSettings = {
+        ...current,
+        ollama: {
+          ...(current.ollama ?? {}),
+          ...(updates as Partial<Omit<OllamaConfig, 'provider'>>),
+        },
+      };
+      saveSettings(updated);
+      return updated;
+    }
+    default: {
+      // Should be unreachable due to T extends LLMProvider, but keep a safe fallback
+      const updated: LLMSettings = { ...current };
+      saveSettings(updated);
+      return updated;
+    }
+  }
+};
+
+/**
+ * Set the active provider
+ */
+export const setActiveProvider = (provider: LLMProvider): LLMSettings => {
+  const current = loadSettings();
+  const updated: LLMSettings = {
+    ...current,
+    activeProvider: provider,
+  };
+  saveSettings(updated);
+  return updated;
+};
+
+/**
+ * Get the current provider configuration
+ */
+export const getActiveProviderConfig = (): ProviderConfig | null => {
+  const settings = loadSettings();
+  
+  switch (settings.activeProvider) {
+    case 'openai':
+      if (!settings.openai?.apiKey) {
+        return null;
+      }
+      return {
+        provider: 'openai',
+        ...settings.openai,
+      } as OpenAIConfig;
+      
+    case 'azure-openai':
+      if (!settings.azureOpenAI?.apiKey || !settings.azureOpenAI?.endpoint) {
+        return null;
+      }
+      return {
+        provider: 'azure-openai',
+        ...settings.azureOpenAI,
+      } as AzureOpenAIConfig;
+      
+    case 'gemini':
+      if (!settings.gemini?.apiKey) {
+        return null;
+      }
+      return {
+        provider: 'gemini',
+        ...settings.gemini,
+      } as GeminiConfig;
+      
+    case 'anthropic':
+      if (!settings.anthropic?.apiKey) {
+        return null;
+      }
+      return {
+        provider: 'anthropic',
+        ...settings.anthropic,
+      } as AnthropicConfig;
+      
+    case 'ollama':
+      return {
+        provider: 'ollama',
+        ...settings.ollama,
+      } as OllamaConfig;
+      
+    default:
+      return null;
+  }
+};
+
+/**
+ * Check if the active provider is properly configured
+ */
+export const isProviderConfigured = (): boolean => {
+  return getActiveProviderConfig() !== null;
+};
+
+/**
+ * Clear all settings (reset to defaults)
+ */
+export const clearSettings = (): void => {
+  localStorage.removeItem(STORAGE_KEY);
+};
+
+/**
+ * Get display name for a provider
+ */
+export const getProviderDisplayName = (provider: LLMProvider): string => {
+  switch (provider) {
+    case 'openai':
+      return 'OpenAI';
+    case 'azure-openai':
+      return 'Azure OpenAI';
+    case 'gemini':
+      return 'Google Gemini';
+    case 'anthropic':
+      return 'Anthropic';
+    case 'ollama':
+      return 'Ollama (Local)';
+    default:
+      return provider;
+  }
+};
+
+/**
+ * Get available models for a provider
+ */
+export const getAvailableModels = (provider: LLMProvider): string[] => {
+  switch (provider) {
+    case 'openai':
+      return ['gpt-4.5-preview', 'gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-4', 'gpt-3.5-turbo'];
+    case 'azure-openai':
+      // Azure models depend on deployment, so we show common ones
+      return ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-4', 'gpt-35-turbo'];
+    case 'gemini':
+      return ['gemini-2.0-flash', 'gemini-1.5-pro', 'gemini-1.5-flash', 'gemini-1.0-pro'];
+    case 'anthropic':
+      return ['claude-sonnet-4-20250514', 'claude-3-5-sonnet-20241022', 'claude-3-5-haiku-20241022', 'claude-3-opus-20240229'];
+    case 'ollama':
+      return ['llama3.2', 'llama3.1', 'mistral', 'codellama', 'deepseek-coder'];
+    default:
+      return [];
+  }
+};
+```
+
+## core/mcp/mcp-client.ts
+
+```typescript
+/**
+ * MCP Browser Client
+ * 
+ * WebSocket client that connects to the gitnexus-mcp daemon.
+ * - Sends codebase context (stats, hotspots, folder tree) on connect
+ * - Receives tool calls from external AI agents and executes them
+ * - Emits activity events for real-time monitoring
+ */
+
+/**
+ * Agent color mapping for multi-agent support
+ */
+export const AGENT_COLORS: Record<string, string> = {
+  'cursor': '#a855f7',      // Purple
+  'claude': '#3b82f6',      // Blue  
+  'claude-code': '#3b82f6', // Blue
+  'windsurf': '#22c55e',    // Green
+  'codeium': '#22c55e',     // Green (Windsurf)
+  'unknown': '#6b7280',     // Gray
+};
+
+export function getAgentColor(agentName: string): string {
+  const normalized = agentName.toLowerCase().trim();
+  for (const [key, color] of Object.entries(AGENT_COLORS)) {
+    if (normalized.includes(key)) {
+      return color;
+    }
+  }
+  return AGENT_COLORS.unknown;
+}
+
+export interface ConnectedAgent {
+  name: string;
+  color: string;
+}
+
+export interface MCPMessage {
+  id: string;
+  type?: 'context' | 'tool_call' | 'tool_result' | 'agent_info';
+  method?: string;
+  params?: Record<string, any>;
+  result?: any;
+  error?: { message: string };
+  agentName?: string;
+}
+
+/**
+ * Codebase context to send to daemon
+ */
+export interface CodebaseContext {
+  projectName: string;
+  stats: {
+    fileCount: number;
+    functionCount: number;
+    classCount: number;
+    interfaceCount: number;
+    methodCount: number;
+  };
+  hotspots: Array<{
+    name: string;
+    type: string;
+    filePath: string;
+    connections: number;
+  }>;
+  folderTree: string;
+}
+
+/**
+ * Activity event for real-time monitoring
+ */
+export interface ActivityEvent {
+  id: string;
+  tool: string;
+  params: Record<string, any>;
+  status: 'running' | 'complete' | 'error';
+  result?: any;
+  error?: string;
+  timestamp: number;
+  duration?: number;
+  agentName?: string;
+  agentColor?: string;
+}
+
+type ToolHandler = (params: Record<string, any>) => Promise<any>;
+type ActivityListener = (event: ActivityEvent) => void;
+
+export class MCPBrowserClient {
+  private ws: WebSocket | null = null;
+  private handlers: Map<string, ToolHandler> = new Map();
+  private connectionListeners: Set<(connected: boolean) => void> = new Set();
+  private activityListeners: Set<ActivityListener> = new Set();
+  private activityLog: ActivityEvent[] = [];
+  private pendingContext: CodebaseContext | null = null;
+  private _connectedAgent: ConnectedAgent | null = null;
+  
+  constructor(private port = 54319) {}
+  
+  /**
+   * Connect to the MCP daemon
+   */
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(`ws://localhost:${this.port}`);
+        
+        this.ws.onopen = () => {
+          console.log('[MCP] Connected to daemon');
+          this.notifyConnectionListeners(true);
+          
+          // Send pending context if available
+          if (this.pendingContext) {
+            this.sendContext(this.pendingContext);
+          }
+          
+          resolve();
+        };
+        
+        this.ws.onerror = () => {
+          this.notifyConnectionListeners(false);
+          reject(new Error('Failed to connect to MCP bridge'));
+        };
+        
+        this.ws.onmessage = (event) => {
+          try {
+            const msg: MCPMessage = JSON.parse(event.data);
+            this.handleMessage(msg);
+          } catch (error) {
+            console.error('[MCP] Failed to parse message:', error);
+          }
+        };
+        
+        this.ws.onclose = () => {
+          this.ws = null;
+          this.notifyConnectionListeners(false);
+        };
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+  
+  /**
+   * Send codebase context to daemon
+   * Call this whenever context changes (new repo loaded, etc.)
+   */
+  sendContext(context: CodebaseContext) {
+    this.pendingContext = context;
+    
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      const msg = {
+        id: `ctx_${Date.now()}`,
+        type: 'context',
+        params: context,
+      };
+      this.ws.send(JSON.stringify(msg));
+      console.log('[MCP] Sent context:', context.projectName);
+    }
+  }
+  
+  /**
+   * Handle incoming messages from daemon
+   */
+  private async handleMessage(msg: MCPMessage) {
+    // Handle agent info updates
+    if (msg.type === 'agent_info' && msg.agentName) {
+      this._connectedAgent = {
+        name: msg.agentName,
+        color: getAgentColor(msg.agentName),
+      };
+      console.log('[MCP] Agent connected:', this._connectedAgent);
+      return;
+    }
+    
+    // This is a tool call request from an external agent
+    if (msg.method && msg.id) {
+      const handler = this.handlers.get(msg.method);
+      const startTime = Date.now();
+      
+      // Get agent info from message or use connected agent
+      const agentName = msg.agentName || this._connectedAgent?.name || 'Unknown';
+      const agentColor = getAgentColor(agentName);
+      
+      // Create activity event with agent info
+      const activityEvent: ActivityEvent = {
+        id: msg.id,
+        tool: msg.method,
+        params: msg.params || {},
+        status: 'running',
+        timestamp: startTime,
+        agentName,
+        agentColor,
+      };
+      this.logActivity(activityEvent);
+      
+      if (handler) {
+        try {
+          const result = await handler(msg.params || {});
+          this.send({ id: msg.id, result });
+          
+          // Update activity with success
+          this.updateActivity(msg.id, {
+            status: 'complete',
+            result,
+            duration: Date.now() - startTime,
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : 'Unknown error';
+          this.send({ id: msg.id, error: { message } });
+          
+          // Update activity with error
+          this.updateActivity(msg.id, {
+            status: 'error',
+            error: message,
+            duration: Date.now() - startTime,
+          });
+        }
+      } else {
+        this.send({ 
+          id: msg.id, 
+          error: { message: `Unknown tool: ${msg.method}` } 
+        });
+        
+        // Update activity with error
+        this.updateActivity(msg.id, {
+          status: 'error',
+          error: `Unknown tool: ${msg.method}`,
+          duration: Date.now() - startTime,
+        });
+      }
+    }
+  }
+  
+  /**
+   * Log an activity event
+   */
+  private logActivity(event: ActivityEvent) {
+    this.activityLog.push(event);
+    // Keep max 100 events
+    if (this.activityLog.length > 100) {
+      this.activityLog.shift();
+    }
+    this.notifyActivityListeners(event);
+  }
+  
+  /**
+   * Update an existing activity event
+   */
+  private updateActivity(id: string, updates: Partial<ActivityEvent>) {
+    const event = this.activityLog.find(e => e.id === id);
+    if (event) {
+      Object.assign(event, updates);
+      this.notifyActivityListeners(event);
+    }
+  }
+  
+  /**
+   * Send a message to the daemon
+   */
+  private send(msg: MCPMessage) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+  
+  /**
+   * Register a handler for a tool
+   */
+  registerHandler(method: string, handler: ToolHandler) {
+    this.handlers.set(method, handler);
+  }
+  
+  /**
+   * Listen for connection state changes
+   */
+  onConnectionChange(listener: (connected: boolean) => void) {
+    this.connectionListeners.add(listener);
+    return () => this.connectionListeners.delete(listener);
+  }
+  
+  private notifyConnectionListeners(connected: boolean) {
+    this.connectionListeners.forEach(listener => listener(connected));
+  }
+  
+  /**
+   * Listen for activity events
+   */
+  onActivity(listener: ActivityListener) {
+    this.activityListeners.add(listener);
+    return () => this.activityListeners.delete(listener);
+  }
+  
+  private notifyActivityListeners(event: ActivityEvent) {
+    this.activityListeners.forEach(listener => listener(event));
+  }
+  
+  /**
+   * Get the activity log
+   */
+  getActivityLog(): ActivityEvent[] {
+    return [...this.activityLog];
+  }
+  
+  /**
+   * Clear the activity log
+   */
+  clearActivityLog() {
+    this.activityLog = [];
+  }
+  
+  /**
+   * Check if connected
+   */
+  get isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+  
+  /**
+   * Get the connected agent info
+   */
+  get connectedAgent(): ConnectedAgent | null {
+    return this._connectedAgent;
+  }
+  
+  /**
+   * Disconnect from daemon
+   */
+  disconnect() {
+    this.ws?.close();
+    this.ws = null;
+  }
+}
+
+// Singleton instance
+let mcpClientInstance: MCPBrowserClient | null = null;
+
+export function getMCPClient(): MCPBrowserClient {
+  if (!mcpClientInstance) {
+    mcpClientInstance = new MCPBrowserClient();
+  }
+  return mcpClientInstance;
+}
+```
+
+## core/search/hybrid-search.ts
+
+```typescript
+/**
+ * Hybrid Search with Reciprocal Rank Fusion (RRF)
+ * 
+ * Combines BM25 (keyword) and semantic (embedding) search results.
+ * Uses RRF to merge rankings without needing score normalization.
+ * 
+ * This is the same approach used by Elasticsearch, Pinecone, and other
+ * production search systems.
+ */
+
+import { searchBM25, isBM25Ready, type BM25SearchResult } from './bm25-index';
+import type { SemanticSearchResult } from '../embeddings/types';
+
+/**
+ * RRF constant - standard value used in the literature
+ * Higher values give more weight to lower-ranked results
+ */
+const RRF_K = 60;
+
+export interface HybridSearchResult {
+  filePath: string;
+  score: number;           // RRF score
+  rank: number;            // Final rank
+  sources: ('bm25' | 'semantic')[];  // Which methods found this
+  
+  // Metadata from semantic search (if available)
+  nodeId?: string;
+  name?: string;
+  label?: string;
+  startLine?: number;
+  endLine?: number;
+  
+  // Original scores for debugging
+  bm25Score?: number;
+  semanticScore?: number;
+}
+
+/**
+ * Perform hybrid search combining BM25 and semantic results
+ * 
+ * @param bm25Results - Results from BM25 keyword search
+ * @param semanticResults - Results from semantic/embedding search
+ * @param limit - Maximum results to return
+ * @returns Merged and re-ranked results
+ */
+export const mergeWithRRF = (
+  bm25Results: BM25SearchResult[],
+  semanticResults: SemanticSearchResult[],
+  limit: number = 10
+): HybridSearchResult[] => {
+  const merged = new Map<string, HybridSearchResult>();
+  
+  // Process BM25 results
+  for (let i = 0; i < bm25Results.length; i++) {
+    const r = bm25Results[i];
+    const rrfScore = 1 / (RRF_K + i + 1);  // i+1 because rank starts at 1
+    
+    merged.set(r.filePath, {
+      filePath: r.filePath,
+      score: rrfScore,
+      rank: 0,  // Will be set after sorting
+      sources: ['bm25'],
+      bm25Score: r.score,
+    });
+  }
+  
+  // Process semantic results and merge
+  for (let i = 0; i < semanticResults.length; i++) {
+    const r = semanticResults[i];
+    const rrfScore = 1 / (RRF_K + i + 1);
+    
+    const existing = merged.get(r.filePath);
+    if (existing) {
+      // Found by both methods - add scores
+      existing.score += rrfScore;
+      existing.sources.push('semantic');
+      existing.semanticScore = 1 - r.distance;
+      
+      // Add semantic metadata
+      existing.nodeId = r.nodeId;
+      existing.name = r.name;
+      existing.label = r.label;
+      existing.startLine = r.startLine;
+      existing.endLine = r.endLine;
+    } else {
+      // Only found by semantic
+      merged.set(r.filePath, {
+        filePath: r.filePath,
+        score: rrfScore,
+        rank: 0,
+        sources: ['semantic'],
+        semanticScore: 1 - r.distance,
+        nodeId: r.nodeId,
+        name: r.name,
+        label: r.label,
+        startLine: r.startLine,
+        endLine: r.endLine,
+      });
+    }
+  }
+  
+  // Sort by RRF score descending
+  const sorted = Array.from(merged.values())
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+  
+  // Assign final ranks
+  sorted.forEach((r, i) => {
+    r.rank = i + 1;
+  });
+  
+  return sorted;
+};
+
+/**
+ * Check if hybrid search is available
+ * Requires BM25 index to be built
+ * Note: Semantic search is optional - hybrid works with just BM25 if embeddings aren't ready
+ */
+export const isHybridSearchReady = (): boolean => {
+  return isBM25Ready();
+};
+
+/**
+ * Format hybrid results for LLM consumption
+ */
+export const formatHybridResults = (results: HybridSearchResult[]): string => {
+  if (results.length === 0) {
+    return 'No results found.';
+  }
+  
+  const formatted = results.map((r, i) => {
+    const sources = r.sources.join(' + ');
+    const location = r.startLine ? ` (lines ${r.startLine}-${r.endLine})` : '';
+    const label = r.label ? `${r.label}: ` : 'File: ';
+    const name = r.name || r.filePath.split('/').pop() || r.filePath;
+    
+    return `[${i + 1}] ${label}${name}
+    File: ${r.filePath}${location}
+    Found by: ${sources}
+    Relevance: ${r.score.toFixed(4)}`;
+  });
+  
+  return `Found ${results.length} results:\n\n${formatted.join('\n\n')}`;
+};
+```
+
+## core/search/index.ts
+
+```typescript
+/**
+ * Search Module
+ * 
+ * Exports BM25 indexing and hybrid search functionality.
+ */
+
+export { 
+  buildBM25Index, 
+  searchBM25, 
+  isBM25Ready, 
+  getBM25Stats,
+  clearBM25Index,
+  type BM25SearchResult,
+} from './bm25-index';
+
+export { 
+  mergeWithRRF, 
+  isHybridSearchReady,
+  formatHybridResults,
+  type HybridSearchResult,
+} from './hybrid-search';
+```
+
+## core/tree-sitter/parser-loader.ts
+
+```typescript
+import Parser from 'web-tree-sitter';
+import { SupportedLanguages } from '../../config/supported-languages';
+
+let parser: Parser | null = null;
+
+// Cache the compiled Language objects to avoid fetching/compiling twice
+const languageCache = new Map<string, Parser.Language>();
+
+export const loadParser = async (): Promise<Parser> => {
+    if (parser) return parser;
+
+    await Parser.init({
+        locateFile: (scriptName: string) => {
+            return `/wasm/${scriptName}`;
+        }
+    })
+
+    parser = new Parser();
+    return parser;
+}
+
+// Get the appropriate WASM file based on language and file extension
+const getWasmPath = (language: SupportedLanguages, filePath?: string): string => {
+    // For TypeScript, check if it's a TSX file
+    if (language === SupportedLanguages.TypeScript) {
+        if (filePath?.endsWith('.tsx')) {
+            return '/wasm/typescript/tree-sitter-tsx.wasm';
+        }
+        return '/wasm/typescript/tree-sitter-typescript.wasm';
+    }
+    
+    const languageFileMap: Record<SupportedLanguages, string> = {
+        [SupportedLanguages.JavaScript]: '/wasm/javascript/tree-sitter-javascript.wasm',
+        [SupportedLanguages.TypeScript]: '/wasm/typescript/tree-sitter-typescript.wasm',
+        [SupportedLanguages.Python]: '/wasm/python/tree-sitter-python.wasm',
+    };
+    
+    return languageFileMap[language];
+};
+
+export const loadLanguage = async (language: SupportedLanguages, filePath?: string): Promise<void> => {
+    if (!parser) await loadParser();
+
+    const wasmPath = getWasmPath(language, filePath);
+    
+    // Use wasmPath as cache key to differentiate ts vs tsx
+    if (languageCache.has(wasmPath)) {
+        parser!.setLanguage(languageCache.get(wasmPath)!);
+        return;
+    }
+
+    if (!wasmPath) throw new Error(`Unsupported language: ${language}`);
+    
+    const loadedLanguage = await Parser.Language.load(wasmPath);    
+    languageCache.set(wasmPath, loadedLanguage);
+    parser!.setLanguage(loadedLanguage);
+}
+```
+
+## hooks/useAppState.tsx
+
+```text
+import { createContext, useContext, useState, useCallback, useRef, useEffect, ReactNode } from 'react';
+import * as Comlink from 'comlink';
+import { KnowledgeGraph, GraphNode, NodeLabel } from '../core/graph/types';
+import { PipelineProgress, PipelineResult, deserializePipelineResult } from '../types/pipeline';
+import { createKnowledgeGraph } from '../core/graph/graph';
+import { DEFAULT_VISIBLE_LABELS } from '../lib/constants';
+import type { IngestionWorkerApi } from '../workers/ingestion.worker';
+import type { FileEntry } from '../services/zip';
+import type { EmbeddingProgress, SemanticSearchResult } from '../core/embeddings/types';
+import type { LLMSettings, ProviderConfig, AgentStreamChunk, ChatMessage, ToolCallInfo, MessageStep } from '../core/llm/types';
+import { loadSettings, getActiveProviderConfig } from '../core/llm/settings-service';
+import type { AgentMessage } from '../core/llm/agent';
+import { DEFAULT_VISIBLE_EDGES, type EdgeType } from '../lib/constants';
+
+export type ViewMode = 'onboarding' | 'loading' | 'exploring';
+export type RightPanelTab = 'code' | 'chat';
+export type EmbeddingStatus = 'idle' | 'loading' | 'embedding' | 'indexing' | 'ready' | 'error';
+
+export interface QueryResult {
+  rows: Record<string, any>[];
+  nodeIds: string[];
+  executionTime: number;
+}
+
+// Animation types for graph nodes
+export type AnimationType = 'pulse' | 'ripple' | 'glow';
+
+export interface NodeAnimation {
+  type: AnimationType;
+  startTime: number;
+  duration: number;
+}
+
+// Code reference from AI grounding or user selection
+export interface CodeReference {
+  id: string;
+  filePath: string;
+  startLine?: number;
+  endLine?: number;
+  nodeId?: string;  // Associated graph node ID
+  label?: string;   // File, Function, Class, etc.
+  name?: string;    // Display name
+  source: 'ai' | 'user';  // How it was added
+}
+
+export interface CodeReferenceFocus {
+  filePath: string;
+  startLine?: number;
+  endLine?: number;
+  ts: number;
+}
+
+interface AppState {
+  // View state
+  viewMode: ViewMode;
+  setViewMode: (mode: ViewMode) => void;
+
+  // Graph data
+  graph: KnowledgeGraph | null;
+  setGraph: (graph: KnowledgeGraph | null) => void;
+  fileContents: Map<string, string>;
+  setFileContents: (contents: Map<string, string>) => void;
+
+  // Selection
+  selectedNode: GraphNode | null;
+  setSelectedNode: (node: GraphNode | null) => void;
+
+  // Right Panel (unified Code + Chat)
+  isRightPanelOpen: boolean;
+  setRightPanelOpen: (open: boolean) => void;
+  rightPanelTab: RightPanelTab;
+  setRightPanelTab: (tab: RightPanelTab) => void;
+  openCodePanel: () => void;
+  openChatPanel: () => void;
+
+  // Filters
+  visibleLabels: NodeLabel[];
+  toggleLabelVisibility: (label: NodeLabel) => void;
+  visibleEdgeTypes: EdgeType[];
+  toggleEdgeVisibility: (edgeType: EdgeType) => void;
+
+  // Depth filter (N hops from selection)
+  depthFilter: number | null;
+  setDepthFilter: (depth: number | null) => void;
+
+  // Query state
+  highlightedNodeIds: Set<string>;
+  setHighlightedNodeIds: (ids: Set<string>) => void;
+  // AI highlights (toggable)
+  aiCitationHighlightedNodeIds: Set<string>;
+  aiToolHighlightedNodeIds: Set<string>;
+  blastRadiusNodeIds: Set<string>;
+  isAIHighlightsEnabled: boolean;
+  toggleAIHighlights: () => void;
+  clearAIToolHighlights: () => void;
+  clearBlastRadius: () => void;
+  queryResult: QueryResult | null;
+  setQueryResult: (result: QueryResult | null) => void;
+  clearQueryHighlights: () => void;
+
+  // Node animations (for MCP tool visual feedback)
+  animatedNodes: Map<string, NodeAnimation>;
+  triggerNodeAnimation: (nodeIds: string[], type: AnimationType) => void;
+  clearAnimations: () => void;
+
+  // Progress
+  progress: PipelineProgress | null;
+  setProgress: (progress: PipelineProgress | null) => void;
+
+  // Project info
+  projectName: string;
+  setProjectName: (name: string) => void;
+
+  // Worker API (shared across app)
+  runPipeline: (file: File, onProgress: (p: PipelineProgress) => void) => Promise<PipelineResult>;
+  runPipelineFromFiles: (files: FileEntry[], onProgress: (p: PipelineProgress) => void) => Promise<PipelineResult>;
+  runQuery: (cypher: string) => Promise<any[]>;
+  isDatabaseReady: () => Promise<boolean>;
+
+  // Embedding state
+  embeddingStatus: EmbeddingStatus;
+  embeddingProgress: EmbeddingProgress | null;
+
+  // Embedding methods
+  startEmbeddings: (forceDevice?: 'webgpu' | 'wasm') => Promise<void>;
+  semanticSearch: (query: string, k?: number) => Promise<SemanticSearchResult[]>;
+  semanticSearchWithContext: (query: string, k?: number, hops?: number) => Promise<any[]>;
+  isEmbeddingReady: boolean;
+
+  // Debug/test methods
+  testArrayParams: () => Promise<{ success: boolean; error?: string }>;
+
+  // LLM/Agent state
+  llmSettings: LLMSettings;
+  isSettingsPanelOpen: boolean;
+  setSettingsPanelOpen: (open: boolean) => void;
+  isAgentReady: boolean;
+  isAgentInitializing: boolean;
+  agentError: string | null;
+
+  // Chat state
+  chatMessages: ChatMessage[];
+  isChatLoading: boolean;
+  currentToolCalls: ToolCallInfo[];
+
+  // LLM methods
+  refreshLLMSettings: () => void;
+  initializeAgent: (overrideProjectName?: string) => Promise<void>;
+  sendChatMessage: (message: string) => Promise<void>;
+  clearChat: () => void;
+
+  // Code References Panel
+  codeReferences: CodeReference[];
+  isCodePanelOpen: boolean;
+  setCodePanelOpen: (open: boolean) => void;
+  addCodeReference: (ref: Omit<CodeReference, 'id'>) => void;
+  removeCodeReference: (id: string) => void;
+  clearAICodeReferences: () => void;
+  clearCodeReferences: () => void;
+  codeReferenceFocus: CodeReferenceFocus | null;
+}
+
+const AppStateContext = createContext<AppState | null>(null);
+
+export const AppStateProvider = ({ children }: { children: ReactNode }) => {
+  // View state
+  const [viewMode, setViewMode] = useState<ViewMode>('onboarding');
+
+  // Graph data
+  const [graph, setGraph] = useState<KnowledgeGraph | null>(null);
+  const [fileContents, setFileContents] = useState<Map<string, string>>(new Map());
+
+  // Selection
+  const [selectedNode, setSelectedNode] = useState<GraphNode | null>(null);
+
+  // Right Panel
+  const [isRightPanelOpen, setRightPanelOpen] = useState(false);
+  const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>('code');
+
+  const openCodePanel = useCallback(() => {
+    // Legacy API: used by graph/tree selection.
+    // Code is now shown in the Code References Panel (left of the graph),
+    // so "openCodePanel" just ensures that panel becomes visible when needed.
+    setCodePanelOpen(true);
+  }, []);
+
+  const openChatPanel = useCallback(() => {
+    setRightPanelOpen(true);
+    setRightPanelTab('chat');
+  }, []);
+
+  // Filters
+  const [visibleLabels, setVisibleLabels] = useState<NodeLabel[]>(DEFAULT_VISIBLE_LABELS);
+  const [visibleEdgeTypes, setVisibleEdgeTypes] = useState<EdgeType[]>(DEFAULT_VISIBLE_EDGES);
+
+  // Depth filter
+  const [depthFilter, setDepthFilter] = useState<number | null>(null);
+
+  // Query state
+  const [highlightedNodeIds, setHighlightedNodeIds] = useState<Set<string>>(new Set());
+  const [queryResult, setQueryResult] = useState<QueryResult | null>(null);
+
+  // AI highlights (separate from user/query highlights)
+  const [aiCitationHighlightedNodeIds, setAICitationHighlightedNodeIds] = useState<Set<string>>(new Set());
+  const [aiToolHighlightedNodeIds, setAIToolHighlightedNodeIds] = useState<Set<string>>(new Set());
+  const [blastRadiusNodeIds, setBlastRadiusNodeIds] = useState<Set<string>>(new Set());
+  const [isAIHighlightsEnabled, setAIHighlightsEnabled] = useState(true);
+
+  const toggleAIHighlights = useCallback(() => {
+    setAIHighlightsEnabled(prev => !prev);
+  }, []);
+
+  const clearAIToolHighlights = useCallback(() => {
+    setAIToolHighlightedNodeIds(new Set());
+  }, []);
+
+  const clearBlastRadius = useCallback(() => {
+    setBlastRadiusNodeIds(new Set());
+  }, []);
+
+  const clearQueryHighlights = useCallback(() => {
+    setHighlightedNodeIds(new Set());
+    setQueryResult(null);
+  }, []);
+
+  // Node animations (for MCP tool visual feedback)
+  const [animatedNodes, setAnimatedNodes] = useState<Map<string, NodeAnimation>>(new Map());
+  const animationTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const triggerNodeAnimation = useCallback((nodeIds: string[], type: AnimationType) => {
+    const now = Date.now();
+    const duration = type === 'pulse' ? 2000 : type === 'ripple' ? 3000 : 4000;
+
+    setAnimatedNodes(prev => {
+      const next = new Map(prev);
+      for (const id of nodeIds) {
+        next.set(id, { type, startTime: now, duration });
+      }
+      return next;
+    });
+
+    // Auto-cleanup after duration
+    setTimeout(() => {
+      setAnimatedNodes(prev => {
+        const next = new Map(prev);
+        for (const id of nodeIds) {
+          const anim = next.get(id);
+          if (anim && anim.startTime === now) {
+            next.delete(id);
+          }
+        }
+        return next;
+      });
+    }, duration + 100);
+  }, []);
+
+  const clearAnimations = useCallback(() => {
+    setAnimatedNodes(new Map());
+    if (animationTimerRef.current) {
+      clearInterval(animationTimerRef.current);
+      animationTimerRef.current = null;
+    }
+  }, []);
+
+  // Progress
+  const [progress, setProgress] = useState<PipelineProgress | null>(null);
+
+  // Project info
+  const [projectName, setProjectName] = useState<string>('');
+
+  // Embedding state
+  const [embeddingStatus, setEmbeddingStatus] = useState<EmbeddingStatus>('idle');
+  const [embeddingProgress, setEmbeddingProgress] = useState<EmbeddingProgress | null>(null);
+
+  // LLM/Agent state
+  const [llmSettings, setLLMSettings] = useState<LLMSettings>(loadSettings);
+  const [isSettingsPanelOpen, setSettingsPanelOpen] = useState(false);
+  const [isAgentReady, setIsAgentReady] = useState(false);
+  const [isAgentInitializing, setIsAgentInitializing] = useState(false);
+  const [agentError, setAgentError] = useState<string | null>(null);
+
+  // Chat state
+  const [chatMessages, setChatMessages] = useState<ChatMessage[]>([]);
+  const [isChatLoading, setIsChatLoading] = useState(false);
+  const [currentToolCalls, setCurrentToolCalls] = useState<ToolCallInfo[]>([]);
+
+  // Code References Panel state
+  const [codeReferences, setCodeReferences] = useState<CodeReference[]>([]);
+  const [isCodePanelOpen, setCodePanelOpen] = useState(false);
+  const [codeReferenceFocus, setCodeReferenceFocus] = useState<CodeReferenceFocus | null>(null);
+
+  const normalizePath = useCallback((p: string) => {
+    return p.replace(/\\/g, '/').replace(/^\.?\//, '');
+  }, []);
+
+  const resolveFilePath = useCallback((requestedPath: string): string | null => {
+    const req = normalizePath(requestedPath).toLowerCase();
+    if (!req) return null;
+
+    // Exact match first
+    for (const key of fileContents.keys()) {
+      if (normalizePath(key).toLowerCase() === req) return key;
+    }
+
+    // Ends-with match (best for partial paths like "src/foo.ts")
+    let best: { path: string; score: number } | null = null;
+    for (const key of fileContents.keys()) {
+      const norm = normalizePath(key).toLowerCase();
+      if (norm.endsWith(req)) {
+        const score = 1000 - norm.length; // shorter is better
+        if (!best || score > best.score) best = { path: key, score };
+      }
+    }
+    if (best) return best.path;
+
+    // Segment match fallback
+    const segs = req.split('/').filter(Boolean);
+    for (const key of fileContents.keys()) {
+      const normSegs = normalizePath(key).toLowerCase().split('/').filter(Boolean);
+      let idx = 0;
+      for (const s of segs) {
+        const found = normSegs.findIndex((x, i) => i >= idx && x.includes(s));
+        if (found === -1) { idx = -1; break; }
+        idx = found + 1;
+      }
+      if (idx !== -1) return key;
+    }
+
+    return null;
+  }, [fileContents, normalizePath]);
+
+  const findFileNodeId = useCallback((filePath: string): string | undefined => {
+    if (!graph) return undefined;
+    const target = normalizePath(filePath);
+    const fileNode = graph.nodes.find(
+      (n) => n.label === 'File' && normalizePath(n.properties.filePath) === target
+    );
+    return fileNode?.id;
+  }, [graph, normalizePath]);
+
+  // Code References methods
+  const addCodeReference = useCallback((ref: Omit<CodeReference, 'id'>) => {
+    const id = `ref-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const newRef: CodeReference = { ...ref, id };
+
+    setCodeReferences(prev => {
+      // Don't add duplicates (same file + line range)
+      const isDuplicate = prev.some(r =>
+        r.filePath === ref.filePath &&
+        r.startLine === ref.startLine &&
+        r.endLine === ref.endLine
+      );
+      if (isDuplicate) return prev;
+      return [...prev, newRef];
+    });
+
+    // Auto-open panel when references are added
+    setCodePanelOpen(true);
+
+    // Signal the Code Inspector to focus (scroll + glow) this reference.
+    // This should happen even if the reference already exists (duplicates are ignored),
+    // so it must be separate from the add-to-list behavior.
+    setCodeReferenceFocus({
+      filePath: ref.filePath,
+      startLine: ref.startLine,
+      endLine: ref.endLine,
+      ts: Date.now(),
+    });
+
+    // Track AI highlights separately so they can be toggled off in the UI
+    if (ref.nodeId && ref.source === 'ai') {
+      setAICitationHighlightedNodeIds(prev => new Set([...prev, ref.nodeId!]));
+    }
+  }, []);
+
+  // Remove ONLY AI-provided refs so each new chat response refreshes the Code panel
+  const clearAICodeReferences = useCallback(() => {
+    setCodeReferences(prev => {
+      const removed = prev.filter(r => r.source === 'ai');
+      const kept = prev.filter(r => r.source !== 'ai');
+
+      // Remove citation-based AI highlights for removed refs
+      const removedNodeIds = new Set(removed.map(r => r.nodeId).filter(Boolean) as string[]);
+      if (removedNodeIds.size > 0) {
+        setAICitationHighlightedNodeIds(prevIds => {
+          const next = new Set(prevIds);
+          for (const id of removedNodeIds) next.delete(id);
+          return next;
+        });
+      }
+
+      // Don't auto-close if the user has something selected (top viewer)
+      if (kept.length === 0 && !selectedNode) {
+        setCodePanelOpen(false);
+      }
+      return kept;
+    });
+  }, [queryResult, selectedNode]);
+
+  // Auto-add a code reference when the user selects a node in the graph/tree
+  useEffect(() => {
+    if (!selectedNode) return;
+    // User selection should show in the top "Selected file" viewer,
+    // not be appended to the AI citations list.
+    setCodePanelOpen(true);
+  }, [selectedNode]);
+
+  // Worker (single instance shared across app)
+  const workerRef = useRef<Worker | null>(null);
+  const apiRef = useRef<Comlink.Remote<IngestionWorkerApi> | null>(null);
+
+  useEffect(() => {
+    const worker = new Worker(
+      new URL('../workers/ingestion.worker.ts', import.meta.url),
+      { type: 'module' }
+    );
+    const api = Comlink.wrap<IngestionWorkerApi>(worker);
+    workerRef.current = worker;
+    apiRef.current = api;
+
+    return () => {
+      worker.terminate();
+      workerRef.current = null;
+      apiRef.current = null;
+    };
+  }, []);
+
+  const runPipeline = useCallback(async (
+    file: File,
+    onProgress: (progress: PipelineProgress) => void
+  ): Promise<PipelineResult> => {
+    const api = apiRef.current;
+    if (!api) throw new Error('Worker not initialized');
+
+    const proxiedOnProgress = Comlink.proxy(onProgress);
+    const serializedResult = await api.runPipeline(file, proxiedOnProgress);
+    return deserializePipelineResult(serializedResult, createKnowledgeGraph);
+  }, []);
+
+  const runPipelineFromFiles = useCallback(async (
+    files: FileEntry[],
+    onProgress: (progress: PipelineProgress) => void
+  ): Promise<PipelineResult> => {
+    const api = apiRef.current;
+    if (!api) throw new Error('Worker not initialized');
+
+    const proxiedOnProgress = Comlink.proxy(onProgress);
+    const serializedResult = await api.runPipelineFromFiles(files, proxiedOnProgress);
+    return deserializePipelineResult(serializedResult, createKnowledgeGraph);
+  }, []);
+
+  const runQuery = useCallback(async (cypher: string): Promise<any[]> => {
+    const api = apiRef.current;
+    if (!api) throw new Error('Worker not initialized');
+    return api.runQuery(cypher);
+  }, []);
+
+  const isDatabaseReady = useCallback(async (): Promise<boolean> => {
+    const api = apiRef.current;
+    if (!api) return false;
+    try {
+      return await api.isReady();
+    } catch {
+      return false;
+    }
+  }, []);
+
+  // Embedding methods
+  const startEmbeddings = useCallback(async (forceDevice?: 'webgpu' | 'wasm'): Promise<void> => {
+    const api = apiRef.current;
+    if (!api) throw new Error('Worker not initialized');
+
+    setEmbeddingStatus('loading');
+    setEmbeddingProgress(null);
+
+    try {
+      const proxiedOnProgress = Comlink.proxy((progress: EmbeddingProgress) => {
+        setEmbeddingProgress(progress);
+
+        // Update status based on phase
+        switch (progress.phase) {
+          case 'loading-model':
+            setEmbeddingStatus('loading');
+            break;
+          case 'embedding':
+            setEmbeddingStatus('embedding');
+            break;
+          case 'indexing':
+            setEmbeddingStatus('indexing');
+            break;
+          case 'ready':
+            setEmbeddingStatus('ready');
+            break;
+          case 'error':
+            setEmbeddingStatus('error');
+            break;
+        }
+      });
+
+      await api.startEmbeddingPipeline(proxiedOnProgress, forceDevice);
+    } catch (error: any) {
+      // Check if it's WebGPU not available - let caller handle the dialog
+      if (error?.name === 'WebGPUNotAvailableError' ||
+        error?.message?.includes('WebGPU not available')) {
+        setEmbeddingStatus('idle'); // Reset to idle so user can try again
+      } else {
+        setEmbeddingStatus('error');
+      }
+      throw error;
+    }
+  }, []);
+
+  const semanticSearch = useCallback(async (
+    query: string,
+    k: number = 10
+  ): Promise<SemanticSearchResult[]> => {
+    const api = apiRef.current;
+    if (!api) throw new Error('Worker not initialized');
+    return api.semanticSearch(query, k);
+  }, []);
+
+  const semanticSearchWithContext = useCallback(async (
+    query: string,
+    k: number = 5,
+    hops: number = 2
+  ): Promise<any[]> => {
+    const api = apiRef.current;
+    if (!api) throw new Error('Worker not initialized');
+    return api.semanticSearchWithContext(query, k, hops);
+  }, []);
+
+  const testArrayParams = useCallback(async (): Promise<{ success: boolean; error?: string }> => {
+    const api = apiRef.current;
+    if (!api) return { success: false, error: 'Worker not initialized' };
+    return api.testArrayParams();
+  }, []);
+
+  // LLM methods
+  const refreshLLMSettings = useCallback(() => {
+    setLLMSettings(loadSettings());
+  }, []);
+
+  const initializeAgent = useCallback(async (overrideProjectName?: string): Promise<void> => {
+    const api = apiRef.current;
+    if (!api) {
+      setAgentError('Worker not initialized');
+      return;
+    }
+
+    const config = getActiveProviderConfig();
+    if (!config) {
+      setAgentError('Please configure an LLM provider in settings');
+      return;
+    }
+
+    setIsAgentInitializing(true);
+    setAgentError(null);
+
+    try {
+      // Use override if provided (for fresh loads), fallback to state (for re-init)
+      const effectiveProjectName = overrideProjectName || projectName || 'project';
+      const result = await api.initializeAgent(config, effectiveProjectName);
+      if (result.success) {
+        setIsAgentReady(true);
+        setAgentError(null);
+        if (import.meta.env.DEV) {
+          console.log('✅ Agent initialized successfully');
+        }
+      } else {
+        setAgentError(result.error ?? 'Failed to initialize agent');
+        setIsAgentReady(false);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setAgentError(message);
+      setIsAgentReady(false);
+    } finally {
+      setIsAgentInitializing(false);
+    }
+  }, [projectName]);
+
+  const sendChatMessage = useCallback(async (message: string): Promise<void> => {
+    const api = apiRef.current;
+    if (!api) {
+      setAgentError('Worker not initialized');
+      return;
+    }
+
+    // Refresh Code panel for the new question: keep user-pinned refs, clear old AI citations
+    clearAICodeReferences();
+    // Also clear previous tool-driven AI highlights (highlight_in_graph)
+    clearAIToolHighlights();
+
+    if (!isAgentReady) {
+      // Try to initialize first
+      await initializeAgent();
+      if (!apiRef.current) return;
+    }
+
+    // Add user message
+    const userMessage: ChatMessage = {
+      id: `user-${Date.now()}`,
+      role: 'user',
+      content: message,
+      timestamp: Date.now(),
+    };
+    setChatMessages(prev => [...prev, userMessage]);
+
+    // If embeddings are running and we're currently creating the vector index,
+    // avoid a confusing "Embeddings not ready" error and give a clear wait message.
+    if (embeddingStatus === 'indexing') {
+      const assistantMessage: ChatMessage = {
+        id: `assistant-${Date.now()}`,
+        role: 'assistant',
+        content: 'Wait a moment, vector index is being created.',
+        timestamp: Date.now(),
+      };
+      setChatMessages(prev => [...prev, assistantMessage]);
+      setAgentError(null);
+      setIsChatLoading(false);
+      setCurrentToolCalls([]);
+      return;
+    }
+
+    setIsChatLoading(true);
+    setCurrentToolCalls([]);
+
+    // Prepare message history for agent (convert our format to AgentMessage format)
+    const history: AgentMessage[] = [...chatMessages, userMessage].map(m => ({
+      role: m.role === 'tool' ? 'assistant' : m.role,
+      content: m.content,
+    }));
+
+    // Create placeholder for assistant response
+    const assistantMessageId = `assistant-${Date.now()}`;
+    // Use an ordered steps array to preserve execution order (reasoning → tool → reasoning → tool → answer)
+    const stepsForMessage: MessageStep[] = [];
+    // Keep toolCalls for backwards compat and currentToolCalls state
+    const toolCallsForMessage: ToolCallInfo[] = [];
+    let stepCounter = 0;
+
+    // Helper to update the message with current steps
+    const updateMessage = () => {
+      // Build content from steps for backwards compatibility
+      const contentParts = stepsForMessage
+        .filter(s => s.type === 'reasoning' || s.type === 'content')
+        .map(s => s.content)
+        .filter(Boolean);
+      const content = contentParts.join('\n\n');
+
+      setChatMessages(prev => {
+        const existing = prev.find(m => m.id === assistantMessageId);
+        const newMessage: ChatMessage = {
+          id: assistantMessageId,
+          role: 'assistant' as const,
+          content,
+          steps: [...stepsForMessage],
+          toolCalls: [...toolCallsForMessage],
+          timestamp: existing?.timestamp ?? Date.now(),
+        };
+        if (existing) {
+          return prev.map(m => m.id === assistantMessageId ? newMessage : m);
+        } else {
+          return [...prev, newMessage];
+        }
+      });
+    };
+
+    try {
+      const onChunk = Comlink.proxy((chunk: AgentStreamChunk) => {
+        switch (chunk.type) {
+          case 'reasoning':
+            // LLM's thinking/reasoning - accumulate contiguous reasoning
+            if (chunk.reasoning) {
+              const lastStep = stepsForMessage[stepsForMessage.length - 1];
+              if (lastStep && lastStep.type === 'reasoning') {
+                // Append to existing reasoning step
+                stepsForMessage[stepsForMessage.length - 1] = {
+                  ...lastStep,
+                  content: (lastStep.content || '') + chunk.reasoning,
+                };
+              } else {
+                // Create new reasoning step (after tool calls or at start)
+                stepsForMessage.push({
+                  id: `step-${stepCounter++}`,
+                  type: 'reasoning',
+                  content: chunk.reasoning,
+                });
+              }
+              updateMessage();
+            }
+            break;
+
+          case 'content':
+            // Final answer content - accumulate into contiguous content step
+            if (chunk.content) {
+              // Only append if the LAST step is a content step (contiguous streaming)
+              const lastStep = stepsForMessage[stepsForMessage.length - 1];
+              if (lastStep && lastStep.type === 'content') {
+                // Append to existing content step
+                stepsForMessage[stepsForMessage.length - 1] = {
+                  ...lastStep,
+                  content: (lastStep.content || '') + chunk.content,
+                };
+              } else {
+                // Create new content step (after tool calls or at start)
+                stepsForMessage.push({
+                  id: `step-${stepCounter++}`,
+                  type: 'content',
+                  content: chunk.content,
+                });
+              }
+              updateMessage();
+
+              // Parse inline grounding references and add them to the Code References panel.
+              // Supports: [[file.ts:10-25]] (file refs) and [[Class:View]] (node refs)
+              const currentContentStep = stepsForMessage[stepsForMessage.length - 1];
+              const fullText = (currentContentStep && currentContentStep.type === 'content')
+                ? (currentContentStep.content || '')
+                : '';
+
+              // Pattern 1: File refs - [[path/file.ext]] or [[path/file.ext:line]] or [[path/file.ext:line-line]]
+              // Line numbers are optional
+              const fileRefRegex = /\[\[([a-zA-Z0-9_\-./\\]+\.[a-zA-Z0-9]+)(?::(\d+)(?:[-–](\d+))?)?\]\]/g;
+              let fileMatch: RegExpExecArray | null;
+              while ((fileMatch = fileRefRegex.exec(fullText)) !== null) {
+                const rawPath = fileMatch[1].trim();
+                const startLine1 = fileMatch[2] ? parseInt(fileMatch[2], 10) : undefined;
+                const endLine1 = fileMatch[3] ? parseInt(fileMatch[3], 10) : startLine1;
+
+                const resolvedPath = resolveFilePath(rawPath);
+                if (!resolvedPath) continue;
+
+                const startLine0 = startLine1 !== undefined ? Math.max(0, startLine1 - 1) : undefined;
+                const endLine0 = endLine1 !== undefined ? Math.max(0, endLine1 - 1) : startLine0;
+                const nodeId = findFileNodeId(resolvedPath);
+
+                addCodeReference({
+                  filePath: resolvedPath,
+                  startLine: startLine0,
+                  endLine: endLine0,
+                  nodeId,
+                  label: 'File',
+                  name: resolvedPath.split('/').pop() ?? resolvedPath,
+                  source: 'ai',
+                });
+              }
+
+              // Pattern 2: Node refs - [[Type:Name]] or [[graph:Type:Name]]
+              const nodeRefRegex = /\[\[(?:graph:)?(Class|Function|Method|Interface|File|Folder|Variable|Enum|Type|CodeElement):([^\]]+)\]\]/g;
+              let nodeMatch: RegExpExecArray | null;
+              while ((nodeMatch = nodeRefRegex.exec(fullText)) !== null) {
+                const nodeType = nodeMatch[1];
+                const nodeName = nodeMatch[2].trim();
+
+                // Find node in graph
+                if (!graph) continue;
+                const node = graph.nodes.find(n =>
+                  n.label === nodeType &&
+                  n.properties.name === nodeName
+                );
+                if (!node || !node.properties.filePath) continue;
+
+                const resolvedPath = resolveFilePath(node.properties.filePath);
+                if (!resolvedPath) continue;
+
+                addCodeReference({
+                  filePath: resolvedPath,
+                  startLine: node.properties.startLine ? node.properties.startLine - 1 : undefined,
+                  endLine: node.properties.endLine ? node.properties.endLine - 1 : undefined,
+                  nodeId: node.id,
+                  label: node.label,
+                  name: node.properties.name,
+                  source: 'ai',
+                });
+              }
+            }
+            break;
+
+          case 'tool_call':
+            if (chunk.toolCall) {
+              const tc = chunk.toolCall;
+              toolCallsForMessage.push(tc);
+              // Add tool call as a step (in order with reasoning)
+              stepsForMessage.push({
+                id: `step-${stepCounter++}`,
+                type: 'tool_call',
+                toolCall: tc,
+              });
+              setCurrentToolCalls(prev => [...prev, tc]);
+              updateMessage();
+            }
+            break;
+
+          case 'tool_result':
+            if (chunk.toolCall) {
+              const tc = chunk.toolCall;
+              // Update the tool call status in toolCallsForMessage
+              let idx = toolCallsForMessage.findIndex(t => t.id === tc.id);
+              if (idx < 0) {
+                idx = toolCallsForMessage.findIndex(t => t.name === tc.name && t.status === 'running');
+              }
+              if (idx < 0) {
+                idx = toolCallsForMessage.findIndex(t => t.name === tc.name && !t.result);
+              }
+              if (idx >= 0) {
+                toolCallsForMessage[idx] = {
+                  ...toolCallsForMessage[idx],
+                  result: tc.result,
+                  status: 'completed'
+                };
+              }
+
+              // Also update the tool call in steps
+              const stepIdx = stepsForMessage.findIndex(s =>
+                s.type === 'tool_call' && s.toolCall && (
+                  s.toolCall.id === tc.id ||
+                  (s.toolCall.name === tc.name && s.toolCall.status === 'running')
+                )
+              );
+              if (stepIdx >= 0 && stepsForMessage[stepIdx].toolCall) {
+                stepsForMessage[stepIdx] = {
+                  ...stepsForMessage[stepIdx],
+                  toolCall: {
+                    ...stepsForMessage[stepIdx].toolCall!,
+                    result: tc.result,
+                    status: 'completed',
+                  },
+                };
+              }
+
+              // Update currentToolCalls
+              setCurrentToolCalls(prev => {
+                let targetIdx = prev.findIndex(t => t.id === tc.id);
+                if (targetIdx < 0) {
+                  targetIdx = prev.findIndex(t => t.name === tc.name && t.status === 'running');
+                }
+                if (targetIdx < 0) {
+                  targetIdx = prev.findIndex(t => t.name === tc.name && !t.result);
+                }
+                if (targetIdx >= 0) {
+                  return prev.map((t, i) => i === targetIdx
+                    ? { ...t, result: tc.result, status: 'completed' }
+                    : t
+                  );
+                }
+                return prev;
+              });
+
+              updateMessage();
+
+              // Parse highlight marker from tool results
+              if (tc.result) {
+                const highlightMatch = tc.result.match(/\[HIGHLIGHT_NODES:([^\]]+)\]/);
+                if (highlightMatch) {
+                  const rawIds = highlightMatch[1].split(',').map((id: string) => id.trim()).filter(Boolean);
+                  if (rawIds.length > 0 && graph) {
+                    const matchedIds = new Set<string>();
+                    const graphNodeIds = graph.nodes.map(n => n.id);
+
+                    for (const rawId of rawIds) {
+                      if (graphNodeIds.includes(rawId)) {
+                        matchedIds.add(rawId);
+                      } else {
+                        const found = graphNodeIds.find(gid =>
+                          gid.endsWith(rawId) || gid.endsWith(':' + rawId)
+                        );
+                        if (found) {
+                          matchedIds.add(found);
+                        }
+                      }
+                    }
+
+                    if (matchedIds.size > 0) {
+                      setAIToolHighlightedNodeIds(matchedIds);
+                    }
+                  } else if (rawIds.length > 0) {
+                    setAIToolHighlightedNodeIds(new Set(rawIds));
+                  }
+                }
+
+                // Parse blast radius marker from tool results
+                const blastMatch = tc.result.match(/\[BLAST_RADIUS:([^\]]+)\]/);
+                if (blastMatch) {
+                  const rawIds = blastMatch[1].split(',').map((id: string) => id.trim()).filter(Boolean);
+                  if (rawIds.length > 0 && graph) {
+                    const matchedIds = new Set<string>();
+                    const graphNodeIds = graph.nodes.map(n => n.id);
+
+                    for (const rawId of rawIds) {
+                      if (graphNodeIds.includes(rawId)) {
+                        matchedIds.add(rawId);
+                      } else {
+                        const found = graphNodeIds.find(gid =>
+                          gid.endsWith(rawId) || gid.endsWith(':' + rawId)
+                        );
+                        if (found) {
+                          matchedIds.add(found);
+                        }
+                      }
+                    }
+
+                    if (matchedIds.size > 0) {
+                      setBlastRadiusNodeIds(matchedIds);
+                    }
+                  } else if (rawIds.length > 0) {
+                    setBlastRadiusNodeIds(new Set(rawIds));
+                  }
+                }
+              }
+            }
+            break;
+
+          case 'error':
+            setAgentError(chunk.error ?? 'Unknown error');
+            break;
+
+          case 'done':
+            // Finalize the assistant message - just call updateMessage one more time
+            updateMessage();
+            break;
+        }
+      });
+
+      await api.chatStream(history, onChunk);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setAgentError(message);
+    } finally {
+      setIsChatLoading(false);
+      setCurrentToolCalls([]);
+    }
+  }, [chatMessages, isAgentReady, initializeAgent, resolveFilePath, findFileNodeId, addCodeReference, clearAICodeReferences, clearAIToolHighlights, graph, embeddingStatus]);
+
+  const clearChat = useCallback(() => {
+    setChatMessages([]);
+    setCurrentToolCalls([]);
+    setAgentError(null);
+  }, []);
+
+  const removeCodeReference = useCallback((id: string) => {
+    setCodeReferences(prev => {
+      const ref = prev.find(r => r.id === id);
+      const newRefs = prev.filter(r => r.id !== id);
+
+      // Remove AI citation highlight if this was the only AI reference to that node
+      if (ref?.nodeId && ref.source === 'ai') {
+        const stillReferenced = newRefs.some(r => r.nodeId === ref.nodeId && r.source === 'ai');
+        if (!stillReferenced) {
+          setAICitationHighlightedNodeIds(prev => {
+            const next = new Set(prev);
+            next.delete(ref.nodeId!);
+            return next;
+          });
+        }
+      }
+
+      // Auto-close panel if no references left AND no selection in top viewer
+      if (newRefs.length === 0 && !selectedNode) {
+        setCodePanelOpen(false);
+      }
+
+      return newRefs;
+    });
+  }, [selectedNode]);
+
+  const clearCodeReferences = useCallback(() => {
+    setCodeReferences([]);
+    setCodePanelOpen(false);
+    setCodeReferenceFocus(null);
+  }, []);
+
+  const toggleLabelVisibility = useCallback((label: NodeLabel) => {
+    setVisibleLabels(prev => {
+      if (prev.includes(label)) {
+        return prev.filter(l => l !== label);
+      } else {
+        return [...prev, label];
+      }
+    });
+  }, []);
+
+  const toggleEdgeVisibility = useCallback((edgeType: EdgeType) => {
+    setVisibleEdgeTypes(prev => {
+      if (prev.includes(edgeType)) {
+        return prev.filter(t => t !== edgeType);
+      } else {
+        return [...prev, edgeType];
+      }
+    });
+  }, []);
+
+  const value: AppState = {
+    viewMode,
+    setViewMode,
+    graph,
+    setGraph,
+    fileContents,
+    setFileContents,
+    selectedNode,
+    setSelectedNode,
+    isRightPanelOpen,
+    setRightPanelOpen,
+    rightPanelTab,
+    setRightPanelTab,
+    openCodePanel,
+    openChatPanel,
+    visibleLabels,
+    toggleLabelVisibility,
+    visibleEdgeTypes,
+    toggleEdgeVisibility,
+    depthFilter,
+    setDepthFilter,
+    highlightedNodeIds,
+    setHighlightedNodeIds,
+    aiCitationHighlightedNodeIds,
+    aiToolHighlightedNodeIds,
+    blastRadiusNodeIds,
+    isAIHighlightsEnabled,
+    toggleAIHighlights,
+    clearAIToolHighlights,
+    clearBlastRadius,
+    queryResult,
+    setQueryResult,
+    clearQueryHighlights,
+    // Node animations
+    animatedNodes,
+    triggerNodeAnimation,
+    clearAnimations,
+    progress,
+    setProgress,
+    projectName,
+    setProjectName,
+    runPipeline,
+    runPipelineFromFiles,
+    runQuery,
+    isDatabaseReady,
+    // Embedding state and methods
+    embeddingStatus,
+    embeddingProgress,
+    startEmbeddings,
+    semanticSearch,
+    semanticSearchWithContext,
+    isEmbeddingReady: embeddingStatus === 'ready',
+    // Debug
+    testArrayParams,
+    // LLM/Agent state
+    llmSettings,
+    isSettingsPanelOpen,
+    setSettingsPanelOpen,
+    isAgentReady,
+    isAgentInitializing,
+    agentError,
+    // Chat state
+    chatMessages,
+    isChatLoading,
+    currentToolCalls,
+    // LLM methods
+    refreshLLMSettings,
+    initializeAgent,
+    sendChatMessage,
+    clearChat,
+    // Code References Panel
+    codeReferences,
+    isCodePanelOpen,
+    setCodePanelOpen,
+    addCodeReference,
+    removeCodeReference,
+    clearAICodeReferences,
+    clearCodeReferences,
+    codeReferenceFocus,
+  };
+
+  return (
+    <AppStateContext.Provider value={value}>
+      {children}
+    </AppStateContext.Provider>
+  );
+};
+
+export const useAppState = (): AppState => {
+  const context = useContext(AppStateContext);
+  if (!context) {
+    throw new Error('useAppState must be used within AppStateProvider');
+  }
+  return context;
+};
+```
+
+## hooks/useSigma.ts
+
+```typescript
+import { useRef, useEffect, useCallback, useState } from 'react';
+import Sigma from 'sigma';
+import Graph from 'graphology';
+import FA2Layout from 'graphology-layout-forceatlas2/worker';
+import forceAtlas2 from 'graphology-layout-forceatlas2';
+import noverlap from 'graphology-layout-noverlap';
+import EdgeCurveProgram from '@sigma/edge-curve';
+import { SigmaNodeAttributes, SigmaEdgeAttributes } from '../lib/graph-adapter';
+import type { NodeAnimation } from './useAppState';
+import type { EdgeType } from '../lib/constants';
+// Helper: Parse hex color to RGB
+const hexToRgb = (hex: string): { r: number; g: number; b: number } => {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : { r: 100, g: 100, b: 100 };
+};
+
+// Helper: RGB to hex
+const rgbToHex = (r: number, g: number, b: number): string => {
+  return '#' + [r, g, b].map(x => {
+    const hex = Math.max(0, Math.min(255, Math.round(x))).toString(16);
+    return hex.length === 1 ? '0' + hex : hex;
+  }).join('');
+};
+
+// Dim a color by mixing with dark background (keeps color hint)
+const dimColor = (hex: string, amount: number): string => {
+  const rgb = hexToRgb(hex);
+  const darkBg = { r: 18, g: 18, b: 28 }; // #12121c - dark background
+  return rgbToHex(
+    darkBg.r + (rgb.r - darkBg.r) * amount,
+    darkBg.g + (rgb.g - darkBg.g) * amount,
+    darkBg.b + (rgb.b - darkBg.b) * amount
+  );
+};
+
+// Brighten a color (increase luminosity)
+const brightenColor = (hex: string, factor: number): string => {
+  const rgb = hexToRgb(hex);
+  return rgbToHex(
+    rgb.r + (255 - rgb.r) * (factor - 1) / factor,
+    rgb.g + (255 - rgb.g) * (factor - 1) / factor,
+    rgb.b + (255 - rgb.b) * (factor - 1) / factor
+  );
+};
+
+interface UseSigmaOptions {
+  onNodeClick?: (nodeId: string) => void;
+  onNodeHover?: (nodeId: string | null) => void;
+  onStageClick?: () => void;
+  highlightedNodeIds?: Set<string>;
+  blastRadiusNodeIds?: Set<string>;
+  animatedNodes?: Map<string, NodeAnimation>;
+  visibleEdgeTypes?: EdgeType[];
+}
+
+interface UseSigmaReturn {
+  containerRef: React.RefObject<HTMLDivElement>;
+  sigmaRef: React.RefObject<Sigma | null>;
+  setGraph: (graph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes>) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  resetZoom: () => void;
+  focusNode: (nodeId: string) => void;
+  isLayoutRunning: boolean;
+  startLayout: () => void;
+  stopLayout: () => void;
+  selectedNode: string | null;
+  setSelectedNode: (nodeId: string | null) => void;
+  refreshHighlights: () => void;
+}
+
+// Noverlap for final cleanup - minimal since it starts with good positions
+const NOVERLAP_SETTINGS = {
+  maxIterations: 20,  // Reduced - less cleanup needed
+  ratio: 1.1,
+  margin: 10,
+  expansion: 1.05,
+};
+
+// ForceAtlas2 settings - FAST convergence since nodes start near their parents
+const getFA2Settings = (nodeCount: number) => {
+  const isSmall = nodeCount < 500;
+  const isMedium = nodeCount >= 500 && nodeCount < 2000;
+  const isLarge = nodeCount >= 2000 && nodeCount < 10000;
+  
+  return {
+    // Lower gravity allows folders to stay spread out
+    gravity: isSmall ? 0.8 : isMedium ? 0.5 : isLarge ? 0.3 : 0.15,
+    
+    // Higher scaling ratio = more spread out overall
+    scalingRatio: isSmall ? 15 : isMedium ? 30 : isLarge ? 60 : 100,
+    
+    // LOW slowDown = FASTER movement (converges quicker)
+    slowDown: isSmall ? 1 : isMedium ? 2 : isLarge ? 3 : 5,
+    
+    // Barnes-Hut for performance - use it even on smaller graphs
+    barnesHutOptimize: nodeCount > 200,
+    barnesHutTheta: isLarge ? 0.8 : 0.6,  // Higher = faster but less accurate
+    
+    // These help with clustering while keeping spread
+    strongGravityMode: false,
+    outboundAttractionDistribution: true,
+    linLogMode: false,
+    adjustSizes: true,
+    edgeWeightInfluence: 1,
+  };
+};
+
+// Layout duration - let it run longer for better results
+// Web Worker + WebGL means minimal system impact
+const getLayoutDuration = (nodeCount: number): number => {
+  if (nodeCount > 10000) return 45000;  // 45s for huge graphs
+  if (nodeCount > 5000) return 35000;   // 35s
+  if (nodeCount > 2000) return 30000;   // 30s
+  if (nodeCount > 1000) return 30000;   // 30s
+  if (nodeCount > 500) return 25000;    // 25s
+  return 20000;                         // 20s for small graphs
+};
+
+export const useSigma = (options: UseSigmaOptions = {}): UseSigmaReturn => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const sigmaRef = useRef<Sigma | null>(null);
+  const graphRef = useRef<Graph<SigmaNodeAttributes, SigmaEdgeAttributes> | null>(null);
+  const layoutRef = useRef<FA2Layout | null>(null);
+  const selectedNodeRef = useRef<string | null>(null);
+  const highlightedRef = useRef<Set<string>>(new Set());
+  const blastRadiusRef = useRef<Set<string>>(new Set());
+  const animatedNodesRef = useRef<Map<string, NodeAnimation>>(new Map());
+  const visibleEdgeTypesRef = useRef<EdgeType[] | null>(null);
+  const layoutTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const animationFrameRef = useRef<number | null>(null);
+  const [isLayoutRunning, setIsLayoutRunning] = useState(false);
+  const [selectedNode, setSelectedNodeState] = useState<string | null>(null);
+
+  useEffect(() => {
+    highlightedRef.current = options.highlightedNodeIds || new Set();
+    blastRadiusRef.current = options.blastRadiusNodeIds || new Set();
+    animatedNodesRef.current = options.animatedNodes || new Map();
+    visibleEdgeTypesRef.current = options.visibleEdgeTypes || null;
+    sigmaRef.current?.refresh();
+  }, [options.highlightedNodeIds, options.blastRadiusNodeIds, options.animatedNodes, options.visibleEdgeTypes]);
+
+  // Animation loop for node effects
+  useEffect(() => {
+    if (!options.animatedNodes || options.animatedNodes.size === 0) {
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current);
+        animationFrameRef.current = null;
+      }
+      return;
+    }
+
+    const animate = () => {
+      sigmaRef.current?.refresh();
+      animationFrameRef.current = requestAnimationFrame(animate);
+    };
+
+    animate();
+
+    return () => {
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current);
+        animationFrameRef.current = null;
+      }
+    };
+  }, [options.animatedNodes]);
+
+  const setSelectedNode = useCallback((nodeId: string | null) => {
+    selectedNodeRef.current = nodeId;
+    setSelectedNodeState(nodeId);
+    
+    const sigma = sigmaRef.current;
+    if (!sigma) return;
+    
+    // Tiny camera nudge to force edge refresh (workaround for Sigma edge caching)
+    const camera = sigma.getCamera();
+    const currentRatio = camera.ratio;
+    // Imperceptible zoom change that triggers re-render
+    camera.animate(
+      { ratio: currentRatio * 1.0001 },
+      { duration: 50 }
+    );
+    
+    sigma.refresh();
+  }, []);
+
+  // Initialize Sigma ONCE
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const graph = new Graph<SigmaNodeAttributes, SigmaEdgeAttributes>();
+    graphRef.current = graph;
+
+    const sigma = new Sigma(graph, containerRef.current, {
+      renderLabels: true,
+      labelFont: 'JetBrains Mono, monospace',
+      labelSize: 11,
+      labelWeight: '500',
+      labelColor: { color: '#e4e4ed' },
+      labelRenderedSizeThreshold: 8,
+      labelDensity: 0.1,
+      labelGridCellSize: 70,
+      
+      defaultNodeColor: '#6b7280',
+      defaultEdgeColor: '#2a2a3a',
+      
+      defaultEdgeType: 'curved',
+      edgeProgramClasses: {
+        curved: EdgeCurveProgram,
+      },
+      
+      // Custom hover renderer - dark background instead of white
+      defaultDrawNodeHover: (context, data, settings) => {
+        const label = data.label;
+        if (!label) return;
+        
+        const size = settings.labelSize || 11;
+        const font = settings.labelFont || 'JetBrains Mono, monospace';
+        const weight = settings.labelWeight || '500';
+        
+        context.font = `${weight} ${size}px ${font}`;
+        const textWidth = context.measureText(label).width;
+        
+        const nodeSize = data.size || 8;
+        const x = data.x;
+        const y = data.y - nodeSize - 10;
+        const paddingX = 8;
+        const paddingY = 5;
+        const height = size + paddingY * 2;
+        const width = textWidth + paddingX * 2;
+        const radius = 4;
+        
+        // Dark background pill
+        context.fillStyle = '#12121c';
+        context.beginPath();
+        context.roundRect(x - width / 2, y - height / 2, width, height, radius);
+        context.fill();
+        
+        // Border matching node color
+        context.strokeStyle = data.color || '#6366f1';
+        context.lineWidth = 2;
+        context.stroke();
+        
+        // Label text - light color
+        context.fillStyle = '#f5f5f7';
+        context.textAlign = 'center';
+        context.textBaseline = 'middle';
+        context.fillText(label, x, y);
+        
+        // Also draw a subtle glow ring around the node
+        context.beginPath();
+        context.arc(data.x, data.y, nodeSize + 4, 0, Math.PI * 2);
+        context.strokeStyle = data.color || '#6366f1';
+        context.lineWidth = 2;
+        context.globalAlpha = 0.5;
+        context.stroke();
+        context.globalAlpha = 1;
+      },
+      
+      minCameraRatio: 0.002,
+      maxCameraRatio: 50,
+      hideEdgesOnMove: true,
+      zIndex: true,
+      
+      nodeReducer: (node, data) => {
+        const res = { ...data };
+        
+        if (data.hidden) {
+          res.hidden = true;
+          return res;
+        }
+        
+        const currentSelected = selectedNodeRef.current;
+        const highlighted = highlightedRef.current;
+        const blastRadius = blastRadiusRef.current;
+        const animatedNodes = animatedNodesRef.current;
+        const hasHighlights = highlighted.size > 0;
+        const hasBlastRadius = blastRadius.size > 0;
+        const isQueryHighlighted = highlighted.has(node);
+        const isBlastRadiusNode = blastRadius.has(node);
+        
+        // Apply animation effects FIRST (before other highlighting)
+        const animation = animatedNodes.get(node);
+        if (animation) {
+          const now = Date.now();
+          const elapsed = now - animation.startTime;
+          const progress = Math.min(elapsed / animation.duration, 1);
+          
+          // Calculate animation phase (0-1-0-1... oscillation)
+          const phase = (Math.sin(progress * Math.PI * 4) + 1) / 2;
+          
+          if (animation.type === 'pulse') {
+            // Cyan pulse for search results
+            const sizeMultiplier = 1.5 + phase * 0.8;
+            res.size = (data.size || 8) * sizeMultiplier;
+            res.color = phase > 0.5 ? '#06b6d4' : brightenColor('#06b6d4', 1.3);
+            res.zIndex = 5;
+            res.highlighted = true;
+          } else if (animation.type === 'ripple') {
+            // Red ripple for blast radius
+            const sizeMultiplier = 1.3 + phase * 1.2;
+            res.size = (data.size || 8) * sizeMultiplier;
+            res.color = phase > 0.5 ? '#ef4444' : '#f87171';
+            res.zIndex = 5;
+            res.highlighted = true;
+          } else if (animation.type === 'glow') {
+            // Purple glow for highlight
+            const sizeMultiplier = 1.4 + phase * 0.6;
+            res.size = (data.size || 8) * sizeMultiplier;
+            res.color = phase > 0.5 ? '#a855f7' : '#c084fc';
+            res.zIndex = 5;
+            res.highlighted = true;
+          }
+          
+          return res;
+        }
+        
+        // Blast radius takes priority (red highlighting)
+        if (hasBlastRadius && !currentSelected) {
+          if (isBlastRadiusNode) {
+            res.color = '#ef4444'; // Red for blast radius
+            res.size = (data.size || 8) * 1.8;
+            res.zIndex = 3;
+            res.highlighted = true;
+          } else if (isQueryHighlighted) {
+            // Regular cyan highlight for non-blast-radius nodes
+            res.color = '#06b6d4';
+            res.size = (data.size || 8) * 1.4;
+            res.zIndex = 2;
+            res.highlighted = true;
+          } else {
+            res.color = dimColor(data.color, 0.15);
+            res.size = (data.size || 8) * 0.4;
+            res.zIndex = 0;
+          }
+          return res;
+        }
+        
+        if (hasHighlights && !currentSelected) {
+          if (isQueryHighlighted) {
+            res.color = '#06b6d4';
+            res.size = (data.size || 8) * 1.6;
+            res.zIndex = 2;
+            res.highlighted = true;
+          } else {
+            res.color = dimColor(data.color, 0.2);
+            res.size = (data.size || 8) * 0.5;
+            res.zIndex = 0;
+          }
+          return res;
+        }
+        
+        if (currentSelected) {
+          const graph = graphRef.current;
+          if (graph) {
+            const isSelected = node === currentSelected;
+            const isNeighbor = graph.hasEdge(node, currentSelected) || graph.hasEdge(currentSelected, node);
+            
+            if (isSelected) {
+              res.color = data.color;
+              res.size = (data.size || 8) * 1.8;
+              res.zIndex = 2;
+              res.highlighted = true;
+            } else if (isNeighbor) {
+              res.color = data.color;
+              res.size = (data.size || 8) * 1.3;
+              res.zIndex = 1;
+            } else {
+              res.color = dimColor(data.color, 0.25);
+              res.size = (data.size || 8) * 0.6;
+              res.zIndex = 0;
+            }
+          }
+        }
+        
+        return res;
+      },
+      
+      edgeReducer: (edge, data) => {
+        const res = { ...data };
+        
+        // Check edge type visibility first
+        const visibleTypes = visibleEdgeTypesRef.current;
+        if (visibleTypes && data.relationType) {
+          if (!visibleTypes.includes(data.relationType as EdgeType)) {
+            res.hidden = true;
+            return res;
+          }
+        }
+        
+        const currentSelected = selectedNodeRef.current;
+        const highlighted = highlightedRef.current;
+        const blastRadius = blastRadiusRef.current;
+        const hasHighlights = highlighted.size > 0 || blastRadius.size > 0; // Check BOTH sets
+        
+        if (hasHighlights && !currentSelected) {
+          const graph = graphRef.current;
+          if (graph) {
+            const [source, target] = graph.extremities(edge);
+            
+            // Check if nodes are in EITHER set
+            const isSourceActive = highlighted.has(source) || blastRadius.has(source);
+            const isTargetActive = highlighted.has(target) || blastRadius.has(target);
+            
+            const bothHighlighted = isSourceActive && isTargetActive;
+            const oneHighlighted = isSourceActive || isTargetActive;
+            
+            if (bothHighlighted) {
+              // If both nodes are in blast radius, use red edge
+              if (blastRadius.has(source) && blastRadius.has(target)) {
+                res.color = '#ef4444';
+              } else {
+                res.color = '#06b6d4';
+              }
+              res.size = Math.max(2, (data.size || 1) * 3);
+              res.zIndex = 2;
+            } else if (oneHighlighted) {
+              res.color = dimColor('#06b6d4', 0.4);
+              res.size = 1;
+              res.zIndex = 1;
+            } else {
+              res.color = dimColor(data.color, 0.08);
+              res.size = 0.2;
+              res.zIndex = 0;
+            }
+          }
+          return res;
+        }
+        
+        if (currentSelected) {
+          const graph = graphRef.current;
+          if (graph) {
+            const [source, target] = graph.extremities(edge);
+            const isConnected = source === currentSelected || target === currentSelected;
+            
+            if (isConnected) {
+              res.color = brightenColor(data.color, 1.5);
+              res.size = Math.max(3, (data.size || 1) * 4);
+              res.zIndex = 2;
+            } else {
+              res.color = dimColor(data.color, 0.1);
+              res.size = 0.3;
+              res.zIndex = 0;
+            }
+          }
+        }
+        
+        return res;
+      },
+    });
+
+    sigmaRef.current = sigma;
+
+    sigma.on('clickNode', ({ node }) => {
+      setSelectedNode(node);
+      options.onNodeClick?.(node);
+    });
+
+    sigma.on('clickStage', () => {
+      setSelectedNode(null);
+      options.onStageClick?.();
+    });
+
+    sigma.on('enterNode', ({ node }) => {
+      options.onNodeHover?.(node);
+      if (containerRef.current) {
+        containerRef.current.style.cursor = 'pointer';
+      }
+    });
+
+    sigma.on('leaveNode', () => {
+      options.onNodeHover?.(null);
+      if (containerRef.current) {
+        containerRef.current.style.cursor = 'grab';
+      }
+    });
+
+    return () => {
+      if (layoutTimeoutRef.current) {
+        clearTimeout(layoutTimeoutRef.current);
+      }
+      layoutRef.current?.kill();
+      sigma.kill();
+      sigmaRef.current = null;
+      graphRef.current = null;
+    };
+  }, []);
+
+  // Run ForceAtlas2 layout
+  const runLayout = useCallback((graph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes>) => {
+    const nodeCount = graph.order;
+    if (nodeCount === 0) return;
+
+    // Kill existing
+    if (layoutRef.current) {
+      layoutRef.current.kill();
+      layoutRef.current = null;
+    }
+    if (layoutTimeoutRef.current) {
+      clearTimeout(layoutTimeoutRef.current);
+      layoutTimeoutRef.current = null;
+    }
+
+    // Get settings
+    const inferredSettings = forceAtlas2.inferSettings(graph);
+    const customSettings = getFA2Settings(nodeCount);
+    const settings = { ...inferredSettings, ...customSettings };
+    
+    const layout = new FA2Layout(graph, { settings });
+    
+    layoutRef.current = layout;
+    layout.start();
+    setIsLayoutRunning(true);
+
+    const duration = getLayoutDuration(nodeCount);
+    
+    layoutTimeoutRef.current = setTimeout(() => {
+      if (layoutRef.current) {
+        layoutRef.current.stop();
+        layoutRef.current = null;
+        
+        // Light noverlap cleanup
+        noverlap.assign(graph, NOVERLAP_SETTINGS);
+        sigmaRef.current?.refresh();
+        
+        setIsLayoutRunning(false);
+      }
+    }, duration);
+  }, []);
+
+  const setGraph = useCallback((newGraph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes>) => {
+    const sigma = sigmaRef.current;
+    if (!sigma) return;
+
+    if (layoutRef.current) {
+      layoutRef.current.kill();
+      layoutRef.current = null;
+    }
+    if (layoutTimeoutRef.current) {
+      clearTimeout(layoutTimeoutRef.current);
+      layoutTimeoutRef.current = null;
+    }
+
+    graphRef.current = newGraph;
+    sigma.setGraph(newGraph);
+    setSelectedNode(null);
+
+    runLayout(newGraph);
+    sigma.getCamera().animatedReset({ duration: 500 });
+  }, [runLayout, setSelectedNode]);
+
+  const focusNode = useCallback((nodeId: string) => {
+    const sigma = sigmaRef.current;
+    const graph = graphRef.current;
+    if (!sigma || !graph || !graph.hasNode(nodeId)) return;
+
+    // Skip if already focused on this node (prevents double-click issues)
+    const alreadySelected = selectedNodeRef.current === nodeId;
+    
+    // Set selection state directly (without the camera nudge from setSelectedNode)
+    selectedNodeRef.current = nodeId;
+    setSelectedNodeState(nodeId);
+    
+    // Only animate camera if selecting a new node
+    if (!alreadySelected) {
+      const nodeAttrs = graph.getNodeAttributes(nodeId);
+      sigma.getCamera().animate(
+        { x: nodeAttrs.x, y: nodeAttrs.y, ratio: 0.15 },
+        { duration: 400 }
+      );
+    }
+    
+    sigma.refresh();
+  }, []);
+
+  const zoomIn = useCallback(() => {
+    sigmaRef.current?.getCamera().animatedZoom({ duration: 200 });
+  }, []);
+
+  const zoomOut = useCallback(() => {
+    sigmaRef.current?.getCamera().animatedUnzoom({ duration: 200 });
+  }, []);
+
+  const resetZoom = useCallback(() => {
+    sigmaRef.current?.getCamera().animatedReset({ duration: 300 });
+    setSelectedNode(null);
+  }, [setSelectedNode]);
+
+  const startLayout = useCallback(() => {
+    const graph = graphRef.current;
+    if (!graph || graph.order === 0) return;
+    runLayout(graph);
+  }, [runLayout]);
+
+  const stopLayout = useCallback(() => {
+    if (layoutTimeoutRef.current) {
+      clearTimeout(layoutTimeoutRef.current);
+      layoutTimeoutRef.current = null;
+    }
+    if (layoutRef.current) {
+      layoutRef.current.stop();
+      layoutRef.current = null;
+      
+      const graph = graphRef.current;
+      if (graph) {
+        noverlap.assign(graph, NOVERLAP_SETTINGS);
+        sigmaRef.current?.refresh();
+      }
+      
+      setIsLayoutRunning(false);
+    }
+  }, []);
+
+  const refreshHighlights = useCallback(() => {
+    sigmaRef.current?.refresh();
+  }, []);
+
+  return {
+    containerRef,
+    sigmaRef,
+    setGraph,
+    zoomIn,
+    zoomOut,
+    resetZoom,
+    focusNode,
+    isLayoutRunning,
+    startLayout,
+    stopLayout,
+    selectedNode,
+    setSelectedNode,
+    refreshHighlights,
+  };
+};
+```
+
+## index.css
+
+```css
+@import "tailwindcss";
+
+/* ═══════════════════════════════════════════════════════════════
+   TAILWIND V4 THEME CONFIGURATION
+═══════════════════════════════════════════════════════════════ */
+@theme {
+  /* Backgrounds */
+  --color-void: #06060a;
+  --color-deep: #0a0a10;
+  --color-surface: #101018;
+  --color-elevated: #16161f;
+  --color-hover: #1c1c28;
+
+  /* Borders */
+  --color-border-subtle: #1e1e2a;
+  --color-border-default: #2a2a3a;
+
+  /* Text */
+  --color-text-primary: #e4e4ed;
+  --color-text-secondary: #8888a0;
+  --color-text-muted: #5a5a70;
+
+  /* Accent */
+  --color-accent: #7c3aed;
+  --color-accent-dim: #5b21b6;
+
+  /* Node colors */
+  --color-node-file: #3b82f6;
+  --color-node-folder: #6366f1;
+  --color-node-class: #f59e0b;
+  --color-node-function: #10b981;
+  --color-node-interface: #ec4899;
+  --color-node-import: #6b7280;
+  --color-node-method: #14b8a6;
+
+  /* Fonts */
+  --font-sans: 'Outfit', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+
+  /* Animations */
+  --animate-breathe: breathe 3s ease-in-out infinite;
+  --animate-pulse-glow: pulse-glow 2s ease-in-out infinite;
+  --animate-slide-in: slide-in 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  --animate-slide-up: slide-up 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  --animate-fade-in: fade-in 0.3s ease-out;
+
+  /* Box shadows */
+  --shadow-glow: 0 0 20px rgba(124, 58, 237, 0.4);
+  --shadow-glow-soft: 0 0 40px rgba(124, 58, 237, 0.15);
+}
+
+/* Keyframes */
+@keyframes breathe {
+
+  0%,
+  100% {
+    border-color: #2a2a3a;
+    box-shadow: 0 0 0 0 rgba(124, 58, 237, 0.3);
+  }
+
+  50% {
+    border-color: #7c3aed;
+    box-shadow: 0 0 40px 10px rgba(124, 58, 237, 0.3);
+  }
+}
+
+@keyframes pulse-glow {
+
+  0%,
+  100% {
+    transform: scale(1);
+    box-shadow: 0 0 40px rgba(124, 58, 237, 0.4);
+  }
+
+  50% {
+    transform: scale(1.1);
+    box-shadow: 0 0 80px rgba(124, 58, 237, 0.6);
+  }
+}
+
+@keyframes slide-in {
+  from {
+    opacity: 0;
+    transform: translateX(20px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes slide-up {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   BASE STYLES
+═══════════════════════════════════════════════════════════════ */
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  height: 100%;
+}
+
+body {
+  background-color: var(--color-void);
+  color: var(--color-text-primary);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   CUSTOM SCROLLBAR
+═══════════════════════════════════════════════════════════════ */
+.scrollbar-thin {
+  scrollbar-width: thin;
+  scrollbar-color: #2a2a3a #0a0a10;
+}
+
+.scrollbar-thin::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+.scrollbar-thin::-webkit-scrollbar-track {
+  background: var(--color-deep);
+}
+
+.scrollbar-thin::-webkit-scrollbar-thumb {
+  background: var(--color-border-default);
+  border-radius: 4px;
+}
+
+.scrollbar-thin::-webkit-scrollbar-thumb:hover {
+  background: var(--color-text-muted);
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   CHAT MESSAGE PROSE STYLES
+═══════════════════════════════════════════════════════════════ */
+.chat-prose {
+  font-size: 14px;
+  line-height: 1.75;
+  color: var(--color-text-primary);
+}
+
+/* Spacing between all block elements */
+.chat-prose p,
+.chat-prose ul,
+.chat-prose ol,
+.chat-prose pre,
+.chat-prose blockquote,
+.chat-prose table {
+  margin-top: 0;
+  margin-bottom: 1em;
+}
+
+.chat-prose p:last-child,
+.chat-prose ul:last-child,
+.chat-prose ol:last-child,
+.chat-prose pre:last-child,
+.chat-prose blockquote:last-child {
+  margin-bottom: 0;
+}
+
+.chat-prose strong {
+  font-weight: 600;
+  color: #fff;
+}
+
+.chat-prose em {
+  font-style: italic;
+  color: var(--color-text-secondary);
+}
+
+/* Headers */
+.chat-prose h1,
+.chat-prose h2,
+.chat-prose h3,
+.chat-prose h4 {
+  font-weight: 600;
+  color: #fff;
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+  line-height: 1.3;
+}
+
+.chat-prose h1 {
+  font-size: 1.25em;
+}
+
+.chat-prose h2 {
+  font-size: 1.125em;
+}
+
+.chat-prose h3 {
+  font-size: 1em;
+}
+
+.chat-prose h4 {
+  font-size: 0.875em;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-secondary);
+}
+
+.chat-prose>h1:first-child,
+.chat-prose>h2:first-child,
+.chat-prose>h3:first-child,
+.chat-prose>h4:first-child {
+  margin-top: 0;
+}
+
+/* Lists */
+.chat-prose ul,
+.chat-prose ol {
+  margin: 0.75em 0;
+  padding-left: 1.5em;
+}
+
+.chat-prose li {
+  margin: 0.375em 0;
+  padding-left: 0.25em;
+}
+
+.chat-prose li::marker {
+  color: var(--color-accent);
+}
+
+.chat-prose ul ul,
+.chat-prose ol ol,
+.chat-prose ul ol,
+.chat-prose ol ul {
+  margin: 0.25em 0;
+}
+
+/* Inline code - VS Code style */
+.chat-prose code:not([class*="language-"]) {
+  padding: 0.2em 0.5em;
+  background: rgba(110, 118, 129, 0.2);
+  border-radius: 6px;
+  font-family: var(--font-mono);
+  font-size: 0.875em;
+  color: #e6b450 !important;
+  border: 1px solid rgba(110, 118, 129, 0.3);
+  font-weight: 500;
+}
+
+/* Ensure inline code keeps its color inside links and other elements */
+.chat-prose a code:not([class*="language-"]),
+.chat-prose strong code:not([class*="language-"]),
+.chat-prose em code:not([class*="language-"]) {
+  color: #e6b450 !important;
+}
+
+/* Code blocks */
+.chat-prose pre {
+  margin: 1em 0;
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+/* Blockquotes */
+.chat-prose blockquote {
+  margin: 1em 0;
+  padding: 0.5em 1em;
+  border-left: 3px solid var(--color-accent);
+  background: var(--color-surface);
+  border-radius: 0 6px 6px 0;
+  color: var(--color-text-secondary);
+}
+
+.chat-prose blockquote p {
+  margin: 0;
+}
+
+/* Horizontal rules */
+.chat-prose hr {
+  margin: 1.5em 0;
+  border: none;
+  border-top: 1px solid var(--color-border-subtle);
+}
+
+/* Links - but NOT grounding/citation buttons (those have their own Tailwind styles) */
+.chat-prose a:not(.code-ref-btn) {
+  color: var(--color-accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.chat-prose a:not(.code-ref-btn):hover {
+  color: #a78bfa;
+}
+
+/* Tables */
+.chat-prose table {
+  width: 100%;
+  margin: 1em 0;
+  border-collapse: collapse;
+  font-size: 0.875em;
+}
+
+.chat-prose th,
+.chat-prose td {
+  padding: 0.5em 0.75em;
+  border: 1px solid var(--color-border-subtle);
+  text-align: left;
+}
+
+.chat-prose th {
+  background: var(--color-surface);
+  font-weight: 600;
+  color: var(--color-text-secondary);
+}
+
+.chat-prose tr:nth-child(even) td {
+  background: var(--color-surface);
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   SIGMA.JS CONTAINER
+═══════════════════════════════════════════════════════════════ */
+.sigma-container {
+  width: 100%;
+  height: 100%;
+}
+
+.sigma-container canvas {
+  outline: none;
+}
+```
+
+## main.tsx
+
+```text
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { Buffer } from 'buffer';
+import App from './App';
+import './index.css';
+
+// Polyfill Buffer for isomorphic-git (requires Node.js Buffer API)
+globalThis.Buffer = Buffer;
+
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## services/zip.ts
+
+```typescript
+import JSZip from 'jszip';
+import { shouldIgnorePath } from '../config/ignore-service';
+
+export interface FileEntry {
+    path: string;
+    content: string;
+}
+
+/**
+ * Find the common root folder prefix in ZIP files
+ * GitHub ZIPs have a root folder like "repo-main/" or "repo-branch/"
+ */
+const findRootPrefix = (paths: string[]): string => {
+    if (paths.length === 0) return '';
+    
+    // Get the first path segment of each file
+    const firstSegments = paths
+        .filter(p => p.includes('/'))
+        .map(p => p.split('/')[0]);
+    
+    if (firstSegments.length === 0) return '';
+    
+    // Check if ALL files share the same first segment
+    const firstSegment = firstSegments[0];
+    const allSameRoot = firstSegments.every(s => s === firstSegment);
+    
+    if (allSameRoot) {
+        return firstSegment + '/';
+    }
+    
+    return '';
+};
+
+export const extractZip = async (file: File): Promise<FileEntry[]> => {
+    const zip = await JSZip.loadAsync(file);
+    const files: FileEntry[] = [];
+    const allPaths: string[] = [];
+    
+    // First pass: collect all paths to find common root
+    zip.forEach((relativePath, entry) => {
+        if (!entry.dir) {
+            allPaths.push(relativePath);
+        }
+    });
+    
+    // Find and strip root prefix (e.g., "repo-main/")
+    const rootPrefix = findRootPrefix(allPaths);
+    
+    const promises: Promise<void>[] = [];
+
+    const processEntry = async (relativePath: string, entry: JSZip.JSZipObject) => {
+        if (entry.dir) return;
+        
+        // Strip root prefix if present
+        const normalizedPath = rootPrefix && relativePath.startsWith(rootPrefix)
+            ? relativePath.slice(rootPrefix.length)
+            : relativePath;
+        
+        if (!normalizedPath) return; // Skip if path becomes empty
+        if (shouldIgnorePath(normalizedPath)) return;
+
+        const content = await entry.async('string');
+        
+        files.push({
+            path: normalizedPath,
+            content: content
+        });
+    };
+
+    zip.forEach((relativePath, entry) => {
+        promises.push(processEntry(relativePath, entry));
+    });
+    
+    await Promise.all(promises);
+    
+    return files;
+};
+```
+
+## types/kuzu-wasm.d.ts
+
+```typescript
+declare module 'kuzu-wasm' {
+  export function init(): Promise<void>;
+  export class Database {
+    constructor(path: string);
+    close(): Promise<void>;
+  }
+  export class Connection {
+    constructor(db: Database);
+    query(cypher: string): Promise<QueryResult>;
+    close(): Promise<void>;
+  }
+  export interface QueryResult {
+    hasNext(): Promise<boolean>;
+    getNext(): Promise<any>;
+  }
+  export const FS: {
+    writeFile(path: string, data: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+  };
+  const kuzu: {
+    init: typeof init;
+    Database: typeof Database;
+    Connection: typeof Connection;
+    FS: typeof FS;
+  };
+  export default kuzu;
+}
+```
+
+## types/pipeline.ts
+
+```typescript
+import { GraphNode, GraphRelationship, KnowledgeGraph } from '../core/graph/types';
+import { CommunityDetectionResult } from '../core/ingestion/community-processor';
+
+export type PipelinePhase = 'idle' | 'extracting' | 'structure' | 'parsing' | 'imports' | 'calls' | 'heritage' | 'communities' | 'complete' | 'error';
+
+export interface PipelineProgress {
+  phase: PipelinePhase;
+  percent: number;
+  message: string;
+  detail?: string;
+  stats?: {
+    filesProcessed: number;
+    totalFiles: number;
+    nodesCreated: number;
+  };
+}
+
+// Original result type (used internally in pipeline)
+export interface PipelineResult {
+  graph: KnowledgeGraph;
+  fileContents: Map<string, string>;
+  communityResult?: CommunityDetectionResult;
+}
+
+// Serializable version for Web Worker communication
+// Maps and functions cannot be transferred via postMessage
+export interface SerializablePipelineResult {
+  nodes: GraphNode[];
+  relationships: GraphRelationship[];
+  fileContents: Record<string, string>; // Object instead of Map
+}
+
+// Helper to convert PipelineResult to serializable format
+export const serializePipelineResult = (result: PipelineResult): SerializablePipelineResult => ({
+  nodes: result.graph.nodes,
+  relationships: result.graph.relationships,
+  fileContents: Object.fromEntries(result.fileContents),
+});
+
+// Helper to reconstruct from serializable format (used in main thread)
+export const deserializePipelineResult = (
+  serialized: SerializablePipelineResult,
+  createGraph: () => KnowledgeGraph
+): PipelineResult => {
+  const graph = createGraph();
+  serialized.nodes.forEach(node => graph.addNode(node));
+  serialized.relationships.forEach(rel => graph.addRelationship(rel));
+  
+  return {
+    graph,
+    fileContents: new Map(Object.entries(serialized.fileContents)),
+  };
+};
+```
+
+## vite-env.d.ts
+
+```typescript
+/// <reference types="vite/client" />
+```
+
+## workers/ingestion.worker.ts
+
+```typescript
+import * as Comlink from 'comlink';
+import { runIngestionPipeline, runPipelineFromFiles } from '../core/ingestion/pipeline';
+import { PipelineProgress, SerializablePipelineResult, serializePipelineResult } from '../types/pipeline';
+import { FileEntry } from '../services/zip';
+import {
+  runEmbeddingPipeline,
+  semanticSearch as doSemanticSearch,
+  semanticSearchWithContext as doSemanticSearchWithContext,
+  type EmbeddingProgressCallback,
+} from '../core/embeddings/embedding-pipeline';
+import { isEmbedderReady, disposeEmbedder } from '../core/embeddings/embedder';
+import type { EmbeddingProgress, SemanticSearchResult } from '../core/embeddings/types';
+import type { ProviderConfig, AgentStreamChunk } from '../core/llm/types';
+import { createGraphRAGAgent, streamAgentResponse, type AgentMessage } from '../core/llm/agent';
+import { buildCodebaseContext } from '../core/llm/context-builder';
+import { 
+  buildBM25Index, 
+  searchBM25, 
+  isBM25Ready, 
+  getBM25Stats,
+  mergeWithRRF,
+  type HybridSearchResult,
+} from '../core/search';
+
+// Lazy import for Kuzu to avoid breaking worker if SharedArrayBuffer unavailable
+let kuzuAdapter: typeof import('../core/kuzu/kuzu-adapter') | null = null;
+const getKuzuAdapter = async () => {
+  if (!kuzuAdapter) {
+    kuzuAdapter = await import('../core/kuzu/kuzu-adapter');
+  }
+  return kuzuAdapter;
+};
+
+// Embedding state
+let embeddingProgress: EmbeddingProgress | null = null;
+let isEmbeddingComplete = false;
+
+// File contents state - stores full file contents for grep/read tools
+let storedFileContents: Map<string, string> = new Map();
+
+// Agent state
+let currentAgent: ReturnType<typeof createGraphRAGAgent> | null = null;
+let currentProviderConfig: ProviderConfig | null = null;
+
+/**
+ * Worker API exposed via Comlink
+ * 
+ * Note: The onProgress callback is passed as a Comlink.proxy() from the main thread,
+ * allowing it to be called from the worker and have it execute on the main thread.
+ */
+const workerApi = {
+  /**
+   * Run the ingestion pipeline in the worker thread
+   * @param file - The ZIP file to process
+   * @param onProgress - Proxied callback for progress updates (runs on main thread)
+   * @returns Serializable result (nodes, relationships, fileContents as object)
+   */
+  async runPipeline(
+    file: File,
+    onProgress: (progress: PipelineProgress) => void
+  ): Promise<SerializablePipelineResult> {
+    // Run the actual pipeline
+    const result = await runIngestionPipeline(file, onProgress);
+    
+    // Store file contents for grep/read tools (full content, not truncated)
+    storedFileContents = result.fileContents;
+    
+    // Build BM25 index for keyword search (instant, ~100ms)
+    const bm25DocCount = buildBM25Index(storedFileContents);
+    if (import.meta.env.DEV) {
+      console.log(`🔍 BM25 index built: ${bm25DocCount} documents`);
+    }
+    
+    // Load graph into KuzuDB for querying (optional - gracefully degrades)
+    try {
+      onProgress({
+        phase: 'complete',
+        percent: 98,
+        message: 'Loading into KuzuDB...',
+        stats: {
+          filesProcessed: result.graph.nodeCount,
+          totalFiles: result.graph.nodeCount,
+          nodesCreated: result.graph.nodeCount,
+        },
+      });
+      
+      const kuzu = await getKuzuAdapter();
+      await kuzu.loadGraphToKuzu(result.graph, result.fileContents);
+      
+      if (import.meta.env.DEV) {
+        const stats = await kuzu.getKuzuStats();
+        console.log('KuzuDB loaded:', stats);
+        console.log('📁 Stored', storedFileContents.size, 'files for grep/read tools');
+      }
+    } catch {
+      // KuzuDB is optional - silently continue without it
+    }
+    
+    // Convert to serializable format for transfer back to main thread
+    return serializePipelineResult(result);
+  },
+
+  /**
+   * Execute a Cypher query against the KuzuDB database
+   * @param cypher - The Cypher query string
+   * @returns Query results as an array of objects
+   */
+  async runQuery(cypher: string): Promise<any[]> {
+    const kuzu = await getKuzuAdapter();
+    if (!kuzu.isKuzuReady()) {
+      throw new Error('Database not ready. Please load a repository first.');
+    }
+    return kuzu.executeQuery(cypher);
+  },
+
+  /**
+   * Check if the database is ready for queries
+   */
+  async isReady(): Promise<boolean> {
+    try {
+      const kuzu = await getKuzuAdapter();
+      return kuzu.isKuzuReady();
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Get database statistics
+   */
+  async getStats(): Promise<{ nodes: number; edges: number }> {
+    try {
+      const kuzu = await getKuzuAdapter();
+      return kuzu.getKuzuStats();
+    } catch {
+      return { nodes: 0, edges: 0 };
+    }
+  },
+
+  /**
+   * Run the ingestion pipeline from pre-extracted files (e.g., from git clone)
+   * @param files - Array of file entries with path and content
+   * @param onProgress - Proxied callback for progress updates
+   * @returns Serializable result
+   */
+  async runPipelineFromFiles(
+    files: FileEntry[],
+    onProgress: (progress: PipelineProgress) => void
+  ): Promise<SerializablePipelineResult> {
+    // Skip extraction phase, start from 15%
+    onProgress({
+      phase: 'extracting',
+      percent: 15,
+      message: 'Files ready',
+      stats: { filesProcessed: 0, totalFiles: files.length, nodesCreated: 0 },
+    });
+
+    // Run the pipeline
+    const result = await runPipelineFromFiles(files, onProgress);
+    
+    // Store file contents for grep/read tools (full content, not truncated)
+    storedFileContents = result.fileContents;
+    
+    // Build BM25 index for keyword search (instant, ~100ms)
+    const bm25DocCount = buildBM25Index(storedFileContents);
+    if (import.meta.env.DEV) {
+      console.log(`🔍 BM25 index built: ${bm25DocCount} documents`);
+    }
+    
+    // Load graph into KuzuDB for querying (optional - gracefully degrades)
+    try {
+      onProgress({
+        phase: 'complete',
+        percent: 98,
+        message: 'Loading into KuzuDB...',
+        stats: {
+          filesProcessed: result.graph.nodeCount,
+          totalFiles: result.graph.nodeCount,
+          nodesCreated: result.graph.nodeCount,
+        },
+      });
+      
+      const kuzu = await getKuzuAdapter();
+      await kuzu.loadGraphToKuzu(result.graph, result.fileContents);
+      
+      if (import.meta.env.DEV) {
+        const stats = await kuzu.getKuzuStats();
+        console.log('KuzuDB loaded:', stats);
+        console.log('📁 Stored', storedFileContents.size, 'files for grep/read tools');
+      }
+    } catch {
+      // KuzuDB is optional - silently continue without it
+    }
+    
+    // Convert to serializable format for transfer back to main thread
+    return serializePipelineResult(result);
+  },
+
+  // ============================================================
+  // Embedding Pipeline Methods
+  // ============================================================
+
+  /**
+   * Start the embedding pipeline in the background
+   * Generates embeddings for all embeddable nodes and creates vector index
+   * @param onProgress - Proxied callback for embedding progress updates
+   * @param forceDevice - Force a specific device ('webgpu' or 'wasm')
+   */
+  async startEmbeddingPipeline(
+    onProgress: (progress: EmbeddingProgress) => void,
+    forceDevice?: 'webgpu' | 'wasm'
+  ): Promise<void> {
+    const kuzu = await getKuzuAdapter();
+    if (!kuzu.isKuzuReady()) {
+      throw new Error('Database not ready. Please load a repository first.');
+    }
+
+    // Reset state
+    embeddingProgress = null;
+    isEmbeddingComplete = false;
+
+    const progressCallback: EmbeddingProgressCallback = (progress) => {
+      embeddingProgress = progress;
+      if (progress.phase === 'ready') {
+        isEmbeddingComplete = true;
+      }
+      onProgress(progress);
+    };
+
+    await runEmbeddingPipeline(
+      kuzu.executeQuery, 
+      kuzu.executeWithReusedStatement, 
+      progressCallback,
+      forceDevice ? { device: forceDevice } : {}
+    );
+  },
+
+  /**
+   * Perform semantic search on the codebase
+   * @param query - Natural language search query
+   * @param k - Number of results to return (default: 10)
+   * @param maxDistance - Maximum distance threshold (default: 0.5)
+   * @returns Array of search results ordered by relevance
+   */
+  async semanticSearch(
+    query: string,
+    k: number = 10,
+    maxDistance: number = 0.5
+  ): Promise<SemanticSearchResult[]> {
+    const kuzu = await getKuzuAdapter();
+    if (!kuzu.isKuzuReady()) {
+      throw new Error('Database not ready. Please load a repository first.');
+    }
+    if (!isEmbeddingComplete) {
+      throw new Error('Embeddings not ready. Please wait for embedding pipeline to complete.');
+    }
+
+    return doSemanticSearch(kuzu.executeQuery, query, k, maxDistance);
+  },
+
+  /**
+   * Perform semantic search with graph expansion
+   * Finds similar nodes AND their connections
+   * @param query - Natural language search query
+   * @param k - Number of initial results (default: 5)
+   * @param hops - Number of graph hops to expand (default: 2)
+   * @returns Search results with connected nodes
+   */
+  async semanticSearchWithContext(
+    query: string,
+    k: number = 5,
+    hops: number = 2
+  ): Promise<any[]> {
+    const kuzu = await getKuzuAdapter();
+    if (!kuzu.isKuzuReady()) {
+      throw new Error('Database not ready. Please load a repository first.');
+    }
+    if (!isEmbeddingComplete) {
+      throw new Error('Embeddings not ready. Please wait for embedding pipeline to complete.');
+    }
+
+    return doSemanticSearchWithContext(kuzu.executeQuery, query, k, hops);
+  },
+
+  /**
+   * Perform hybrid search combining BM25 (keyword) and semantic (embedding) search
+   * Uses Reciprocal Rank Fusion (RRF) to merge results
+   * 
+   * @param query - Search query
+   * @param k - Number of results to return (default: 10)
+   * @returns Hybrid search results with RRF scores
+   */
+  async hybridSearch(
+    query: string,
+    k: number = 10
+  ): Promise<HybridSearchResult[]> {
+    if (!isBM25Ready()) {
+      throw new Error('Search index not ready. Please load a repository first.');
+    }
+    
+    // Get BM25 results (always available after ingestion)
+    const bm25Results = searchBM25(query, k * 3);  // Get more for better RRF merge
+    
+    // Get semantic results if embeddings are ready
+    let semanticResults: SemanticSearchResult[] = [];
+    if (isEmbeddingComplete) {
+      try {
+        const kuzu = await getKuzuAdapter();
+        if (kuzu.isKuzuReady()) {
+          semanticResults = await doSemanticSearch(kuzu.executeQuery, query, k * 3, 0.5);
+        }
+      } catch {
+        // Semantic search failed, continue with BM25 only
+      }
+    }
+    
+    // Merge with RRF
+    return mergeWithRRF(bm25Results, semanticResults, k);
+  },
+
+  /**
+   * Check if BM25 search index is ready
+   */
+  isBM25Ready(): boolean {
+    return isBM25Ready();
+  },
+
+  /**
+   * Get BM25 index statistics
+   */
+  getBM25Stats(): { documentCount: number; termCount: number } {
+    return getBM25Stats();
+  },
+
+  /**
+   * Check if the embedding model is loaded and ready
+   */
+  isEmbeddingModelReady(): boolean {
+    return isEmbedderReady();
+  },
+
+  /**
+   * Check if embeddings are fully generated and indexed
+   */
+  isEmbeddingComplete(): boolean {
+    return isEmbeddingComplete;
+  },
+
+  /**
+   * Get current embedding progress
+   */
+  getEmbeddingProgress(): EmbeddingProgress | null {
+    return embeddingProgress;
+  },
+
+  /**
+   * Cleanup embedding model resources
+   */
+  async disposeEmbeddingModel(): Promise<void> {
+    await disposeEmbedder();
+    isEmbeddingComplete = false;
+    embeddingProgress = null;
+  },
+
+  /**
+   * Test if KuzuDB supports array parameters in prepared statements
+   * This is a diagnostic function
+   */
+  async testArrayParams(): Promise<{ success: boolean; error?: string }> {
+    const kuzu = await getKuzuAdapter();
+    if (!kuzu.isKuzuReady()) {
+      return { success: false, error: 'Database not ready' };
+    }
+    return kuzu.testArrayParams();
+  },
+
+  // ============================================================
+  // Graph RAG Agent Methods
+  // ============================================================
+
+  /**
+   * Initialize the Graph RAG agent with a provider configuration
+   * Must be called before using chat methods
+   * @param config - Provider configuration (Azure OpenAI or Gemini)
+   * @param projectName - Name of the loaded project/repository
+   */
+  async initializeAgent(config: ProviderConfig, projectName?: string): Promise<{ success: boolean; error?: string }> {
+    try {
+      const kuzu = await getKuzuAdapter();
+      if (!kuzu.isKuzuReady()) {
+        return { success: false, error: 'Database not ready. Please load a repository first.' };
+      }
+
+      // Create semantic search wrappers that handle embedding state
+      const semanticSearchWrapper = async (query: string, k?: number, maxDistance?: number) => {
+        if (!isEmbeddingComplete) {
+          throw new Error('Embeddings not ready');
+        }
+        return doSemanticSearch(kuzu.executeQuery, query, k, maxDistance);
+      };
+
+      const semanticSearchWithContextWrapper = async (query: string, k?: number, hops?: number) => {
+        if (!isEmbeddingComplete) {
+          throw new Error('Embeddings not ready');
+        }
+        return doSemanticSearchWithContext(kuzu.executeQuery, query, k, hops);
+      };
+
+      // Hybrid search wrapper - combines BM25 + semantic
+      const hybridSearchWrapper = async (query: string, k?: number) => {
+        // Get BM25 results (always available after ingestion)
+        const bm25Results = searchBM25(query, (k ?? 10) * 3);
+        
+        // Get semantic results if embeddings are ready
+        let semanticResults: any[] = [];
+        if (isEmbeddingComplete) {
+          try {
+            semanticResults = await doSemanticSearch(kuzu.executeQuery, query, (k ?? 10) * 3, 0.5);
+          } catch {
+            // Semantic search failed, continue with BM25 only
+          }
+        }
+        
+        // Merge with RRF
+        return mergeWithRRF(bm25Results, semanticResults, k ?? 10);
+      };
+
+      // Use provided projectName, or fallback to 'project' if not provided
+      const resolvedProjectName = projectName || 'project';
+      if (import.meta.env.DEV) {
+        console.log('📛 Project name received:', { provided: projectName, resolved: resolvedProjectName });
+      }
+      
+      let codebaseContext;
+      try {
+        codebaseContext = await buildCodebaseContext(kuzu.executeQuery, resolvedProjectName);
+        if (import.meta.env.DEV) {
+          console.log('📊 Codebase context built:', {
+            files: codebaseContext.stats.fileCount,
+            functions: codebaseContext.stats.functionCount,
+            hotspots: codebaseContext.hotspots.length,
+          });
+        }
+      } catch (err) {
+        console.warn('Failed to build codebase context, proceeding without:', err);
+      }
+
+      currentAgent = createGraphRAGAgent(
+        config,
+        kuzu.executeQuery,
+        semanticSearchWrapper,
+        semanticSearchWithContextWrapper,
+        hybridSearchWrapper,
+        () => isEmbeddingComplete,
+        () => isBM25Ready(),
+        storedFileContents,
+        codebaseContext
+      );
+      currentProviderConfig = config;
+
+      if (import.meta.env.DEV) {
+        console.log('🤖 Graph RAG Agent initialized with provider:', config.provider);
+      }
+
+      return { success: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (import.meta.env.DEV) {
+        console.error('❌ Agent initialization failed:', error);
+      }
+      return { success: false, error: message };
+    }
+  },
+
+  /**
+   * Check if the agent is initialized
+   */
+  isAgentReady(): boolean {
+    return currentAgent !== null;
+  },
+
+  /**
+   * Get current provider info
+   */
+  getAgentProvider(): { provider: string; model: string } | null {
+    if (!currentProviderConfig) return null;
+    return {
+      provider: currentProviderConfig.provider,
+      model: currentProviderConfig.model,
+    };
+  },
+
+  /**
+   * Chat with the Graph RAG agent (streaming)
+   * Sends response chunks via the onChunk callback
+   * @param messages - Conversation history
+   * @param onChunk - Proxied callback for streaming chunks (runs on main thread)
+   */
+  async chatStream(
+    messages: AgentMessage[],
+    onChunk: (chunk: AgentStreamChunk) => void
+  ): Promise<void> {
+    if (!currentAgent) {
+      onChunk({ type: 'error', error: 'Agent not initialized. Please configure an LLM provider first.' });
+      return;
+    }
+
+    try {
+      for await (const chunk of streamAgentResponse(currentAgent, messages)) {
+        onChunk(chunk);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onChunk({ type: 'error', error: message });
+    }
+  },
+
+  /**
+   * Dispose of the current agent
+   */
+  disposeAgent(): void {
+    currentAgent = null;
+    currentProviderConfig = null;
+  },
+};
+
+// Expose the worker API to the main thread
+Comlink.expose(workerApi);
+
+// TypeScript type for the exposed API (used by the hook)
+export type IngestionWorkerApi = typeof workerApi;
+```
+
+## Statistics
+
+- Total Files: 58
+- Total Characters: 532348
+- Total Tokens: 0
diff --git a/gitnexus/src/services/git-clone.ts b/gitnexus/src/services/git-clone.ts
index 8d4627377..b12bc6686 100644
--- a/gitnexus/src/services/git-clone.ts
+++ b/gitnexus/src/services/git-clone.ts
@@ -17,25 +17,22 @@ const initFS = () => {
   return fsName;
 };
 
-// Use public proxy in development, a custom proxy in production
-const USE_OWN_PROXY = !import.meta.env.DEV;
+// Hosted proxy URL - use this for localhost to avoid local proxy issues
+const HOSTED_PROXY_URL = 'https://gitnexus.vercel.app/api/proxy';
 
 /**
- * Custom HTTP client that uses a query-param based proxy in production
- * isomorphic-git's default corsProxy appends URL as path, which doesn't work
- * well with Vercel's file-based routing.
+ * Custom HTTP client that uses a query-param based proxy
+ * - In development (localhost): uses the hosted Vercel proxy for reliability
+ * - In production: uses the local /api/proxy endpoint
  */
 const createProxiedHttp = (): typeof http => {
-  if (!USE_OWN_PROXY) {
-    // In dev, use the public proxy via isomorphic-git's built-in corsProxy option
-    return http;
-  }
-
-  // In production, wrap the HTTP client to use the custom proxy
+  const isDev = typeof window !== 'undefined' && window.location.hostname === 'localhost';
+  
   return {
     request: async (config) => {
-      // Rewrite the URL to go through the proxy
-      const proxyUrl = `/api/proxy?url=${encodeURIComponent(config.url)}`;
+      // Use hosted proxy for localhost, local proxy for production
+      const proxyBase = isDev ? HOSTED_PROXY_URL : '/api/proxy';
+      const proxyUrl = `${proxyBase}?url=${encodeURIComponent(config.url)}`;
       
       // Call the original http.request with the proxied URL
       return http.request({
@@ -100,9 +97,6 @@ export const cloneRepository = async (
       http: httpClient,
       dir,
       url: repoUrl,
-      // Only use corsProxy in dev mode (with public proxy)
-      ...(import.meta.env.DEV ? { corsProxy: 'https://cors.isomorphic-git.org' } : {}),
-      singleBranch: true,
       depth: 1,
       // Auth callback for private repos (PAT stays client-side)
       onAuth: token ? () => ({ username: token, password: 'x-oauth-basic' }) : undefined,
diff --git a/gitnexus/src/types/pipeline.ts b/gitnexus/src/types/pipeline.ts
index ca7218593..0c7fec293 100644
--- a/gitnexus/src/types/pipeline.ts
+++ b/gitnexus/src/types/pipeline.ts
@@ -1,6 +1,7 @@
 import { GraphNode, GraphRelationship, KnowledgeGraph } from '../core/graph/types';
+import { CommunityDetectionResult } from '../core/ingestion/community-processor';
 
-export type PipelinePhase = 'idle' | 'extracting' | 'structure' | 'parsing' | 'imports' | 'calls' | 'heritage' | 'complete' | 'error';
+export type PipelinePhase = 'idle' | 'extracting' | 'structure' | 'parsing' | 'imports' | 'calls' | 'heritage' | 'communities' | 'enriching' | 'complete' | 'error';
 
 export interface PipelineProgress {
   phase: PipelinePhase;
@@ -18,6 +19,7 @@ export interface PipelineProgress {
 export interface PipelineResult {
   graph: KnowledgeGraph;
   fileContents: Map<string, string>;
+  communityResult?: CommunityDetectionResult;
 }
 
 // Serializable version for Web Worker communication
diff --git a/gitnexus/src/workers/ingestion.worker.ts b/gitnexus/src/workers/ingestion.worker.ts
index c1406fb4b..c5fb407f2 100644
--- a/gitnexus/src/workers/ingestion.worker.ts
+++ b/gitnexus/src/workers/ingestion.worker.ts
@@ -11,7 +11,11 @@ import {
 import { isEmbedderReady, disposeEmbedder } from '../core/embeddings/embedder';
 import type { EmbeddingProgress, SemanticSearchResult } from '../core/embeddings/types';
 import type { ProviderConfig, AgentStreamChunk } from '../core/llm/types';
-import { createGraphRAGAgent, streamAgentResponse, type AgentMessage } from '../core/llm/agent';
+import { createGraphRAGAgent, streamAgentResponse, type AgentMessage, createChatModel } from '../core/llm/agent';
+import { SystemMessage } from '@langchain/core/messages';
+import { enrichClustersBatch, ClusterMemberInfo, ClusterEnrichment } from '../core/ingestion/cluster-enricher';
+import { CommunityNode } from '../core/ingestion/community-processor';
+import { PipelineResult } from '../types/pipeline';
 import { buildCodebaseContext } from '../core/llm/context-builder';
 import { 
   buildBM25Index, 
@@ -41,6 +45,11 @@ let storedFileContents: Map<string, string> = new Map();
 // Agent state
 let currentAgent: ReturnType<typeof createGraphRAGAgent> | null = null;
 let currentProviderConfig: ProviderConfig | null = null;
+let currentGraphResult: PipelineResult | null = null;
+
+// Pending enrichment config (for background processing)
+let pendingEnrichmentConfig: ProviderConfig | null = null;
+let enrichmentCancelled = false;
 
 /**
  * Worker API exposed via Comlink
@@ -57,10 +66,14 @@ const workerApi = {
    */
   async runPipeline(
     file: File,
-    onProgress: (progress: PipelineProgress) => void
+    onProgress: (progress: PipelineProgress) => void,
+    clusteringConfig?: ProviderConfig
   ): Promise<SerializablePipelineResult> {
+    // Debug logging
+    console.log('🔧 runPipeline called with clusteringConfig:', !!clusteringConfig);
     // Run the actual pipeline
     const result = await runIngestionPipeline(file, onProgress);
+    currentGraphResult = result;
     
     // Store file contents for grep/read tools (full content, not truncated)
     storedFileContents = result.fileContents;
@@ -96,6 +109,12 @@ const workerApi = {
       // KuzuDB is optional - silently continue without it
     }
     
+    // Store clustering config for background enrichment (runs after graph loads)
+    if (clusteringConfig) {
+      pendingEnrichmentConfig = clusteringConfig;
+      console.log('📋 Clustering config saved for background enrichment');
+    }
+    
     // Convert to serializable format for transfer back to main thread
     return serializePipelineResult(result);
   },
@@ -145,7 +164,8 @@ const workerApi = {
    */
   async runPipelineFromFiles(
     files: FileEntry[],
-    onProgress: (progress: PipelineProgress) => void
+    onProgress: (progress: PipelineProgress) => void,
+    clusteringConfig?: ProviderConfig
   ): Promise<SerializablePipelineResult> {
     // Skip extraction phase, start from 15%
     onProgress({
@@ -157,6 +177,7 @@ const workerApi = {
 
     // Run the pipeline
     const result = await runPipelineFromFiles(files, onProgress);
+    currentGraphResult = result;
     
     // Store file contents for grep/read tools (full content, not truncated)
     storedFileContents = result.fileContents;
@@ -192,6 +213,12 @@ const workerApi = {
       // KuzuDB is optional - silently continue without it
     }
     
+    // Store clustering config for background enrichment (runs after graph loads)
+    if (clusteringConfig) {
+      pendingEnrichmentConfig = clusteringConfig;
+      console.log('📋 Clustering config saved for background enrichment');
+    }
+    
     // Convert to serializable format for transfer back to main thread
     return serializePipelineResult(result);
   },
@@ -235,6 +262,44 @@ const workerApi = {
     );
   },
 
+  /**
+   * Start background cluster enrichment (if pending)
+   * Called after graph loads, runs in background like embeddings
+   * @param onProgress - Progress callback
+   */
+  async startBackgroundEnrichment(
+    onProgress?: (current: number, total: number) => void
+  ): Promise<{ enriched: number; skipped: boolean }> {
+    if (!pendingEnrichmentConfig) {
+      console.log('⏭️ No pending enrichment config, skipping');
+      return { enriched: 0, skipped: true };
+    }
+    
+    console.log('✨ Starting background LLM enrichment...');
+    try {
+      await workerApi.enrichCommunities(
+        pendingEnrichmentConfig,
+        onProgress ?? (() => {})
+      );
+      pendingEnrichmentConfig = null; // Clear after running
+      console.log('✅ Background enrichment completed');
+      return { enriched: 1, skipped: false };
+    } catch (err) {
+      console.error('❌ Background enrichment failed:', err);
+      pendingEnrichmentConfig = null;
+      return { enriched: 0, skipped: false };
+    }
+  },
+
+  /**
+   * Cancel the current enrichment operation
+   */
+  async cancelEnrichment(): Promise<void> {
+    enrichmentCancelled = true;
+    pendingEnrichmentConfig = null;
+    console.log('⏸️ Enrichment cancelled by user');
+  },
+
   /**
    * Perform semantic search on the codebase
    * @param query - Natural language search query
@@ -522,6 +587,137 @@ const workerApi = {
     currentAgent = null;
     currentProviderConfig = null;
   },
+
+  /**
+   * Enrich community clusters using LLM
+   */
+  async enrichCommunities(
+    providerConfig: ProviderConfig,
+    onProgress: (current: number, total: number) => void
+  ): Promise<{ enrichments: Record<string, ClusterEnrichment>, tokensUsed: number }> {
+    if (!currentGraphResult) {
+      throw new Error('No graph loaded. Please ingest a repository first.');
+    }
+
+    const { graph } = currentGraphResult;
+    
+    // Filter for community nodes
+    const communityNodes = graph.nodes
+      .filter(n => n.label === 'Community')
+      .map(n => ({
+        id: n.id,
+        label: 'Community',
+        heuristicLabel: n.properties.heuristicLabel,
+        cohesion: n.properties.cohesion,
+        symbolCount: n.properties.symbolCount
+      } as CommunityNode));
+
+    if (communityNodes.length === 0) {
+      return { enrichments: {}, tokensUsed: 0 };
+    }
+
+    // Build member map: CommunityID -> Member Info
+    const memberMap = new Map<string, ClusterMemberInfo[]>();
+    
+    // Initialize map
+    communityNodes.forEach(c => memberMap.set(c.id, []));
+    
+    // Find all MEMBER_OF edges
+    graph.relationships.forEach(rel => {
+      if (rel.type === 'MEMBER_OF') {
+        const communityId = rel.targetId;
+        const memberId = rel.sourceId; // MEMBER_OF goes Member -> Community
+        
+        if (memberMap.has(communityId)) {
+          // Find member node details
+          const memberNode = graph.nodes.find(n => n.id === memberId);
+          if (memberNode) {
+            memberMap.get(communityId)?.push({
+              name: memberNode.properties.name,
+              filePath: memberNode.properties.filePath,
+              type: memberNode.label
+            });
+          }
+        }
+      }
+    });
+
+    // Create LLM client adapter for LangChain model
+    const chatModel = createChatModel(providerConfig);
+    const llmClient = {
+      generate: async (prompt: string): Promise<string> => {
+        const response = await chatModel.invoke([
+          new SystemMessage('You are a helpful code analysis assistant.'),
+          { role: 'user', content: prompt }
+        ]);
+        return response.content as string;
+      }
+    };
+
+    // Run enrichment
+    const { enrichments, tokensUsed } = await enrichClustersBatch(
+      communityNodes,
+      memberMap,
+      llmClient,
+      5, // Batch size
+      onProgress
+    );
+
+    if (import.meta.env.DEV) {
+      console.log(`✨ Enriched ${enrichments.size} clusters using ~${Math.round(tokensUsed)} tokens`);
+    }
+
+    // Update graph nodes with enrichment data
+    graph.nodes.forEach(node => {
+      if (node.label === 'Community' && enrichments.has(node.id)) {
+        const enrichment = enrichments.get(node.id)!;
+        node.properties.name = enrichment.name; // Update display label
+        node.properties.keywords = enrichment.keywords;
+        node.properties.description = enrichment.description;
+        node.properties.enrichedBy = 'llm';
+      }
+    });
+
+    // Update KuzuDB with new data
+    try {
+      const kuzu = await getKuzuAdapter();
+        
+      onProgress(enrichments.size, enrichments.size); // Done
+      
+      // Update one by one via Cypher (simplest for now)
+      for (const [id, enrichment] of enrichments.entries()) {
+         // Escape strings for Cypher - replace backslash first, then quotes
+         const escapeCypher = (str: string) => str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+         
+         const keywordsStr = JSON.stringify(enrichment.keywords);
+         const descStr = escapeCypher(enrichment.description);
+         const nameStr = escapeCypher(enrichment.name);
+         const escapedId = escapeCypher(id);
+         
+         const query = `
+           MATCH (c:Community {id: "${escapedId}"})
+           SET c.label = "${nameStr}", 
+               c.keywords = ${keywordsStr}, 
+               c.description = "${descStr}",
+               c.enrichedBy = "llm"
+         `;
+         
+         await kuzu.executeQuery(query);
+      }
+      
+    } catch (err) {
+      console.error('Failed to update KuzuDB with enrichment:', err);
+    }
+    
+    // Convert Map to Record for serialization
+    const enrichmentsRecord: Record<string, ClusterEnrichment> = {};
+    for (const [id, val] of enrichments.entries()) {
+      enrichmentsRecord[id] = val;
+    }
+     
+    return { enrichments: enrichmentsRecord, tokensUsed };
+  
+  },
 };
 
 // Expose the worker API to the main thread