resources implemented and agents.md and skills updated to use it

2026-08-28 05:25:25 +00:00 · 2026-02-05 05:13:48 +05:30 · 2026-02-05 05:13:48 +05:30 · 6c3c47edc3
commit 6c3c47edc3
parent d1e53d7030
19 changed files with 1219 additions and 675 deletions
--- a/.claude/skills/gitnexus/debugging/SKILL.md
+++ b/.claude/skills/gitnexus/debugging/SKILL.md
@ -0,0 +1,103 @@
+---
+name: gitnexus-debugging
+description: Trace bugs through call chains using knowledge graph
+---
+
+# Debugging with GitNexus
+
+## Quick Start
+```
+1. gitnexus_search({query})                → Find code related to error
+2. gitnexus_explore({name, type: "symbol"}) → Get callers and callees
+3. READ gitnexus://process/{name}           → Trace execution flow
+```
+
+## When to Use
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "Debug the payment issue"
+
+## Workflow Checklist
+```
+Bug Investigation:
+- [ ] Understand the symptom (error message, behavior)
+- [ ] gitnexus_search to find related code
+- [ ] Identify the suspect function
+- [ ] gitnexus_explore to see callers/callees
+- [ ] READ gitnexus://process/{name} if suspect is in a process
+- [ ] READ gitnexus://schema for Cypher query help
+- [ ] gitnexus_cypher for custom traces
+```
+
+## Resource Reference
+
+### gitnexus://schema
+Graph schema for writing Cypher queries:
+```yaml
+nodes: [Function, Class, Method, File, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS]
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://process/{name}
+Trace execution flow to find where bug might occur:
+```yaml
+name: CheckoutFlow
+trace:
+  1: handleCheckout
+  2: validateCart
+  3: processPayment  ← bug here?
+  4: sendConfirmation
+```
+
+## Tool Reference
+
+### gitnexus_search
+Find code related to error or symptom:
+```
+gitnexus_search({query: "payment validation error", depth: "full"})
+```
+
+### gitnexus_explore
+Get symbol context:
+```
+gitnexus_explore({name: "validatePayment", type: "symbol"})
+→ Callers: processCheckout, webhookHandler
+→ Callees: verifyCard, fetchRates
+```
+
+### gitnexus_cypher
+Custom graph queries for tracing:
+```cypher
+// Trace call chain (2 hops)
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_search({query: "payment error handling"})
+   → validatePayment, handlePaymentError, PaymentException
+
+2. gitnexus_explore({name: "validatePayment", type: "symbol"})
+   → Callees: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://process/CheckoutFlow
+   → Step 3: validatePayment → calls external API
+
+4. Root cause: fetchRates calls external API without proper timeout
+```
+
+## Debugging Patterns
+
+| Symptom | Approach |
+|---------|----------|
+| Error message | Search for error text, trace throw sites |
+| Wrong return value | Trace data flow through callees |
+| Intermittent failure | Look for external calls, timeouts |
+| Performance issue | Find hot paths via callers count |
--- a/.claude/skills/gitnexus/exploring/SKILL.md
+++ b/.claude/skills/gitnexus/exploring/SKILL.md
@ -0,0 +1,111 @@
+---
+name: gitnexus-exploring
+description: Navigate unfamiliar code using GitNexus knowledge graph
+---
+
+# Exploring Codebases
+
+## Quick Start
+```
+1. READ gitnexus://context        → Get codebase overview (~150 tokens)
+2. READ gitnexus://clusters       → See all functional clusters
+3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
+```
+
+## When to Use
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+
+## Workflow Checklist
+```
+Exploration Progress:
+- [ ] READ gitnexus://context for codebase overview
+- [ ] READ gitnexus://clusters to list all clusters
+- [ ] Identify the relevant cluster by name
+- [ ] READ gitnexus://cluster/{name} for cluster details
+- [ ] Use gitnexus_explore for specific symbols
+```
+
+## Resource Reference
+
+### gitnexus://context
+Codebase overview. **Read first.**
+```yaml
+project: my-app
+stats:
+  files: 42
+  symbols: 918
+  clusters: 12
+  processes: 45
+tools_available: [search, explore, impact, overview, cypher]
+resources_available: [clusters, processes, cluster/{name}, process/{name}]
+```
+
+### gitnexus://clusters
+All functional clusters with cohesion scores.
+```yaml
+clusters:
+  - name: "Auth"
+    symbols: 47
+    cohesion: 92%
+  - name: "Database"
+    symbols: 32
+    cohesion: 88%
+```
+
+### gitnexus://cluster/{name}
+Members of a specific cluster.
+```yaml
+name: Auth
+symbols: 47
+cohesion: 92%
+members:
+  - name: validateUser
+    type: Function
+    file: src/auth/validator.ts
+```
+
+### gitnexus://process/{name}
+Full execution trace.
+```yaml
+name: LoginFlow
+type: cross_community
+steps:
+  1: handleLogin (src/auth/handler.ts)
+  2: validateUser (src/auth/validator.ts)
+  3: createSession (src/auth/session.ts)
+```
+
+## Tool Reference (When Resources Aren't Enough)
+
+### gitnexus_explore
+For detailed symbol context with callers/callees:
+```
+gitnexus_explore({name: "validateUser", type: "symbol"})
+→ Callers: loginHandler, apiMiddleware
+→ Callees: checkToken, getUserById
+```
+
+### gitnexus_search
+For finding code by query:
+```
+gitnexus_search({query: "payment validation", depth: "full"})
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://context
+   → 918 symbols, 12 clusters
+
+2. READ gitnexus://clusters
+   → Clusters: Auth, Payment, Database, API...
+
+3. READ gitnexus://cluster/Payment
+   → Members: processPayment, validateCard, PaymentService
+
+4. READ gitnexus://process/CheckoutFlow
+   → handleCheckout → validateCart → processPayment → sendConfirmation
+```
--- a/.claude/skills/gitnexus/impact-analysis/SKILL.md
+++ b/.claude/skills/gitnexus/impact-analysis/SKILL.md
@ -0,0 +1,113 @@
+---
+name: gitnexus-impact-analysis
+description: Analyze blast radius before making code changes
+---
+
+# Impact Analysis
+
+## Quick Start
+```
+1. gitnexus_impact({target, direction: "upstream"}) → What depends on this
+2. READ gitnexus://clusters                         → Check affected areas
+3. READ gitnexus://processes                        → Affected execution flows
+```
+
+## When to Use
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+
+## Understanding Output
+
+| Depth | Risk Level | Meaning |
+|-------|-----------|---------|
+| d=1 | WILL BREAK | Direct callers/importers |
+| d=2 | LIKELY AFFECTED | Indirect dependencies |
+| d=3 | MAY NEED TESTING | Transitive effects |
+
+## Workflow Checklist
+```
+Impact Analysis:
+- [ ] gitnexus_impact(target, "upstream") to find dependents
+- [ ] READ gitnexus://clusters to understand affected areas
+- [ ] Check high-confidence (>0.8) dependencies first
+- [ ] Count affected clusters (cross-cutting = higher risk)
+- [ ] If >10 processes affected, consider splitting change
+```
+
+## Resource Reference
+
+### gitnexus://clusters
+Check which clusters might be affected:
+```yaml
+clusters:
+  - name: Auth
+    symbols: 47
+  - name: API
+    symbols: 32
+```
+
+### gitnexus://processes
+Find which processes touch the target:
+```yaml
+processes:
+  - name: LoginFlow
+    type: cross_community
+    steps: 5
+```
+
+## Tool Reference
+
+### gitnexus_impact
+Analyze blast radius:
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+
+→ Affected Processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM (3 processes)
+```
+
+## Risk Assessment
+
+| Affected | Risk |
+|----------|------|
+| <5 symbols, 1 cluster | LOW |
+| 5-15 symbols, 1-2 clusters | MEDIUM |
+| >15 symbols or 3+ clusters | HIGH |
+| Critical path (auth, payments) | CRITICAL |
+
+## Pre-Change Checklist
+```
+Before Committing:
+- [ ] Run impact analysis
+- [ ] Review all d=1 (WILL BREAK) items
+- [ ] Verify test coverage for affected processes
+- [ ] If risk > MEDIUM, get code review
+- [ ] If cross-cluster, coordinate with other teams
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware
+   → d=2: authRouter, sessionManager
+
+2. READ gitnexus://clusters
+   → Auth and API clusters affected
+
+3. Decision: 2 direct callers, 2 clusters = MEDIUM risk
+```
--- a/.claude/skills/gitnexus/refactoring/SKILL.md
+++ b/.claude/skills/gitnexus/refactoring/SKILL.md
@ -0,0 +1,118 @@
+---
+name: gitnexus-refactoring
+description: Plan safe refactors using blast radius and dependency mapping
+---
+
+# Refactoring with GitNexus
+
+## Quick Start
+```
+1. gitnexus_impact({target, direction: "upstream"}) → Map all dependents
+2. READ gitnexus://schema                           → Understand graph structure
+3. gitnexus_cypher                                  → Find all references
+```
+
+## When to Use
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Refactor without breaking things"
+
+## Checklists
+
+### Rename Symbol
+```
+Rename Refactoring:
+- [ ] gitnexus_impact(oldName, "upstream") — find all callers
+- [ ] gitnexus_search(oldName) — find string literals
+- [ ] Check for reflection/dynamic references
+- [ ] Update in order: interface → implementation → usages
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+```
+Extract Module:
+- [ ] gitnexus_explore(target, "symbol") — map dependencies
+- [ ] gitnexus_impact(target, "upstream") — find callers
+- [ ] READ gitnexus://cluster/{name} — check cohesion
+- [ ] Define new module interface
+- [ ] Update imports across affected files
+```
+
+### Split Function
+```
+Split Function:
+- [ ] gitnexus_explore(target, "symbol") — understand callees
+- [ ] Group related logic
+- [ ] gitnexus_impact — verify callers won't break
+- [ ] Create new functions
+- [ ] Update callers
+```
+
+## Resource Reference
+
+### gitnexus://schema
+Graph structure for Cypher queries:
+```yaml
+nodes: [Function, Class, Method, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, MEMBER_OF]
+
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://cluster/{name}
+Check if extraction preserves cohesion:
+```yaml
+name: Payment
+cohesion: 92%
+members: [processPayment, validateCard, PaymentService]
+```
+
+## Tool Reference
+
+### Finding all references
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath
+ORDER BY caller.filePath
+```
+
+### Finding imports of a module
+```cypher
+MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"})
+RETURN importer.name, importer.filePath
+```
+
+## Example: Safely Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → loginHandler, apiMiddleware, testUtils
+
+2. gitnexus_search({query: "validateUser"})
+   → Found in: config.json (dynamic reference!)
+
+3. READ gitnexus://processes
+   → LoginFlow, TokenRefresh, APIGateway
+
+4. Plan update order:
+   1. Update declaration in auth.ts
+   2. Update config.json string reference
+   3. Update loginHandler
+   4. Update apiMiddleware
+   5. Run tests for LoginFlow, TokenRefresh
+```
+
+## Refactoring Safety Rules
+
+| Risk Factor | Mitigation |
+|-------------|------------|
+| Many callers (>5) | Update in small batches |
+| Cross-cluster | Coordinate with other teams |
+| String references | Search for dynamic usage |
+| Reflection | Check for dynamic invocation |
+| External exports | May break downstream repos |
--- a/.cursor/plans/enhance_523ca41c.plan.md
+++ b/.cursor/plans/enhance_523ca41c.plan.md
@ -1,239 +0,0 @@
---
-name: Enhance
-overview: Restructure GitNexus LLM tools to leverage clusters and processes for better code understanding. Remove unused highlight tool, add new tools (explore, overview), enhance existing tools with cluster/process context, and improve impact analysis reliability.
-todos: []
---
-
-# Enhanced LLM Tools with Cluster and Process Integration
-
-## Summary
-
-Consolidate GitNexus from 6 tools to **7 focused tools** that leverage the pre-computed clusters (Communities) and processes for richer context. Remove the highlight tool, add `explore` and `overview` tools, and enhance `search` and `blastRadius` with cluster/process awareness.
-
-## Final Tool Set
-
-| Tool | Status | Purpose ||------|--------|---------|| `search` | Enhance | Hybrid search + group results by process/cluster || `grep` | Keep | Regex pattern search || `read` | Keep | Read file content || `explore` | **New** | Deep dive on one symbol, cluster, or process || `overview` | **New** | Codebase map (all clusters + all processes) || `impact` | Enhance | Rename from blastRadius, add process/cluster context, increase limits || `cypher` | Keep | Raw graph queries || `highlight` | **Remove** | No longer needed |
-
-## Architecture
-
-```mermaid
-flowchart TD
-    subgraph tools [LLM Tools Layer]
-        search[search]
-        grep[grep]
-        read[read]
-        explore[explore]
-        overview[overview]
-        impact[impact]
-        cypher[cypher]
-    end
-    
-    subgraph graph [Knowledge Graph]
-        nodes[Nodes: File, Function, Class...]
-        communities[Community Nodes]
-        processes[Process Nodes]
-        edges[CodeRelation Edges]
-        memberOf[MEMBER_OF Edges]
-        stepIn[STEP_IN_PROCESS Edges]
-    end
-    
-    search --> edges
-    search --> communities
-    search --> processes
-    explore --> communities
-    explore --> processes
-    explore --> memberOf
-    explore --> stepIn
-    overview --> communities
-    overview --> processes
-    impact --> edges
-    impact --> communities
-    impact --> processes
-    cypher --> graph
-```
-
-
-
-## File Changes
-
-### 1. Remove Highlight Tool
-
-**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)
-
- Delete the `highlightTool` definition (lines ~395-414)
- Remove `highlightTool` from the returned array (line ~862)
- Remove highlight marker logic from `blastRadius` output (line ~814-816)
-
-**File:** [gitnexus/src/core/llm/agent.ts](gitnexus/src/core/llm/agent.ts)
-
- Remove highlight references from system prompt (lines 70, 77)
- Update tool list in prompt to reflect new tools
-
-**File:** [gitnexus/src/core/llm/types.ts](gitnexus/src/core/llm/types.ts)
-
- Remove `'highlight'` from `AgentStreamChunk.type` union (line 180)
- Remove `highlightNodeIds` property (line 187-188)
-
-### 2. Add `explore` Tool
-
-**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)New tool that auto-detects target type and returns comprehensive context:
-
-```typescript
-explore({
-  target: string,  // Name of symbol, cluster, or process
-  type?: 'symbol' | 'cluster' | 'process'  // Optional, auto-detected
-})
-```
-
-**Functionality:**
-
- For symbols: Query node, get MEMBER_OF cluster, get STEP_IN_PROCESS processes, get 1-hop connections
- For clusters: Query Community node, get members via MEMBER_OF, get processes that touch this cluster
- For processes: Query Process node, get steps via STEP_IN_PROCESS with step order, get clusters touched
-
-**Cypher queries needed:**
-
-```cypher
-- Symbol cluster membership
-MATCH (s {name: $name})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
-RETURN c.label, c.description
-
-- Symbol process participation  
-MATCH (s {name: $name})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
-RETURN p.label, r.step, p.stepCount
-
-- Process steps in order
-MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {id: $processId})
-RETURN s.name, s.filePath, r.step
-ORDER BY r.step
-```
-
-
-
-### 3. Add `overview` Tool
-
-**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)New tool that returns codebase structure:
-
-```typescript
-overview()  // No parameters
-```
-
-**Functionality:**
-
- Query all Community nodes with member counts
- Query all Process nodes with step counts and types
- Calculate cluster dependencies (cross-cluster CALLS)
- Identify critical paths (most connected processes)
-
-**Output format:**
-
-```javascript
-CLUSTERS (N total):
-| Cluster | Symbols | Cohesion | Description |
-...
-
-PROCESSES (N total):
-| Process | Steps | Type | Clusters |
-...
-
-CRITICAL PATHS:
- LoginFlow (45 edges)
-...
-```
-
-
-
-### 4. Enhance `search` Tool
-
-**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)Modify existing search to group results by process:**Current:** Returns flat list with 1-hop connections**Enhanced:** Groups results by process, adds cluster context**Changes:**
-
- After hybrid search, query STEP_IN_PROCESS for each result
- Group results by process ID
- Sort processes by number of matching results (relevance)
- Add cluster label for each result via MEMBER_OF query
- Keep 1-hop connections as optional detail
-
-**New parameter:**
-
-```typescript
-search({
-  query: string,
-  groupByProcess?: boolean,  // Default: true
-  limit?: number
-})
-```
-
-
-
-### 5. Enhance `impact` Tool (rename from blastRadius)
-
-**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)**Rename:** `blastRadiusTool` to `impactTool`**Enhancements:**
-
-1. Increase LIMIT clauses: 100 to 300 (depth 1), 100 to 200 (depth 2), 50 to 100 (depth 3)
-2. Add affected processes section (query STEP_IN_PROCESS for all affected symbols)
-3. Add affected clusters section (query MEMBER_OF for all affected symbols)
-4. Add risk assessment summary
-5. Surface confidence scores more prominently (group by confidence level)
-
-**New output sections:**
-
-```javascript
-AFFECTED PROCESSES:
- LoginFlow - BROKEN at step 2
- SignupFlow - BROKEN at step 1
-
-AFFECTED CLUSTERS:
- Authentication (direct)
- API Routes (indirect)
-
-RISK: CRITICAL
- N direct callers
- N processes affected
- N clusters affected
-```
-
-
-
-### 6. Increase Process Detection Limits
-
-**File:** [gitnexus/src/core/ingestion/process-processor.ts](gitnexus/src/core/ingestion/process-processor.ts)Change default config (lines 27-32):
-
-```typescript
-const DEFAULT_CONFIG: ProcessDetectionConfig = {
-  maxTraceDepth: 10,    // Keep
-  maxBranching: 4,      // Was 3
-  maxProcesses: 75,     // Was 50
-  minSteps: 2,          // Keep
-};
-```
-
-
-
-### 7. Update System Prompt
-
-**File:** [gitnexus/src/core/llm/agent.ts](gitnexus/src/core/llm/agent.ts)Update BASE_SYSTEM_PROMPT to reflect new tools:
-
-```javascript
-## TOOLS
- **search** - Hybrid search. Results grouped by process with cluster context.
- **grep** - Regex pattern search for exact strings.
- **read** - Read file content.
- **explore** - Deep dive on a symbol, cluster, or process. Shows membership, participation, connections.
- **overview** - Codebase map showing all clusters and processes.
- **impact** - Impact analysis. Shows affected processes, clusters, and risk level.
- **cypher** - Raw Cypher queries against the graph.
-
-## GRAPH SCHEMA
-Nodes: File, Folder, Function, Class, Interface, Method, Community, Process
-Relations: CodeRelation with type: CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
-```
-
-
-
-## Implementation Order
-
-1. Remove highlight tool (cleanup)
-2. Increase process detection limits
-3. Add overview tool (simplest new tool)
-4. Add explore tool
-5. Enhance impact tool
--- a/.cursorrules
+++ b/.cursorrules
@ -0,0 +1,5 @@
+# AI Agent Rules
+
+Follow .gitnexus/RULES.md for all project context and coding guidelines.
+
+This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices.
--- a/.gitignore
+++ b/.gitignore
@ -41,3 +41,6 @@ coverage/

 .env*.local
 .gitnexus
