feat: add LOD graph rendering and performance optimizations

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

@@ -21,9 +21,33 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------- | ---------------------------------------------------------------- |
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--db <type>` | Database backend: `kuzu` (default) or `neptune` |
+| `--neptune-endpoint <host>` | Neptune cluster endpoint hostname |
+| `--neptune-region <region>` | AWS region (falls back to `AWS_REGION`) |
+| `--neptune-port <port>` | Neptune HTTP port (default: 8182) |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
 
+#### Neptune environment variables
+
+Instead of CLI flags, you can set these env vars:
+
+| Variable | Effect |
+| -------- | ------ |
+| `GITNEXUS_DB_TYPE` | `kuzu` (default) or `neptune` |
+| `GITNEXUS_NEPTUNE_ENDPOINT` | Neptune cluster endpoint hostname |
+| `GITNEXUS_NEPTUNE_REGION` | AWS region (falls back to `AWS_REGION`) |
+| `GITNEXUS_NEPTUNE_PORT` | Neptune HTTP port (default: 8182) |
+
+```bash
+# Full Neptune example
+npx gitnexus analyze --db neptune \
+  --neptune-endpoint your-cluster.us-east-1.neptune.amazonaws.com \
+  --neptune-region us-east-1
+```
+
+Neptune requires valid AWS credentials (env vars, instance profile, or SSO). See [Neptune setup guide](../docs/neptune-setup.md) for VPC, IAM, and security group configuration.
+
 ### status — Check index freshness
 
 ```bash
@@ -80,3 +104,5 @@ Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_
 - **"Not inside a git repository"**: Run from a directory inside a git repo
 - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
 - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
+- **"Neptune endpoint is required"**: Pass `--neptune-endpoint <host>` or set `GITNEXUS_NEPTUNE_ENDPOINT`
+- **Neptune connection timeout**: Neptune requires VPC network access — use a VPN, VPC peering, or SSH tunnel. See [Neptune setup guide](../docs/neptune-setup.md)

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