+
+# Generated files (should not be indexed)
+repomix-output*
--- a/.windsurfrules
+++ b/.windsurfrules
@ -0,0 +1,5 @@
+# AI Agent Rules
+
+Follow .gitnexus/RULES.md for all project context and coding guidelines.
+
+This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices.
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,81 @@
+# AI Agent Rules
+
+Follow .gitnexus/RULES.md for all project context and coding guidelines.
+
+This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices.
+
+<!-- gitnexus:start -->
+# GitNexus MCP
+
+This project is indexed by GitNexus, providing AI agents with deep code intelligence.
+
+## Project: GitnexusV2
+
+| Metric | Count |
+|--------|-------|
+| Files | 150 |
+| Symbols | 930 |
+| Relationships | 2411 |
+| Communities | 280 |
+| Processes | 75 |
+
+## Quick Start
+
+```
+1. READ gitnexus://context        → Get codebase overview (~150 tokens)
+2. READ gitnexus://clusters       → See all functional clusters
+3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
+4. gitnexus_search(query)         → Find code by query
+```
+
+## Available Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `gitnexus://context` | Codebase stats, tools, and resources overview |
+| `gitnexus://clusters` | All clusters with symbol counts and cohesion |
+| `gitnexus://cluster/{name}` | Cluster members and details |
+| `gitnexus://processes` | All execution flows with types |
+| `gitnexus://process/{name}` | Full process trace with steps |
+| `gitnexus://schema` | Graph schema for Cypher queries |
+
+## Available Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `search` | Semantic + keyword search | Finding code by query |
+| `overview` | List clusters & processes | Understanding architecture |
+| `explore` | Deep dive on symbol/cluster/process | Detailed investigation |
+| `impact` | Blast radius analysis | Before making changes |
+| `cypher` | Raw graph queries | Complex analysis |
+
+## Workflow Examples
+
+### Exploring the Codebase
+```
+READ gitnexus://context           → Stats and overview
+READ gitnexus://clusters          → Find relevant cluster
+READ gitnexus://cluster/Auth      → Explore Auth cluster
+gitnexus_explore("validateUser", "symbol") → Detailed symbol info
+```
+
+### Planning a Change
+```
+gitnexus_impact("UserService", "upstream") → See what breaks
+READ gitnexus://processes         → Check affected flows
+gitnexus_explore("LoginFlow", "process") → Trace execution
+```
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+
+**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+// Example: Find callers of a function
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```
+
+<!-- gitnexus:end -->
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,75 @@
+<!-- gitnexus:start -->
+# GitNexus MCP
+
+This project is indexed by GitNexus, providing AI agents with deep code intelligence.
+
+## Project: GitnexusV2
+
+| Metric | Count |
+|--------|-------|
+| Files | 150 |
+| Symbols | 930 |
+| Relationships | 2411 |
+| Communities | 280 |
+| Processes | 75 |
+
+## Quick Start
+
+```
+1. READ gitnexus://context        → Get codebase overview (~150 tokens)
+2. READ gitnexus://clusters       → See all functional clusters
+3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
+4. gitnexus_search(query)         → Find code by query
+```
+
+## Available Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `gitnexus://context` | Codebase stats, tools, and resources overview |
+| `gitnexus://clusters` | All clusters with symbol counts and cohesion |
+| `gitnexus://cluster/{name}` | Cluster members and details |
+| `gitnexus://processes` | All execution flows with types |
+| `gitnexus://process/{name}` | Full process trace with steps |
+| `gitnexus://schema` | Graph schema for Cypher queries |
+
+## Available Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `search` | Semantic + keyword search | Finding code by query |
+| `overview` | List clusters & processes | Understanding architecture |
+| `explore` | Deep dive on symbol/cluster/process | Detailed investigation |
+| `impact` | Blast radius analysis | Before making changes |
+| `cypher` | Raw graph queries | Complex analysis |
+
+## Workflow Examples
+
+### Exploring the Codebase
+```
+READ gitnexus://context           → Stats and overview
+READ gitnexus://clusters          → Find relevant cluster
+READ gitnexus://cluster/Auth      → Explore Auth cluster
+gitnexus_explore("validateUser", "symbol") → Detailed symbol info
+```
+
+### Planning a Change
+```
+gitnexus_impact("UserService", "upstream") → See what breaks
+READ gitnexus://processes         → Check affected flows
+gitnexus_explore("LoginFlow", "process") → Trace execution
+```
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+
+**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+// Example: Find callers of a function
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```
+
+<!-- gitnexus:end -->
--- a/gitnexus/skills/debugging.md
+++ b/gitnexus/skills/debugging.md
@ -6,9 +6,11 @@ description: Trace bugs through call chains using knowledge graph
 # Debugging with GitNexus

 ## Quick Start
-1. `gitnexus_search(query)` → Find code related to the error
-2. `gitnexus_explore(name, "symbol")` → Get callers and callees
-3. `gitnexus_cypher` → Trace specific dependency paths
+```
+1. gitnexus_search({query})                → Find code related to error
+2. gitnexus_explore({name, type: "symbol"}) → Get callers and callees
+3. READ gitnexus://process/{name}           → Trace execution flow
+```

 ## When to Use
 - "Why is this function failing?"
@ -16,92 +18,80 @@ description: Trace bugs through call chains using knowledge graph
 - "Who calls this method?"
 - "Debug the payment issue"

-## Workflow
+## Workflow Checklist
 ```
 Bug Investigation:
 - [ ] Understand the symptom (error message, behavior)
 - [ ] gitnexus_search to find related code
 - [ ] Identify the suspect function
 - [ ] gitnexus_explore to see callers/callees
- [ ] Check which processes the suspect is in
- [ ] Trace dependencies with gitnexus_cypher
- [ ] Form hypothesis and verify
+- [ ] READ gitnexus://process/{name} if suspect is in a process
+- [ ] READ gitnexus://schema for Cypher query help
+- [ ] gitnexus_cypher for custom traces
+```
+
+## Resource Reference
+
+### gitnexus://schema
+Graph schema for writing Cypher queries:
+```yaml
+nodes: [Function, Class, Method, File, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS]
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://process/{name}
+Trace execution flow to find where bug might occur:
+```yaml
+name: CheckoutFlow
+trace:
+  1: handleCheckout
+  2: validateCart
+  3: processPayment  ← bug here?
+  4: sendConfirmation
 ```

 ## Tool Reference

 ### gitnexus_search
-Find code related to error or symptom.
+Find code related to error or symptom:
 ```
-gitnexus_search({
-  query: "payment validation error",
-  depth: "full",
-  groupByProcess: true
-})
-→ validatePayment, handlePaymentError, PaymentException
-→ Grouped by: CheckoutFlow, RefundFlow
+gitnexus_search({query: "payment validation error", depth: "full"})
 ```

-### gitnexus_explore (for symbol)
-Get symbol context.
+### gitnexus_explore
+Get symbol context:
 ```
 gitnexus_explore({name: "validatePayment", type: "symbol"})
 → Callers: processCheckout, webhookHandler
 → Callees: verifyCard, fetchRates
-→ Cluster: Payment
-→ Processes: CheckoutFlow, RefundFlow
 ```

 ### gitnexus_cypher