@@ -62,3 +62,20 @@ Lightweight reads (~100-500 tokens) for navigation:
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
 RETURN caller.name, caller.filePath
 ```
+
+## Backend Differences
+
+The backend (KuzuDB or Neptune) is selected at index time via `--db`. Once indexed, all MCP tools work transparently — you don't need to change queries.
+
+| Capability       | KuzuDB (default)                        | Neptune                                  |
+| ---------------- | --------------------------------------- | ---------------------------------------- |
+| `query` tool     | BM25 + semantic hybrid search           | CONTAINS predicate (no FTS indexes)      |
+| `cypher` tool    | KuzuDB Cypher dialect                   | openCypher (Neptune-compatible subset)   |
+| `context`        | Identical                               | Identical                                |
+| `impact`         | Identical                               | Identical                                |
+| `rename`         | Identical                               | Identical                                |
+| `detect_changes` | Identical                               | Identical                                |
+| Latency          | Local disk (~ms)                        | Network round-trip (~10-50ms)            |
+| Embeddings       | Supported                               | Not supported (v1)                       |
+
+See [Neptune setup guide](../docs/neptune-setup.md) for configuration details.

.claude/skills/gitnexus/perfection-loop/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: perfection-loop
+description: "Adversarial code review loop with independent BUILDER and CRITIC subagents using ultra-think deep reasoning. Use when the user asks to review code quality, review their changes, or wants thorough adversarial review before committing. Triggers on: 'review this code', 'review my changes', 'perfection loop', 'quality review', 'ultra-think review', 'make this bulletproof', 'is this solid?'. This is NOT for reviewing external PRs (use gitnexus-pr-review for that) — this is for reviewing YOUR code with an auto-fix loop."
+---
+
+# Perfection Loop — Adversarial Code Review
+
+Two independent subagents — a **CRITIC** that tears code apart and a **BUILDER** that fixes every issue — loop until the code passes all quality gates.
+
+Why subagents? The CRITIC has fresh context and no knowledge of the BUILDER's reasoning. This prevents self-mercy — the failure mode where an author reviews their own code and rationalizes away problems.
+
+## When to Use
+
+- "Review this code" / "Review my changes"
+- "Ultra-think review" / "Ultra-think this code"
+- "Is this implementation solid?"
+- "Make this bulletproof"
+- "Perfection loop on X"
+- After completing a feature, before committing
+
+> For reviewing **external PRs** (someone else's code, GitHub PRs), use `gitnexus-pr-review` instead.
+
+## The Loop
+
+```
+ITERATION = 1
+
+REPEAT {
+  1. Determine scope: what files/changes to review
+     - If user specifies files → those files
+     - If on a branch → git diff against base branch
+     - If staged changes → staged files only
+
+  2. Spawn CRITIC subagent → reviews code, produces structured review
+     → Returns verdict: BLOCK or PASS
+
+  3. Show CRITIC review to user
+
+  4. IF verdict = BLOCK:
+     → Spawn BUILDER subagent with the CRITIC's review
+     → BUILDER fixes all CRITICAL and HIGH issues
+     → Summarize fixes to user
+     → ITERATION += 1
+     → GOTO 2
+
+  5. IF verdict = PASS:
+     → Spawn CRITIC one more time (FINAL PASS)
+     → FINAL PASS specifically hunts for things it missed
+     → IF finds issues → GOTO 4
+     → IF clean → DELIVER
+
+} UNTIL delivered OR iteration > 5
+```
+
+If not converging after 5 iterations, deliver with remaining issues listed and let the user decide.
+
+## Spawning the CRITIC
+
+Use the Agent tool. The CRITIC is a **read-only research agent** — it must NOT edit files.
+
+**Prompt template** (replace `{CHANGED_FILES}`, `{DIFF}`, `{N}`):
+
+```
+You are a HOSTILE senior code reviewer. You find every issue. You are NOT the author.
+You do NOT care about the author's feelings. You care about correctness, security,
+performance, and simplicity.
+
+## ULTRA-THINK MODE
+
+Before writing your review, think DEEPLY and ADVERSARIALLY. Do not skim. Do not
+pattern-match on superficial cues. For every piece of code you review:
+
+1. TRACE every code path mentally — what happens on the happy path AND every
+   unhappy path (null, empty, error, timeout, concurrent access)?
+2. THINK BACKWARD — if this code ships, what bug report arrives in 3 months?
+   What incident page fires at 3am? What does the post-mortem say?
+3. THINK FORWARD — if a new developer adds a third variant (new DB backend,
+   new language, new provider), where does this design force them to make
+   changes? How many files? How easy is it to forget one?
+4. THINK LATERALLY — how does this code interact with OTHER code in the same
+   codebase? What assumptions does it make about shared state, ordering,
+   initialization?
+
+Spend the majority of your reasoning on this analysis. The review format is
+just the structured output of your deep thinking — not a substitute for it.
+
+## What to Review
+
+Changed files:
+{CHANGED_FILES}
+
+Diff:
+{DIFF}
+
+## Instructions
+
+1. Read each changed file in full (use the Read tool).
+2. Read the quality gates at:
+   .claude/skills/gitnexus/perfection-loop/references/quality-gates.md
+3. Check every file against every applicable gate.
+4. Use gitnexus_impact on key changed symbols to understand blast radius.
+5. Produce your review in the EXACT format below.
+
+## Review Format
+
+╔══════════════════════════════════════════════════════════╗
+║  INNER CRITIC — REVIEW ITERATION {N}                    ║
+╠══════════════════════════════════════════════════════════╣
+
+── CRITICAL ──────────────────────────────────────────────
+
+1. <file:line> — <what's wrong>
+   WHY it's critical: <impact>
+   FIX: <specific fix, not "consider doing X">
+
+── HIGH ──────────────────────────────────────────────────
+
+2. <file:line> — <what's wrong>
+   WHY it matters: <drift/perf/completeness risk>
+   FIX: <specific fix>
+
+── MEDIUM ────────────────────────────────────────────────
+
+3. <description>
+   FIX: <specific fix>
+
+── LOW ───────────────────────────────────────────────────
+
+4. <description>
+
+── SIMPLICITY CHECK ──────────────────────────────────────
+
+Could this be simpler?  [YES/NO]
+If YES: <what to simplify and why>
+
+── VERDICT ───────────────────────────────────────────────
+
+TOTAL ISSUES: X (C critical, H high, M medium, L low)
+DECISION: [BLOCK — must fix] or [PASS — ship it]
+
+Only PASS when: 0 critical, 0 high, AND simplicity check = NO
+╚══════════════════════════════════════════════════════════╝
+
+## Rules
+
+- Be SPECIFIC: file names, line numbers, code snippets. Vague criticism is useless.
+- Be EXHAUSTIVE: find ALL issues, not just the first one.
+- SIMPLICITY CHECK is mandatory. If YES → HIGH-severity issue.
+- Check interactions between existing code and new code.
+- On FINAL PASS: engage ULTRA-THINK at maximum depth. Assume you missed something.
+  Go beyond surface checks — mentally execute the code:
+  - Interactions between fixes (did fixing A introduce B?)
+  - Edge cases at boundaries (empty inputs, max sizes, concurrent access)
+  - What "obviously works" but doesn't under load or concurrent access
+  - What happens when external deps (DB, API, network) are slow/down
+  - What state is shared? What races exist? What ordering assumptions break?
+  - If this code runs 10,000 times/day for a year, what fails first?
+
+Do NOT edit any files. Report only.
+```
+
+## Spawning the BUILDER
+
+Use the Agent tool. The BUILDER **edits files** to fix issues.
+
+**Prompt template** (replace `{REVIEW}`):
+
+```
+You are a BUILDER. You receive a code review and your ONLY job is to fix every issue.
+
+## Review to Address
+
+{REVIEW}
+
+## Rules
+
+- Fix ALL CRITICAL and HIGH issues. No exceptions. No deferral.
+- Fix MEDIUM issues when the fix is straightforward.
+- LOW issues: fix only if trivial.
+- Do NOT add TODO comments. Do NOT say "fix later". Fix it NOW.
+- SIMPLICITY RATCHET: if the CRITIC said "simplify", your fix MUST result in
+  LESS code, fewer files, fewer abstractions. Not more wrappers.
+- Before editing any symbol, run gitnexus_impact to check blast radius.
+- After all fixes, run gitnexus_detect_changes() to verify scope.
+- End with a brief summary: what you changed, which issues you fixed, and any
+  MEDIUM/LOW issues you intentionally left (with reasoning).
+```
+
+## Escalation Rules
+
+These prevent the loop from gaming itself:
+
+1. **NO SELF-MERCY** — The CRITIC imagines three reviewers: a security engineer, a systems architect who hates drift, and a performance engineer who profiles everything. All three must be satisfied.
+
+2. **REGRESSION WATCH** — After each fix pass, the CRITIC specifically checks whether fixing issue A introduced issue B. Regression = CRITICAL.
+
+3. **SIMPLICITY RATCHET** — If the CRITIC says "simplify" and the BUILDER adds MORE code, that's an automatic HIGH. Simplification means less code, fewer abstractions, fewer files.
+
+4. **NO DEFERRED FIXES** — No `TODO`, no `// HACK`, no `// should be refactored`. If you know it's wrong, fix it now. The loop exists precisely for this.
+
+5. **ULTRA-THINK on FINAL PASS** — The CRITIC must deeply consider: concurrent access, 10x input size, slow/down external dependencies, feature interactions between changes.
+
+## Delivery
+
+When the CRITIC's final verdict is PASS:
+
+```
+=== PERFECTION LOOP COMPLETE ===
+
+ITERATIONS: N
+ISSUES FOUND AND FIXED: X total across all iterations
+CRITICAL FIXES: <brief list of the most important things caught>
+SIMPLICITY SCORE: <1-5, where 5 = can't make it simpler>
+
+[summary of final state]
+```
+
+This tells the user the code survived N rounds of adversarial review and everything found was fixed — not deferred, not noted, FIXED.