-Custom graph queries for tracing.
-
-**Find all callers of a function:**
-```
-gitnexus_cypher({query: `
-  MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validatePayment"})
-  RETURN caller.name, caller.filePath
-`})
-```
-
-**Find what a function calls:**
-```
-gitnexus_cypher({query: `
-  MATCH (f:Function {name: "validatePayment"})-[:CodeRelation {type: 'CALLS'}]->(callee)
-  RETURN callee.name, callee.filePath
-`})
-```
-
-**Trace call chain (2 hops):**
-```
-gitnexus_cypher({query: `
-  MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
-  RETURN [n IN nodes(path) | n.name] AS chain
-`})
+Custom graph queries for tracing:
+```cypher
+// Trace call chain (2 hops)
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
 ```

 ## Example: "Payment endpoint returns 500 intermittently"

-1. **Search for payment error handling**
-   ```
-   gitnexus_search({query: "payment error handling", depth: "full"})
-   ```
+```
+1. gitnexus_search({query: "payment error handling"})
   → validatePayment, handlePaymentError, PaymentException

-2. **Explore the suspect function**
-   ```
-   gitnexus_explore({name: "validatePayment", type: "symbol"})
-   ```
-   → Callers: processCheckout, webhookHandler
-   → Callees: verifyCard, **fetchRates** (external API!)
+2. gitnexus_explore({name: "validatePayment", type: "symbol"})
+   → Callees: verifyCard, fetchRates (external API!)

-3. **Form hypothesis**
-   `fetchRates` calls external currency API → intermittent failures when API is slow
+3. READ gitnexus://process/CheckoutFlow
+   → Step 3: validatePayment → calls external API

-4. **Verify**
-   Read `fetchRates` source to check timeout/error handling
-
-5. **Root cause**
-   `fetchRates` doesn't handle timeout properly → fix with retry logic
+4. Root cause: fetchRates calls external API without proper timeout
+```

 ## Debugging Patterns

@ -111,12 +101,3 @@ gitnexus_cypher({query: `
 | Wrong return value | Trace data flow through callees |
 | Intermittent failure | Look for external calls, timeouts |
 | Performance issue | Find hot paths via callers count |
-| Recent regression | Check recently modified files |
-
-## When to Use Something Else
-
-| Need | Use Instead |
-|------|-------------|
-| Explore unfamiliar code | `gitnexus-exploring` skill |
-| Check change impact | `gitnexus-impact-analysis` skill |
-| Plan refactoring | `gitnexus-refactoring` skill |
--- a/gitnexus/skills/exploring.md
+++ b/gitnexus/skills/exploring.md
@ -6,9 +6,11 @@ description: Navigate unfamiliar code using GitNexus knowledge graph
 # Exploring Codebases

 ## Quick Start
-1. `gitnexus_context` → Get codebase stats and hotspots
-2. `gitnexus_overview` → See all clusters and processes
-3. `gitnexus_explore(name, "cluster")` → Deep dive on a cluster
+```
+1. READ gitnexus://context        → Get codebase overview (~150 tokens)
+2. READ gitnexus://clusters       → See all functional clusters
+3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
+```

 ## When to Use
 - "How does authentication work?"
@ -16,81 +18,94 @@ description: Navigate unfamiliar code using GitNexus knowledge graph
 - "Show me the main components"
 - "Where is the database logic?"

-## Workflow
+## Workflow Checklist
 ```
-Exploring Codebase:
- [ ] Call gitnexus_context to get codebase overview
- [ ] Call gitnexus_overview to list clusters
+Exploration Progress:
+- [ ] READ gitnexus://context for codebase overview
+- [ ] READ gitnexus://clusters to list all clusters
 - [ ] Identify the relevant cluster by name
- [ ] Call gitnexus_explore(clusterName, "cluster") to see members
- [ ] Call gitnexus_explore(symbolName, "symbol") for specific functions
+- [ ] READ gitnexus://cluster/{name} for cluster details
+- [ ] Use gitnexus_explore for specific symbols
 ```

-## Tool Reference
+## Resource Reference

-### gitnexus_context
-Get codebase overview. **Call first.**
-```
-gitnexus_context()
-→ Stats: 2,400 nodes, 12 clusters, 45 processes
-→ Hotspots: most connected functions
+### gitnexus://context
+Codebase overview. **Read first.**
+```yaml
+project: my-app
+stats:
+  files: 42
+  symbols: 918
+  clusters: 12
+  processes: 45
+tools_available: [search, explore, impact, overview, cypher]
+resources_available: [clusters, processes, cluster/{name}, process/{name}]
 ```

-### gitnexus_overview
-List all clusters and processes.
+### gitnexus://clusters
+All functional clusters with cohesion scores.
+```yaml
+clusters:
+  - name: "Auth"
+    symbols: 47
+    cohesion: 92%
+  - name: "Database"
+    symbols: 32
+    cohesion: 88%
 ```
-gitnexus_overview({showClusters: true, showProcesses: true})
-→ Clusters: Auth, Database, API, ...
-→ Processes: LoginFlow, CheckoutFlow, ...
+
+### gitnexus://cluster/{name}
+Members of a specific cluster.
+```yaml
+name: Auth
+symbols: 47
+cohesion: 92%
+members:
+  - name: validateUser
+    type: Function
+    file: src/auth/validator.ts
 ```

+### gitnexus://process/{name}
+Full execution trace.
+```yaml
+name: LoginFlow
+type: cross_community
+steps:
+  1: handleLogin (src/auth/handler.ts)
+  2: validateUser (src/auth/validator.ts)
+  3: createSession (src/auth/session.ts)
+```
+
+## Tool Reference (When Resources Aren't Enough)
+
 ### gitnexus_explore
-Deep dive on symbol, cluster, or process.
+For detailed symbol context with callers/callees:
 ```