.claude/skills/gitnexus/perfection-loop/references/quality-gates.md

@@ -0,0 +1,106 @@
+# Quality Gates
+
+The CRITIC checks every applicable gate. CRITICAL and HIGH gates are blocking.
+
+## Gate 1 — Backward Compatibility (CRITICAL)
+
+- Existing code paths UNTOUCHED — new features are additive
+- Old data/config formats still work (missing fields default gracefully)
+- No function signatures changed without backward-compatible overload
+- No existing imports/exports removed or renamed
+- Regression test: "If I revert my diff, does the original build identically?"
+
+## Gate 2 — Security (CRITICAL)
+
+- NO string interpolation in queries (SQL, Cypher, GraphQL) — parameterized always
+- Escaping correct for target dialect (Cypher: `''` not `\'`, SQL: prepared statements)
+- No hardcoded secrets, credentials, or API keys
+- User input validated/sanitized at every entry point
+- Auth on every new endpoint
+- Error messages don't leak internals (stack traces, DB schema, file paths)
+
+## Gate 3 — Architectural Fit (HIGH)
+
+- ONE dispatch layer — no duplicated dispatch across parallel code paths
+- Interfaces enforced — every impl goes through the interface
+- No copy-paste between modules — shared logic in one place
+- No `if (isBackendX) ... else if (isBackendY)` in business logic — polymorphic dispatch
+- Read AND write path go through the same abstraction
+- Third-variant test: adding a new backend/provider/language touches ≤2 files
+
+## Gate 4 — Completeness (HIGH)
+
+- Every defined function is CALLED somewhere — no dead code
+- Every code path is reachable
+- Every feature described in comments actually works end-to-end
+- Cache exists → invalidation wired up and called
+- ALL endpoints correct for ALL config variants, not just the default
+- Error paths produce useful, actionable messages — not empty arrays or silent catches
+
+## Gate 5 — Performance (HIGH)
+
+- No full-scan on large text fields (`CONTAINS` on source code = timeout)
+- Batch sizes reasonable (not 25 when 100-250 works, not 10000 causing OOM)
+- No per-request construction of expensive objects — reuse/pool
+- Timeouts configured, timeout errors handled gracefully
+- Index creation syntax compatible with target engine
+- Parallelizable async ops use `Promise.all`, not sequential `await`
+
+## Gate 6 — Simplicity (HIGH)
+
+- No abstraction without at least 2 concrete users — don't pre-abstract
+- Could achieve the same result with fewer files, classes, or indirections?
+- Not building for a problem that doesn't exist yet (YAGNI)
+- Every layer of indirection has a concrete benefit TODAY
+- If asked "why is this abstracted?" there's a real answer beyond "it might be useful"
+
+## Gate 7 — Type Safety & Clean Code (MEDIUM)
+
+- No `as any` casts when a proper type exists
+- No `(obj as unknown as {...})` hacks — expose proper public getters
+- Private fields needing external access → public getter/property
+- Parameters and return types explicitly typed
+- No unused imports or variables
+- Consistent naming conventions
+
+## Gate 8 — Separation of Concerns (MEDIUM)
+
+- Unrelated changes NOT bundled
+- Each file has one clear responsibility
+- UI components free of business logic
+- Config separate from implementation
+- Tests test ONE thing, named to match
+
+## Gate 9 — UX & Observability (LOW)
+
+- UI shows active backend/mode/state
+- Loading, error, and empty states all handled
+- Long operations have progress/status output
+- Logs structured and useful
+
+## Gate 10 — LLM/Agent Compatibility (LOW, skip if N/A)
+
+- Tested with multiple LLM dialects (LLMs default to most popular syntax)
+- Query error messages include fix hints for retry guidance
+- Malformed LLM output handled gracefully (parse errors, wrong syntax)
+
+---
+
+## Anti-Patterns — Instant CRITICAL
+
+If the CRITIC spots any of these, flag immediately:
+
+| # | Anti-pattern | Example | Gate |
+|---|---|---|---|
+| 1 | Silent swallow | `.catch(() => [])`, empty `catch {}` | 4 |
+| 2 | Duplicated dispatch | Same if/else branching in two files | 3 |
+| 3 | Query interpolation | `` WHERE x = '${val}' `` | 2 |
+| 4 | Dead exports | `export function X()` never imported | 4 |
+| 5 | `as any` | Casting when proper type exists | 7 |
+| 6 | Unrelated changes | Removing unrelated code in same PR | 8 |
+| 7 | Partial coverage | Endpoint works for variant A, crashes on B | 4 |
+| 8 | Per-request construction | `new DbAdapter()` in request handler | 5 |
+| 9 | Full-scan text match | `CONTAINS` on source code, no size guard | 5 |
+| 10 | Misleading comments | "critical for perf" but code silently fails | 4 |
+| 11 | Premature abstraction | Interface with 1 impl, no plan for 2nd | 6 |
+| 12 | Copy-paste adapter | `getDbConfigFromEntry()` duplicates `getDbConfig()` | 3 |

AGENTS.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **GitNexus** (2273 symbols, 5419 relationships, 174 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **GitNexus** (3816 symbols, 8368 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.