-gitnexus_explore({name: "Auth", type: "cluster"})
-→ Members: validateUser, checkToken, hashPassword
-→ Processes using this cluster
-
 gitnexus_explore({name: "validateUser", type: "symbol"})
 → Callers: loginHandler, apiMiddleware
 → Callees: checkToken, getUserById
-→ Cluster: Auth
+```

-gitnexus_explore({name: "LoginFlow", type: "process"})
-→ Steps: handleLogin → validateUser → createSession → respond
+### gitnexus_search
+For finding code by query:
+```
+gitnexus_search({query: "payment validation", depth: "full"})
 ```

 ## Example: "How does payment processing work?"

-1. **Get overview**
-   ```
-   gitnexus_context()
-   ```
-   → 2,400 nodes, 12 clusters, 45 processes
+```
+1. READ gitnexus://context
+   → 918 symbols, 12 clusters

-2. **Find payment cluster**
-   ```
-   gitnexus_overview({showClusters: true})
-   ```
-   → Clusters: Auth, **Payment**, Database, API, ...
+2. READ gitnexus://clusters
+   → Clusters: Auth, Payment, Database, API...

-3. **Explore payment cluster**
-   ```
-   gitnexus_explore({name: "Payment", type: "cluster"})
-   ```
-   → Members: processPayment, validateCard, PaymentService, ...
-   → Processes: CheckoutFlow, RefundFlow
+3. READ gitnexus://cluster/Payment
+   → Members: processPayment, validateCard, PaymentService

-4. **Trace the checkout flow**
-   ```
-   gitnexus_explore({name: "CheckoutFlow", type: "process"})
-   ```
+4. READ gitnexus://process/CheckoutFlow
   → handleCheckout → validateCart → processPayment → sendConfirmation
-
-## When to Use Something Else
-
-| Need | Use Instead |
-|------|-------------|
-| Debug failing code | `gitnexus-debugging` skill |
-| Check change impact | `gitnexus-impact-analysis` skill |
-| Plan refactoring | `gitnexus-refactoring` skill |
+```
--- a/gitnexus/skills/impact-analysis.md
+++ b/gitnexus/skills/impact-analysis.md
@ -6,9 +6,11 @@ description: Analyze blast radius before making code changes
 # Impact Analysis

 ## Quick Start
-1. `gitnexus_impact(target, "upstream")` → What depends on this (will break)
-2. Review affected processes and clusters
-3. Assess risk level
+```
+1. gitnexus_impact({target, direction: "upstream"}) → What depends on this
+2. READ gitnexus://clusters                         → Check affected areas
+3. READ gitnexus://processes                        → Affected execution flows
+```

 ## When to Use
 - "Is it safe to change this function?"
@ -24,84 +26,61 @@ description: Analyze blast radius before making code changes
 | d=2 | LIKELY AFFECTED | Indirect dependencies |
 | d=3 | MAY NEED TESTING | Transitive effects |

-| Confidence | Meaning |
-|------------|---------|
-| 1.0 | Certain (static analysis) |
-| 0.8+ | High confidence |
-| <0.8 | Fuzzy match (may be false positive) |
-
-## Workflow
+## Workflow Checklist
 ```
 Impact Analysis:
 - [ ] gitnexus_impact(target, "upstream") to find dependents
- [ ] Review affected processes
+- [ ] READ gitnexus://clusters to understand affected areas
 - [ ] Check high-confidence (>0.8) dependencies first
 - [ ] Count affected clusters (cross-cutting = higher risk)
 - [ ] If >10 processes affected, consider splitting change
 ```

+## Resource Reference
+
+### gitnexus://clusters
+Check which clusters might be affected:
+```yaml
+clusters:
+  - name: Auth
+    symbols: 47
+  - name: API
+    symbols: 32
+```
+
+### gitnexus://processes
+Find which processes touch the target:
+```yaml
+processes:
+  - name: LoginFlow
+    type: cross_community
+    steps: 5
+```
+
 ## Tool Reference

 ### gitnexus_impact
-Analyze blast radius.
+Analyze blast radius:
 ```
 gitnexus_impact({
  target: "validateUser",
  direction: "upstream",
  minConfidence: 0.8,
-  maxDepth: 3,
-  includeTests: false
+  maxDepth: 3
 })
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+
+→ Affected Processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM (3 processes)
 ```

-**Parameters:**
- `target` — Function, class, or file name
- `direction` — "upstream" (what depends on this) or "downstream" (what this depends on)
- `minConfidence` — Filter out fuzzy matches (default: 0.7)
- `maxDepth` — How far to trace (default: 3)
- `includeTests` — Include test files (default: false)
-
-**Output:**
-```
-Impact Analysis for "validateUser":
-
-d=1 (WILL BREAK):
- loginHandler (src/auth/login.ts:42) [CALLS, 100%]
- apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
-
-d=2 (LIKELY AFFECTED):
- authRouter (src/routes/auth.ts:22) [CALLS, 95%]
- sessionManager (src/session/manager.ts:88) [CALLS, 90%]
-
-Affected Processes: LoginFlow, TokenRefresh, APIGateway
-Affected Clusters: Auth, API
-
-Risk: MEDIUM (3 processes, 2 clusters)
-```
-
-## Example: "What breaks if I change validateUser?"
-
-1. **Run impact analysis**
-   ```
-   gitnexus_impact({
-     target: "validateUser",
-     direction: "upstream",
-     minConfidence: 0.8
-   })
-   ```
-
-2. **Review output**
-   - d=1: loginHandler, apiMiddleware (WILL BREAK)
-   - d=2: authRouter, sessionManager (LIKELY AFFECTED)
-   - Processes: LoginFlow, TokenRefresh, APIGateway
-   - Risk: MEDIUM
-
-3. **Decision**
-   - 2 direct callers → manageable
-   - 3 processes → need to test all three
-   - Auth + API clusters → may need API team coordination
-
-## Risk Assessment Guide
+## Risk Assessment

 | Affected | Risk |
 |----------|------|
@ -120,10 +99,15 @@ Before Committing:
 - [ ] If cross-cluster, coordinate with other teams
 ```

-## When to Use Something Else
+## Example: "What breaks if I change validateUser?"

-| Need | Use Instead |
-|------|-------------|
-| Explore unfamiliar code | `gitnexus-exploring` skill |
-| Debug failing code | `gitnexus-debugging` skill |
-| Plan large refactors | `gitnexus-refactoring` skill |
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware
+   → d=2: authRouter, sessionManager
+
+2. READ gitnexus://clusters
+   → Auth and API clusters affected
+
+3. Decision: 2 direct callers, 2 clusters = MEDIUM risk
+```
--- a/gitnexus/skills/refactoring.md
+++ b/gitnexus/skills/refactoring.md
@ -6,9 +6,11 @@ description: Plan safe refactors using blast radius and dependency mapping
 # Refactoring with GitNexus

 ## Quick Start
-1. `gitnexus_impact(target, "upstream")` → Map all dependents
-2. `gitnexus_cypher` → Find all references
-3. Plan changes in dependency order
+```
+1. gitnexus_impact({target, direction: "upstream"}) → Map all dependents
+2. READ gitnexus://schema                           → Understand graph structure
+3. gitnexus_cypher                                  → Find all references
+```

 ## When to Use
 - "Rename this function safely"
@ -33,10 +35,9 @@ Rename Refactoring:
 Extract Module:
 - [ ] gitnexus_explore(target, "symbol") — map dependencies
 - [ ] gitnexus_impact(target, "upstream") — find callers
+- [ ] READ gitnexus://cluster/{name} — check cohesion
 - [ ] Define new module interface
- [ ] Move code to new module
 - [ ] Update imports across affected files
- [ ] Verify no circular dependencies
 ```

 ### Split Function
@ -46,102 +47,65 @@ Split Function:
 - [ ] Group related logic
 - [ ] gitnexus_impact — verify callers won't break
 - [ ] Create new functions
- [ ] Update callers to use correct function
+- [ ] Update callers
+```
+
+## Resource Reference
+
+### gitnexus://schema
+Graph structure for Cypher queries:
+```yaml
+nodes: [Function, Class, Method, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, MEMBER_OF]
+
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://cluster/{name}
+Check if extraction preserves cohesion:
+```yaml
+name: Payment
+cohesion: 92%
+members: [processPayment, validateCard, PaymentService]
 ```

 ## Tool Reference

 ### Finding all references
-```
-gitnexus_cypher({query: `
-  MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
-  RETURN caller.name, caller.filePath
-  ORDER BY caller.filePath
-`})
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath
+ORDER BY caller.filePath
 ```

-### Finding symbols by name pattern
-```
-gitnexus_cypher({query: `
-  MATCH (s)
-  WHERE s.name CONTAINS "Payment"
-  RETURN s.name, labels(s)[0] AS type, s.filePath
-`})
-```
-
-### Finding all imports of a module
-```
-gitnexus_cypher({query: `
-  MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"})
-  RETURN importer.name, importer.filePath
-`})
-```
-
-### Finding community/cluster members
-```
-gitnexus_cypher({query: `
-  MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community {label: "Auth"})
-  RETURN s.name, labels(s)[0] AS type
-`})
+### Finding imports of a module
+```cypher
+MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"})
+RETURN importer.name, importer.filePath
 ```

 ## Example: Safely Rename `validateUser` to `authenticateUser`

-1. **Map all callers**
-   ```
-   gitnexus_impact({
-     target: "validateUser",
-     direction: "upstream",
-     minConfidence: 0.9
-   })
-   ```
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
   → loginHandler, apiMiddleware, testUtils

-2. **Check for string references**
-   ```
-   gitnexus_search({query: "validateUser"})
-   ```
+2. gitnexus_search({query: "validateUser"})
   → Found in: config.json (dynamic reference!)

-3. **Get affected processes**
-   ```
-   gitnexus_explore({name: "validateUser", type: "symbol"})
-   ```
-   → Processes: LoginFlow, TokenRefresh, APIGateway
+3. READ gitnexus://processes
+   → LoginFlow, TokenRefresh, APIGateway

-4. **Plan update order**
+4. Plan update order:
   1. Update declaration in auth.ts
   2. Update config.json string reference
   3. Update loginHandler
   4. Update apiMiddleware
-   5. Update testUtils
-   6. Run: LoginFlow, TokenRefresh, APIGateway tests
-
-## Example: Extract PaymentValidator Module
-
-1. **Understand current dependencies**
-   ```
-   gitnexus_explore({name: "validatePayment", type: "symbol"})
-   ```
-   → Callees: verifyCard, checkAmount, fetchRates
-   → Callers: processCheckout, refundHandler
-
-2. **Map blast radius**
-   ```
-   gitnexus_impact({target: "validatePayment", direction: "upstream"})
-   ```
-   → 2 direct callers, 3 processes
-
-3. **Create new module**
-   - Move validatePayment, verifyCard, checkAmount to PaymentValidator
-   - Keep fetchRates as external dependency (inject it)
-
-4. **Update callers**
-   - processCheckout: import { validatePayment } from './PaymentValidator'
-   - refundHandler: import { validatePayment } from './PaymentValidator'
-
-5. **Verify**
-   - Run tests for CheckoutFlow, RefundFlow processes
+   5. Run tests for LoginFlow, TokenRefresh
+```

 ## Refactoring Safety Rules

@ -152,11 +116,3 @@ gitnexus_cypher({query: `
 | String references | Search for dynamic usage |
 | Reflection | Check for dynamic invocation |
 | External exports | May break downstream repos |
-
-## When to Use Something Else
-
-| Need | Use Instead |
-|------|-------------|
-| Explore unfamiliar code | `gitnexus-exploring` skill |
-| Debug failing code | `gitnexus-debugging` skill |
-| Quick impact check | `gitnexus-impact-analysis` skill |
--- a/gitnexus/src/cli/ai-context.ts
+++ b/gitnexus/src/cli/ai-context.ts
@ -26,7 +26,7 @@ const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
 const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';

 /**
- * Generate the full GitNexus context content
+ * Generate the full GitNexus context content (resources-first approach)
 */
 function generateGitNexusContent(projectName: string, stats: RepoStats): string {
  return `${GITNEXUS_START_MARKER}
@ -46,71 +46,67 @@ This project is indexed by GitNexus, providing AI agents with deep code intellig

 ## Quick Start

-1. **Call \`context\` first** — Understand the codebase structure
-2. **Use \`search\` for discovery** — Semantic search with graph context
-3. **Use \`impact\` before refactoring** — Understand blast radius
+\`\`\`
+1. READ gitnexus://context        → Get codebase overview (~150 tokens)
+2. READ gitnexus://clusters       → See all functional clusters
+3. READ gitnexus://cluster/{name} → Deep dive on specific cluster
+4. gitnexus_search(query)         → Find code by query
+\`\`\`
+
+## Available Resources
+
+| Resource | Purpose |
+|----------|---------|
+| \`gitnexus://context\` | Codebase stats, tools, and resources overview |
+| \`gitnexus://clusters\` | All clusters with symbol counts and cohesion |
+| \`gitnexus://cluster/{name}\` | Cluster members and details |
+| \`gitnexus://processes\` | All execution flows with types |
+| \`gitnexus://process/{name}\` | Full process trace with steps |
+| \`gitnexus://schema\` | Graph schema for Cypher queries |

 ## Available Tools

 | Tool | Purpose | When to Use |
 |------|---------|-------------|
-| \`context\` | Codebase overview | Start of conversation |
-| \`search\` | Semantic + keyword search | Finding code |
+| \`search\` | Semantic + keyword search | Finding code by query |
 | \`overview\` | List clusters & processes | Understanding architecture |
 | \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
 | \`impact\` | Blast radius analysis | Before making changes |
 | \`cypher\` | Raw graph queries | Complex analysis |

-## Tool Reference
+## Workflow Examples

-### \`context\`
-Get codebase overview and stats. **Call this first.**
-
-### \`search\`
+### Exploring the Codebase
 \`\`\`
-search(query: "authentication middleware", depth: "full")
-\`\`\`
- \`depth: "definitions"\` — Symbol signatures only (default)
- \`depth: "full"\` — Symbols + all relationships
-
-### \`explore\`
-\`\`\`
-explore(name: "validateUser", type: "symbol")
-explore(name: "Authentication", type: "cluster")
-explore(name: "LoginFlow", type: "process")
+READ gitnexus://context           → Stats and overview
+READ gitnexus://clusters          → Find relevant cluster
+READ gitnexus://cluster/Auth      → Explore Auth cluster
+gitnexus_explore("validateUser", "symbol") → Detailed symbol info
 \`\`\`

-### \`impact\`
+### Planning a Change
 \`\`\`
-impact(target: "UserService", direction: "upstream", minConfidence: 0.8)
+gitnexus_impact("UserService", "upstream") → See what breaks
+READ gitnexus://processes         → Check affected flows
+gitnexus_explore("LoginFlow", "process") → Trace execution
 \`\`\`
- \`upstream\` — What depends on this (will break if changed)
- \`downstream\` — What this depends on

-### \`cypher\`
-Execute Cypher queries on the knowledge graph.
+## Graph Schema

-**Schema:**
- Nodes: \`File\`, \`Folder\`, \`Function\`, \`Class\`, \`Interface\`, \`Method\`, \`Community\`, \`Process\`
- Edges: \`CALLS\`, \`IMPORTS\`, \`EXTENDS\`, \`IMPLEMENTS\`, \`DEFINES\`, \`MEMBER_OF\`, \`STEP_IN_PROCESS\`
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+
+**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS

 \`\`\`cypher
-// Find all callers of a function
-MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunction"})
+// Example: Find callers of a function
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
 RETURN caller.name, caller.filePath
 \`\`\`

-## Key Concepts
-
-| Concept | Description |
-|---------|-------------|
-| **Community** | Functional cluster detected by Leiden algorithm |
-| **Process** | Execution flow from entry point to terminal |
-| **Confidence** | Relationship trust score (1.0 = certain, <0.8 = fuzzy) |
-
 ${GITNEXUS_END_MARKER}`;
 }

+
 /**
 * Check if a file exists
 */
--- a/gitnexus/src/mcp/local/local-backend.ts
+++ b/gitnexus/src/mcp/local/local-backend.ts
@ -169,8 +169,6 @@ export class LocalBackend {
    }

    switch (method) {
-      case 'context':
-        return this.getContext();
      case 'search':
        return this.search(params);
      case 'cypher':
@ -188,35 +186,6 @@ export class LocalBackend {
    }
  }

-  private async getContext(): Promise<string> {
-    if (!this._context || !this.repo) {
-      return 'Repository not indexed. Run: gitnexus analyze';
-    }
-
-    const stats = this.repo.meta.stats || {};
-    return [
-      `# GitNexus: ${this._context.projectName}`,
-      '',
-      '## Stats',
-      `- Files: ${stats.files || 0}`,
-      `- Nodes: ${stats.nodes || 0}`,
-      `- Edges: ${stats.edges || 0}`,
-      `- Communities: ${stats.communities || 0}`,
-      `- Processes: ${stats.processes || 0}`,
-      '',
-      `Indexed: ${this.repo.meta.indexedAt}`,
-      `Commit: ${this.repo.meta.lastCommit?.slice(0, 7)}`,
-      '',
-      '## Available Tools',
-      '- **analyze**: Index/re-index repository',
-      '- **search**: Hybrid semantic + keyword search',
-      '- **cypher**: Graph queries (Cypher)',
-      '- **overview**: List communities and processes',
-      '- **explore**: Deep dive on symbol/cluster/process',
-      '- **impact**: Change impact analysis',
-    ].join('\n');
-  }
-
  private async search(params: { query: string; limit?: number; depth?: string; groupByProcess?: boolean }): Promise<any> {
    await this.ensureInitialized();
    
--- a/gitnexus/src/mcp/resources.ts
+++ b/gitnexus/src/mcp/resources.ts
@ -0,0 +1,311 @@
+/**
+ * MCP Resources
+ * 
+ * Provides structured on-demand data to AI agents.
+ * Resources complement tools by offering lightweight, cacheable data.
+ */
+
+import type { LocalBackend } from './local/local-backend.js';
+
+export interface ResourceDefinition {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+export interface ResourceTemplate {
+  uriTemplate: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+/**
+ * Static resources available when codebase is indexed
+ */
+export function getResourceDefinitions(projectName: string): ResourceDefinition[] {
+  return [
+    {
+      uri: 'gitnexus://context',
+      name: `${projectName} Overview`,
+      description: 'Codebase stats, hotspots, and available tools',
+      mimeType: 'text/yaml',
+    },
+    {
+      uri: 'gitnexus://clusters',
+      name: 'All Clusters',
+      description: 'List of all functional clusters with stats',
+      mimeType: 'text/yaml',
+    },
+    {
+      uri: 'gitnexus://processes',
+      name: 'All Processes',
+      description: 'List of all execution flows with types',
+      mimeType: 'text/yaml',
+    },
+    {
+      uri: 'gitnexus://schema',
+      name: 'Graph Schema',
+      description: 'Node types and relationships for Cypher queries',
+      mimeType: 'text/yaml',
+    },
+  ];
+}
+
+/**
+ * Dynamic resource templates
+ */
+export function getResourceTemplates(): ResourceTemplate[] {
+  return [
+    {
+      uriTemplate: 'gitnexus://cluster/{name}',
+      name: 'Cluster Detail',
+      description: 'Deep dive into a specific cluster',
+      mimeType: 'text/yaml',
+    },
+    {
+      uriTemplate: 'gitnexus://process/{name}',
+      name: 'Process Trace',
+      description: 'Step-by-step execution trace',
+      mimeType: 'text/yaml',
+    },
+  ];
+}
+
+/**
+ * Read a resource and return its content
+ */
+export async function readResource(uri: string, backend: LocalBackend): Promise<string> {
+  // Static resources
+  if (uri === 'gitnexus://context') {
+    return getContextResource(backend);
+  }
+  if (uri === 'gitnexus://clusters') {
+    return getClustersResource(backend);
+  }
+  if (uri === 'gitnexus://processes') {
+    return getProcessesResource(backend);
+  }
+  if (uri === 'gitnexus://schema') {
+    return getSchemaResource();
+  }
+  
+  // Dynamic resources
+  if (uri.startsWith('gitnexus://cluster/')) {
+    const name = uri.replace('gitnexus://cluster/', '');
+    return getClusterDetailResource(name, backend);
+  }
+  if (uri.startsWith('gitnexus://process/')) {
+    const name = uri.replace('gitnexus://process/', '');
+    return getProcessDetailResource(name, backend);
+  }
+  
+  throw new Error(`Unknown resource: ${uri}`);
+}
+
+/**
+ * Context resource - codebase overview
+ */
+async function getContextResource(backend: LocalBackend): Promise<string> {
+  const context = backend.context;
+  if (!context) {
+    return 'error: No codebase loaded. Run: gitnexus analyze';
+  }
+  
+  const lines: string[] = [
+    `project: ${context.projectName}`,
+    'stats:',
+    `  files: ${context.stats.fileCount}`,
+    `  symbols: ${context.stats.functionCount}`,
+    `  clusters: ${context.stats.communityCount}`,
+    `  processes: ${context.stats.processCount}`,
+    '',
+    'tools_available:',
+    '  - search: Hybrid semantic + keyword search',
+    '  - explore: Deep dive on symbol/cluster/process',
+    '  - impact: Blast radius analysis',
+    '  - overview: List all clusters and processes',
+    '  - cypher: Raw graph queries',
+    '',
+    'resources_available:',
+    '  - gitnexus://clusters: All clusters',
+    '  - gitnexus://processes: All processes',
+    '  - gitnexus://cluster/{name}: Cluster details',
+    '  - gitnexus://process/{name}: Process trace',
+  ];
+  
+  return lines.join('\n');
+}
+
+/**
+ * Clusters resource - list all clusters
+ */
+async function getClustersResource(backend: LocalBackend): Promise<string> {
+  try {
+    const result = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 50 });
+    
+    if (!result.clusters || result.clusters.length === 0) {
+      return 'clusters: []\n# No clusters detected. Run: gitnexus analyze';
+    }
+    
+    const lines: string[] = ['clusters:'];
+    
+    for (const cluster of result.clusters) {
+      const label = cluster.heuristicLabel || cluster.label || cluster.id;
+      lines.push(`  - name: "${label}"`);
+      lines.push(`    symbols: ${cluster.symbolCount || 0}`);
+      if (cluster.cohesion) {
+        lines.push(`    cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`);
+      }
+    }
+    
+    return lines.join('\n');
+  } catch (err: any) {
+    return `error: ${err.message}`;
+  }
+}
+
+/**
+ * Processes resource - list all processes
+ */
+async function getProcessesResource(backend: LocalBackend): Promise<string> {
+  try {
+    const result = await backend.callTool('overview', { showClusters: false, showProcesses: true, limit: 50 });
+    
+    if (!result.processes || result.processes.length === 0) {
+      return 'processes: []\n# No processes detected. Run: gitnexus analyze';
+    }
+    
+    const lines: string[] = ['processes:'];
+    
+    for (const proc of result.processes) {
+      const label = proc.heuristicLabel || proc.label || proc.id;
+      lines.push(`  - name: "${label}"`);
+      lines.push(`    type: ${proc.processType || 'unknown'}`);
+      lines.push(`    steps: ${proc.stepCount || 0}`);
+    }
+    
+    return lines.join('\n');
+  } catch (err: any) {
+    return `error: ${err.message}`;
+  }
+}
+
+/**
+ * Schema resource - graph structure for Cypher queries
+ */
+function getSchemaResource(): string {
+  return `# GitNexus Graph Schema
+
+nodes:
+  - File: Source code files
+  - Function: Functions and arrow functions
+  - Class: Class definitions
+  - Interface: Interface/type definitions
+  - Method: Class methods
+  - Community: Functional cluster (Leiden algorithm)
+  - Process: Execution flow trace
+
+relationships:
+  - CALLS: Function/method invocation
+  - IMPORTS: Module imports
+  - EXTENDS: Class inheritance
+  - IMPLEMENTS: Interface implementation
+  - DEFINES: File defines symbol
+  - MEMBER_OF: Symbol belongs to community
+  - STEP_IN_PROCESS: Symbol is step N in process
+
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+    RETURN caller.name, caller.filePath
+  
+  find_community_members: |
+    MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+    WHERE c.heuristicLabel = "Auth"
+    RETURN s.name, labels(s)[0] AS type
+  
+  trace_process: |
+    MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+    WHERE p.heuristicLabel = "LoginFlow"
+    RETURN s.name, r.step
+    ORDER BY r.step
+`;
+}
+
+/**
+ * Cluster detail resource
+ */
+async function getClusterDetailResource(name: string, backend: LocalBackend): Promise<string> {
+  try {
+    const result = await backend.callTool('explore', { name, type: 'cluster' });
+    
+    if (result.error) {
+      return `error: ${result.error}`;
+    }
+    
+    const cluster = result.cluster;
+    const members = result.members || [];
+    
+    const lines: string[] = [
+      `name: "${cluster.heuristicLabel || cluster.label || cluster.id}"`,
+      `symbols: ${cluster.symbolCount || members.length}`,
+    ];
+    
+    if (cluster.cohesion) {
+      lines.push(`cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`);
+    }
+    
+    if (members.length > 0) {
+      lines.push('');
+      lines.push('members:');
+      for (const member of members.slice(0, 20)) {
+        lines.push(`  - name: ${member.name}`);
+        lines.push(`    type: ${member.type}`);
+        lines.push(`    file: ${member.filePath}`);
+      }
+      if (members.length > 20) {
+        lines.push(`  # ... and ${members.length - 20} more`);
+      }
+    }
+    
+    return lines.join('\n');
+  } catch (err: any) {
+    return `error: ${err.message}`;
+  }
+}
+
+/**
+ * Process detail resource
+ */
+async function getProcessDetailResource(name: string, backend: LocalBackend): Promise<string> {
+  try {
+    const result = await backend.callTool('explore', { name, type: 'process' });
+    
+    if (result.error) {
+      return `error: ${result.error}`;
+    }
+    
+    const proc = result.process;
+    const steps = result.steps || [];
+    
+    const lines: string[] = [
+      `name: "${proc.heuristicLabel || proc.label || proc.id}"`,
+      `type: ${proc.processType || 'unknown'}`,
+      `step_count: ${proc.stepCount || steps.length}`,
+    ];
+    
+    if (steps.length > 0) {
+      lines.push('');
+      lines.push('trace:');
+      for (const step of steps) {
+        lines.push(`  ${step.step}: ${step.name} (${step.filePath})`);
+      }
+    }
+    
+    return lines.join('\n');
+  } catch (err: any) {
+    return `error: ${err.message}`;
+  }
+}
--- a/gitnexus/src/mcp/server.ts
+++ b/gitnexus/src/mcp/server.ts
@ -6,6 +6,7 @@
 * communicate via stdin/stdout using the MCP protocol.
 * 
 * Tools: context, search, cypher, overview, explore, impact, analyze
+ * Resources: context, clusters, processes, schema, cluster/{name}, process/{name}
 */

 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@ -15,46 +16,11 @@ import {
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
+  ListResourceTemplatesRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { GITNEXUS_TOOLS } from './tools.js';
-import type { LocalBackend, CodebaseContext } from './local/local-backend.js';
-
-/**
- * Format context as markdown for the resource
- */
-function formatContextAsMarkdown(context: CodebaseContext): string {
-  const { projectName, stats } = context;
-  
-  const lines: string[] = [];
-  
-  lines.push(`# GitNexus: ${projectName}`);
-  lines.push('');
-  lines.push('## Stats');
-  lines.push(`- Files: ${stats.fileCount}`);
-  lines.push(`- Functions: ${stats.functionCount}`);
-  if (stats.communityCount > 0) lines.push(`- Communities: ${stats.communityCount}`);
-  if (stats.processCount > 0) lines.push(`- Processes: ${stats.processCount}`);
-  lines.push('');
-  
-  lines.push('## Available Tools');
-  lines.push('');
-  lines.push('- **context**: Codebase overview and stats');
-  lines.push('- **search**: Hybrid semantic + keyword search');
-  lines.push('- **cypher**: Execute Cypher queries on graph');
-  lines.push('- **overview**: List communities and processes');
-  lines.push('- **explore**: Deep dive on symbol/cluster/process');
-  lines.push('- **impact**: Change impact analysis');
-  lines.push('- **analyze**: Index/re-index repository');
-  lines.push('');
-  
-  lines.push('## Graph Schema');
-  lines.push('');
-  lines.push('**Nodes**: File, Function, Class, Interface, Method, Community, Process');
-  lines.push('');
-  lines.push('**Relations**: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS');
-  
-  return lines.join('\n');
-}
+import type { LocalBackend } from './local/local-backend.js';
+import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';

 export async function startMCPServer(backend: LocalBackend): Promise<void> {
  const server = new Server(
@ -78,15 +44,27 @@ export async function startMCPServer(backend: LocalBackend): Promise<void> {
      return { resources: [] };
    }
    
+    const resources = getResourceDefinitions(context.projectName);
    return {
-      resources: [
-        {
-          uri: 'gitnexus://codebase/context',
-          name: `GitNexus: ${context.projectName}`,
-          description: `Codebase context for ${context.projectName} (${context.stats.fileCount} files)`,
-          mimeType: 'text/markdown',
-        },
-      ],
+      resources: resources.map(r => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: r.mimeType,
+      })),
+    };
+  });
+
+  // Handle list resource templates request (for dynamic resources)
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+    const templates = getResourceTemplates();
+    return {
+      resourceTemplates: templates.map(t => ({
+        uriTemplate: t.uriTemplate,
+        name: t.name,
+        description: t.description,
+        mimeType: t.mimeType,
+      })),
    };
  });

@ -94,35 +72,31 @@ export async function startMCPServer(backend: LocalBackend): Promise<void> {
  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
    const { uri } = request.params;
    
-    if (uri === 'gitnexus://codebase/context') {
-      const context = backend.context;
-      
-      if (!context) {
-        return {
-          contents: [
-            {
-              uri,
-              mimeType: 'text/plain',
-              text: 'No codebase loaded.',
-            },
-          ],
-        };
-      }
-      
+    try {
+      const content = await readResource(uri, backend);
      return {
        contents: [
          {
            uri,
-            mimeType: 'text/markdown',
-            text: formatContextAsMarkdown(context),
+            mimeType: 'text/yaml',
+            text: content,
+          },
+        ],
+      };
+    } catch (err: any) {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'text/plain',
+            text: `Error: ${err.message}`,
          },
        ],
      };
    }
-    
-    throw new Error(`Unknown resource: ${uri}`);
  });

+
  // Handle list tools request
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: GITNEXUS_TOOLS.map((tool) => ({
--- a/gitnexus/src/mcp/tools.ts
+++ b/gitnexus/src/mcp/tools.ts
@ -46,23 +46,6 @@ Run this when:
      required: [],
    },
  },
-  {
-    name: 'context',
-    description: `Get GitNexus codebase context. CALL THIS FIRST before using other tools.
-
-Returns:
- Project name and stats (files, functions, classes)
- Hotspots (most connected/important nodes)
- Communities and processes count
- Tool usage guidance
-
-ALWAYS call this first to understand the codebase before searching or querying.`,
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      required: [],
-    },
-  },
  {
    name: 'search',
    description: `Hybrid search (keyword + semantic) across the codebase.