code-graph-context 2.4.4 → 2.5.0

package/README.md

@@ -1,4 +1,4 @@
-# Code Graph Context MCP Server
+# Code Graph Context
 
 [![npm version](https://badge.fury.io/js/code-graph-context.svg)](https://www.npmjs.com/package/code-graph-context)
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
@@ -8,77 +8,139 @@
 [![OpenAI](https://img.shields.io/badge/OpenAI-Powered-412991?logo=openai&logoColor=white)](https://openai.com/)
 [![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io/)
 
-A Model Context Protocol (MCP) server that builds rich code graphs to provide deep contextual understanding of TypeScript codebases to Large Language Models. This server parses your codebase using AST analysis, constructs a comprehensive graph representation in Neo4j, and provides intelligent querying capabilities through semantic search and graph traversal.
-
-**Config-Driven & Extensible**: Define custom framework schemas to capture domain-specific patterns beyond the included NestJS support. The parser is fully configurable to recognize your architectural patterns, decorators, and relationships.
+**Give your AI coding assistant a photographic memory of your codebase.**
+
+Code Graph Context is an MCP server that builds a semantic graph of your TypeScript codebase, enabling Claude to understand not just individual files, but how your entire system fits together.
+
+> **Config-Driven & Extensible**: Define custom framework schemas to capture domain-specific patterns beyond the included NestJS support. The parser is fully configurable to recognize your architectural patterns, decorators, and relationships.
+
+```
+                    ┌─────────────────────────────────────────────────────────────┐
+                    │                     YOUR CODEBASE                           │
+                    │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+                    │  │ Service  │  │Controller│  │  Module  │  │  Entity  │    │
+                    │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
+                    └───────┼─────────────┼─────────────┼─────────────┼──────────┘
+                            │             │             │             │
+                            ▼             ▼             ▼             ▼
+                    ┌─────────────────────────────────────────────────────────────┐
+                    │                   CODE GRAPH CONTEXT                        │
+                    │                                                             │
+                    │   AST Parser ──► Neo4j Graph ──► Vector Embeddings          │
+                    │   (ts-morph)     (Relationships)  (OpenAI)                  │
+                    │                                                             │
+                    └─────────────────────────────────────────────────────────────┘
+                                                │
+                                                ▼
+                    ┌─────────────────────────────────────────────────────────────┐
+                    │                      CLAUDE CODE                            │
+                    │                                                             │
+                    │   "What services depend on UserService?"                    │
+                    │   "What's the blast radius if I change this function?"      │
+                    │   "Find all HTTP endpoints that accept a UserDTO"           │
+                    │   "Refactor this across all 47 files that use it"           │
+                    │                                                             │
+                    └─────────────────────────────────────────────────────────────┘
+```
+
+## Why Code Graph Context?
+
+| Without Code Graph | With Code Graph |
+|---|---|
+| Claude reads files one at a time | Claude understands the entire dependency tree |
+| "What uses this?" requires manual searching | Instant impact analysis with risk scoring |
+| Refactoring misses edge cases | Graph traversal finds every reference |
+| Large codebases overwhelm context | Semantic search finds exactly what's relevant |
+| Multi-file changes are error-prone | Swarm agents coordinate parallel changes |
 
 ## Features
 
-- **Multi-Project Support**: Parse and query multiple projects in a single database with complete isolation via `projectId`
-- **Rich Code Graph Generation**: Parses TypeScript projects and creates detailed graph representations with AST-level precision
-- **Semantic Search**: Vector-based semantic search using OpenAI embeddings to find relevant code patterns and implementations
-- **Natural Language Querying**: Convert natural language questions into Cypher queries using OpenAI assistants API
-- **Framework-Aware & Customizable**: Built-in NestJS schema with ability to define custom framework patterns via configuration
-- **Weighted Graph Traversal**: Intelligent traversal that scores paths based on relationship importance, query relevance, and depth
-- **Workspace & Monorepo Support**: Auto-detects Nx, Turborepo, pnpm, Yarn, and npm workspaces
-- **Parallel Parsing**: Multi-threaded parsing with configurable worker pool for maximum CPU utilization
-- **Async Parsing**: Background parsing with Worker threads for large codebases without blocking the MCP server
-- **Streaming Import**: Chunked processing for projects with 100+ files to prevent memory issues
-- **TypeAlias Support**: Full parsing of TypeScript type aliases into graph nodes
-- **Incremental Parsing**: Only reparse changed files for faster updates
-- **File Watching**: Real-time monitoring with automatic incremental graph updates on file changes
-- **Impact Analysis**: Assess refactoring risk with dependency analysis (LOW/MEDIUM/HIGH/CRITICAL scoring)
-- **Dead Code Detection**: Find unreferenced exports, uncalled private methods, unused interfaces with confidence scoring
-- **Duplicate Code Detection**: Identify structural duplicates (identical AST) and semantic duplicates (similar logic via embeddings)
-- **Swarm Coordination**: Multi-agent stigmergic coordination through pheromone markers with exponential decay
-- **High Performance**: Optimized Neo4j storage with vector indexing for fast retrieval
-- **MCP Integration**: Seamless integration with Claude Code and other MCP-compatible tools
+- **Multi-Project Support**: Parse and query multiple projects in a single database with complete isolation
+- **Semantic Search**: Vector-based search using OpenAI embeddings to find relevant code
+- **Natural Language Querying**: Convert questions into Cypher queries
+- **Framework-Aware**: Built-in NestJS schema with ability to define custom framework patterns
+- **Weighted Graph Traversal**: Intelligent traversal scoring paths by importance and relevance
+- **Workspace Support**: Auto-detects Nx, Turborepo, pnpm, Yarn, and npm workspaces
+- **Parallel & Async Parsing**: Multi-threaded parsing with Worker threads for large codebases
+- **Streaming Import**: Chunked processing for projects with 100+ files
+- **Incremental Parsing**: Only reparse changed files
+- **File Watching**: Real-time graph updates on file changes
+- **Impact Analysis**: Assess refactoring risk (LOW/MEDIUM/HIGH/CRITICAL)
+- **Dead Code Detection**: Find unreferenced exports with confidence scoring
+- **Duplicate Detection**: Structural (AST hash) and semantic (embedding similarity) duplicates
+- **Swarm Coordination**: Multi-agent stigmergic coordination with pheromone decay
 
 ## Architecture
 
-The MCP server consists of several key components:
-
-### Core Components
-
-1. **TypeScript Parser** (`src/core/parsers/typescript-parser-v2.ts`): Uses `ts-morph` to parse TypeScript AST and extract code entities
-2. **Graph Storage** (`src/storage/neo4j/neo4j.service.ts`): Neo4j integration for storing and querying the code graph
-3. **Embeddings Service** (`src/core/embeddings/embeddings.service.ts`): OpenAI integration for semantic search capabilities
-4. **MCP Server** (`src/mcp/mcp.server.ts`): Main MCP server providing tools for code analysis
+```
+TypeScript Source → AST Parser (ts-morph) → Neo4j Graph + Vector Embeddings → MCP Tools
+```
 
-### Graph Schema
+**Core Components:**
+- `src/core/parsers/typescript-parser.ts` - AST parsing with ts-morph
+- `src/storage/neo4j/neo4j.service.ts` - Graph storage and queries
+- `src/core/embeddings/embeddings.service.ts` - OpenAI embeddings
+- `src/mcp/mcp.server.ts` - MCP server and tool registration
 
-The system uses a dual-schema approach:
+**Dual-Schema System:**
+- **Core Schema**: AST-level nodes (ClassDeclaration, MethodDeclaration, ImportDeclaration, etc.)
+- **Framework Schema**: Semantic interpretation (NestController, NestService, HttpEndpoint, etc.)
 
-- **Core Schema**: AST-level nodes (Classes, Methods, Properties, Imports, etc.)
-- **Framework Schema**: Semantic interpretations (NestJS Controllers, Services, HTTP Endpoints, etc.)
+Nodes have both `coreType` (AST) and `semanticType` (framework meaning), enabling queries like "find all controllers" while maintaining AST precision.
 
-## Getting Started
+## Quick Start
 
 ### Prerequisites
 
 - **Node.js** >= 18
-- **Neo4j** >= 5.23 with APOC plugin
-- **OpenAI API Key** (for embeddings and natural language processing)
-- **Docker** (recommended for Neo4j setup)
+- **Docker** (for Neo4j)
+- **OpenAI API Key**
 
-### Installation
 
-Choose the installation method that works best for you:
 
-#### Option 1: NPM Install (Recommended)
+### 1. Install
 
 ```bash
-# Install globally
 npm install -g code-graph-context
+code-graph-context init  # Sets up Neo4j via Docker
+```
 
-# Set up Neo4j (requires Docker)
-code-graph-context init
+### 2. Configure Claude Code
 
-# Add to Claude Code
-claude mcp add code-graph-context code-graph-context
+Add to Claude Code with your OpenAI API key:
+
+```bash
+claude mcp add --scope user code-graph-context \
+  -e OPENAI_API_KEY=sk-your-key-here \
+  -- code-graph-context
 ```
 
-Then configure your OpenAI API key in `~/.config/claude/config.json`:
+**That's it.** Restart Claude Code and you're ready to go.
+
+### 3. Parse Your Project
+
+In Claude Code, say:
+> "Parse this project and build the code graph"
+
+Claude will run `parse_typescript_project` and index your codebase.
+
+---
+
+## Configuration Files
+
+Claude Code stores MCP server configs in JSON files. The location depends on scope:
+
+| Scope | File | Use Case |
+|-------|------|----------|
+| User (global) | `~/.claude.json` | Available in all projects |
+| Project | `.claude.json` in project root | Project-specific config |
+| Local | `.mcp.json` in project root | Git-ignored local overrides |
+
+### Manual Configuration
+
+If you prefer to edit the config files directly:
+
+**~/.claude.json** (user scope - recommended):
 ```json
 {
   "mcpServers": {
@@ -92,1187 +154,476 @@ Then configure your OpenAI API key in `~/.config/claude/config.json`:
 }
 ```
 
-#### Option 2: From Source
-
-```bash
-# Clone and build
-git clone https://github.com/drewdrewH/code-graph-context.git
-cd code-graph-context
-npm install
-npm run build
-
-# Set up Neo4j
-code-graph-context init
-
-# Add to Claude Code (use absolute path)
-claude mcp add code-graph-context node /absolute/path/to/code-graph-context/dist/cli/cli.js
+**From source installation:**
+```json
+{
+  "mcpServers": {
+    "code-graph-context": {
+      "command": "node",
+      "args": ["/absolute/path/to/code-graph-context/dist/cli/cli.js"],
+      "env": {
+        "OPENAI_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
 ```
 
-### CLI Commands
+### Environment Variables
 
-The package includes a CLI for managing Neo4j:
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENAI_API_KEY` | **Yes** | - | For embeddings and NL queries |
+| `NEO4J_URI` | No | `bolt://localhost:7687` | Neo4j connection URI |
+| `NEO4J_USER` | No | `neo4j` | Neo4j username |
+| `NEO4J_PASSWORD` | No | `PASSWORD` | Neo4j password |
 
-```bash
-code-graph-context init [options]   # Set up Neo4j container
-code-graph-context status           # Check Docker/Neo4j status
-code-graph-context stop             # Stop Neo4j container
-```
+---
 
-**Init options:**
-```
--p, --port <port>       Bolt port (default: 7687)
---http-port <port>      Browser port (default: 7474)
---password <password>   Neo4j password (default: PASSWORD)
--m, --memory <size>     Heap memory (default: 2G)
--f, --force             Recreate container
-```
+## Core Capabilities
 
-### Alternative Neo4j Setup
+### Semantic Code Search
 
-If you prefer not to use the CLI, you can set up Neo4j manually:
+Find code by describing what you need, not by memorizing file paths:
 
-**Docker Compose:**
-```bash
-docker-compose up -d
 ```
-
-**Docker Run:**
-```bash
-docker run -d \
-  --name code-graph-neo4j \
-  -p 7474:7474 -p 7687:7687 \
-  -e NEO4J_AUTH=neo4j/PASSWORD \
-  -e 'NEO4J_PLUGINS=["apoc"]' \
-  neo4j:5.23
+"Find where user authentication tokens are validated"
+"Show me the database connection pooling logic"
+"What handles webhook signature verification?"
 ```
 
-**Neo4j Desktop:** Download from [neo4j.com/download](https://neo4j.com/download/) and install APOC plugin.
-
-**Neo4j Aura (Cloud):** Create account at [neo4j.com/cloud/aura](https://neo4j.com/cloud/platform/aura-graph-database/) and configure connection URI in env vars.
-
-### Verify Installation
+### Impact Analysis
 
-After installation, verify everything is working:
+Before you refactor, understand the blast radius:
 
-1. **Check Neo4j is running:**
-```bash
-# Open Neo4j Browser
-open http://localhost:7474
-# Login: neo4j / PASSWORD
 ```
-
-2. **Test APOC plugin:**
-```cypher
-CALL apoc.help("apoc")
+┌─────────────────────────────────────────────────────────────┐
+│ Impact Analysis: UserService.findById()                     │
+├─────────────────────────────────────────────────────────────┤
+│ Risk Level: HIGH                                            │
+│                                                             │
+│ Direct Dependents (12):                                     │
+│   └── AuthController.login()                                │
+│   └── ProfileController.getProfile()                        │
+│   └── AdminService.getUserDetails()                         │
+│   └── ... 9 more                                            │
+│                                                             │
+│ Transitive Dependents (34):                                 │
+│   └── 8 controllers, 15 services, 11 tests                  │
+│                                                             │
+│ Affected Files: 23                                          │
+│ Recommendation: Add deprecation warning before changing     │
+└─────────────────────────────────────────────────────────────┘
 ```
-Should return a list of APOC functions.
 
-3. **Test MCP server connection:**
-```bash
-claude mcp list
-```
-Should show: `code-graph-context: ✓ Connected`
-
-### Troubleshooting
+### Graph Traversal
 
-**"APOC plugin not found"**
-```bash
-# Check Neo4j logs
-docker logs code-graph-neo4j
+Explore relationships in any direction:
 
-# Verify APOC loaded
-docker exec code-graph-neo4j cypher-shell -u neo4j -p PASSWORD "CALL apoc.help('apoc')"
-
-# Restart if needed
-docker restart code-graph-neo4j
+```
+UserController
+    │
+    ├── INJECTS ──► UserService
+    │                   │
+    │                   ├── INJECTS ──► UserRepository
+    │                   │                   │
+    │                   │                   └── MANAGES ──► User (Entity)
+    │                   │
+    │                   └── INJECTS ──► CacheService
+    │
+    └── EXPOSES ──► POST /users
+                        │
+                        └── ACCEPTS ──► CreateUserDTO
 ```
 
-**"OPENAI_API_KEY environment variable is required"**
-- Get your API key from: https://platform.openai.com/api-keys
-- Add to Claude Code MCP config `env` section
-- Verify with: `echo $OPENAI_API_KEY` (if using shell env)
-
-**"Connection refused bolt://localhost:7687"**
-```bash
-# Check Neo4j is running
-docker ps | grep neo4j
-
-# Check ports are not in use
-lsof -i :7687
+### Dead Code Detection
 
-# Start Neo4j if stopped
-docker start code-graph-neo4j
+Find code that can be safely removed:
 
-# Check Neo4j logs
-docker logs code-graph-neo4j
 ```
-
-**"Neo4j memory errors"**
-```bash
-# Increase memory in docker-compose.yml or docker run:
--e NEO4J_server_memory_heap_max__size=8G
--e NEO4J_dbms_memory_transaction_total_max=8G
-
-docker restart code-graph-neo4j
+Dead Code Analysis: 47 items found
+├── HIGH confidence (23): Exported but never imported
+│   └── formatLegacyDate() in src/utils/date.ts:45
+│   └── UserV1DTO in src/dto/legacy/user.dto.ts:12
+│   └── ... 21 more
+├── MEDIUM confidence (18): Private, never called
+└── LOW confidence (6): May be used dynamically
 ```
 
-**"MCP server not responding"**
-```bash
-# Check Claude Code logs
-cat ~/Library/Logs/Claude/mcp*.log
+### Duplicate Code Detection
 
-# Test server directly
-node /path/to/code-graph-context/dist/mcp/mcp.server.js
+Identify DRY violations across your codebase:
 
-# Rebuild if needed
-npm run build
 ```
+Duplicate Groups Found: 8
 
-## Tool Usage Guide
-
-### Available Tools
-
-| Tool | Description | Best For |
-|------|-------------|----------|
-| `list_projects` | List all parsed projects in database | **Discovery** - see available projects and their status |
-| `search_codebase` | Semantic search using vector embeddings | **Starting point** - find code by describing what you need |
-| `traverse_from_node` | Explore relationships from a specific node | **Deep dive** - understand dependencies and connections |
-| `impact_analysis` | Analyze what depends on a node | **Pre-refactoring** - assess blast radius (LOW/MEDIUM/HIGH/CRITICAL) |
-| `parse_typescript_project` | Parse project and build the graph | **Initial setup** - supports async mode for large projects |
-| `check_parse_status` | Monitor async parsing job progress | **Monitoring** - track background parsing jobs |
-| `start_watch_project` | Start file watching for a project | **Live updates** - auto-update graph on file changes |
-| `stop_watch_project` | Stop file watching for a project | **Resource management** - stop monitoring |
-| `list_watchers` | List all active file watchers | **Monitoring** - see what's being watched |
-| `natural_language_to_cypher` | Convert natural language to Cypher | **Advanced queries** - complex graph queries |
-| `detect_dead_code` | Find unreferenced exports, uncalled methods, unused interfaces | **Code cleanup** - identify potentially removable code |
-| `detect_duplicate_code` | Find structural and semantic code duplicates | **Refactoring** - identify DRY violations |
-| `swarm_pheromone` | Leave pheromone markers on code nodes | **Multi-agent** - stigmergic coordination |
-| `swarm_sense` | Query pheromones in the code graph | **Multi-agent** - sense what other agents are doing |
-| `swarm_cleanup` | Bulk delete pheromones | **Multi-agent** - cleanup after swarm completion |
-| `test_neo4j_connection` | Verify database connectivity | **Health check** - troubleshooting |
-
-> **Note**: All query tools (`search_codebase`, `traverse_from_node`, `impact_analysis`, `natural_language_to_cypher`) require a `projectId` parameter. Use `list_projects` to discover available projects.
-
-### Tool Selection Guide
+Group 1 (Structural - 100% identical):
+├── validateEmail() in src/auth/validation.ts:23
+└── validateEmail() in src/user/validation.ts:45
+    Recommendation: Extract to shared utils
 
-- **`list_projects`**: First step - discover what projects are available
-- **`search_codebase`**: Find code by describing what you're looking for
-- **`traverse_from_node`**: Use node IDs from search results to explore relationships
-- **`impact_analysis`**: Before refactoring - understand what depends on the code you're changing
-
-### Multi-Project Workflow
-
-All query tools require a `projectId` parameter to ensure project isolation. You can provide:
+Group 2 (Semantic - 94% similar):
+├── parseUserInput() in src/api/parser.ts:78
+└── sanitizeInput() in src/webhook/parser.ts:34
+    Recommendation: Review for consolidation
+```
 
-1. **Project ID**: `proj_a1b2c3d4e5f6` (auto-generated from path)
-2. **Project Name**: `my-backend` (extracted from package.json or directory name)
-3. **Project Path**: `/path/to/my-backend` (resolved to project ID)
+---
 
-**Typical Workflow:**
+## Swarm Coordination
+
+**Execute complex, multi-file changes with parallel AI agents.**
+
+The swarm system enables multiple Claude agents to work on your codebase simultaneously, coordinating through the code graph without stepping on each other.
+
+```
+                         ┌──────────────────┐
+                         │   ORCHESTRATOR   │
+                         │                  │
+                         │ "Add JSDoc to    │
+                         │  all services"   │
+                         └────────┬─────────┘
+                                  │
+                    ┌─────────────┼─────────────┐
+                    │             │             │
+                    ▼             ▼             ▼
+             ┌──────────┐  ┌──────────┐  ┌──────────┐
+             │ Worker 1 │  │ Worker 2 │  │ Worker 3 │
+             │          │  │          │  │          │
+             │ Claiming │  │ Working  │  │ Claiming │
+             │ AuthSvc  │  │ UserSvc  │  │ PaySvc   │
+             └──────────┘  └──────────┘  └──────────┘
+                    │             │             │
+                    └─────────────┼─────────────┘
+                                  │
+                                  ▼
+                    ┌─────────────────────────────┐
+                    │      PHEROMONE TRAILS       │
+                    │                             │
+                    │  AuthService: [claimed]     │
+                    │  UserService: [modifying]   │
+                    │  PayService:  [claimed]     │
+                    │  CacheService: [available]  │
+                    │                             │
+                    └─────────────────────────────┘
+```
+
+### Two Coordination Mechanisms
+
+#### 1. Pheromone System (Stigmergic)
+
+Agents leave markers on code nodes that decay over time—like ants leaving scent trails:
+
+| Pheromone | Half-Life | Meaning |
+|-----------|-----------|---------|
+| `exploring` | 2 min | "I'm looking at this" |
+| `claiming` | 1 hour | "This is my territory" |
+| `modifying` | 10 min | "I'm actively changing this" |
+| `completed` | 24 hours | "I finished work here" |
+| `warning` | Never | "Don't touch this" |
+| `blocked` | 5 min | "I'm stuck" |
+
+**Self-healing**: If an agent crashes, its pheromones decay and the work becomes available again.
+
+#### 2. Task Queue (Blackboard)
+
+Explicit task management with dependencies:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        TASK QUEUE                           │
+├─────────────────────────────────────────────────────────────┤
+│ [available] Add JSDoc to UserService         priority: high │
+│ [claimed]   Add JSDoc to AuthService         agent: worker1 │
+│ [blocked]   Update API docs ─────────────────► depends on ──┤
+│ [in_progress] Add JSDoc to PaymentService    agent: worker2 │
+│ [completed] Add JSDoc to CacheService        ✓              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Swarm Tools
+
+| Tool | Purpose |
+|------|---------|
+| `swarm_orchestrate` | Decompose a task and spawn worker agents |
+| `swarm_post_task` | Add a task to the queue |
+| `swarm_get_tasks` | Query tasks with filters |
+| `swarm_claim_task` | Claim/start/release a task |
+| `swarm_complete_task` | Complete/fail/request review |
+| `swarm_pheromone` | Leave a marker on a code node |
+| `swarm_sense` | Query what other agents are doing |
+| `swarm_cleanup` | Remove pheromones after completion |
+
+### Example: Parallel Refactoring
 
 ```typescript
-// Step 1: Discover available projects
-list_projects()
-// Returns: project names, IDs, status, node/edge counts
-
-// Step 2: Parse a new project (if not already parsed)
-parse_typescript_project({
-  projectPath: '/path/to/project',
-  tsconfigPath: '/path/to/project/tsconfig.json'
+// Orchestrator decomposes and creates tasks
+swarm_orchestrate({
+  projectId: "backend",
+  task: "Rename getUserById to findUserById across the codebase",
+  maxAgents: 3
 })
-// Returns: projectId for use in queries
-
-// Step 3: Query the project using any of these ID formats
-search_codebase({ projectId: "my-backend", query: "authentication" })
-search_codebase({ projectId: "proj_a1b2c3d4e5f6", query: "authentication" })
-search_codebase({ projectId: "/path/to/my-backend", query: "authentication" })
-```
-
-**Pro Tips:**
-- Use project names instead of full IDs for convenience
-- Run `list_projects` first to see what's available
-- Each project is completely isolated - queries never cross project boundaries
-
-### Sequential Workflow Patterns
-
-The MCP tools are designed to work together in powerful workflows. Here are the most effective patterns:
-
-#### Pattern 1: Discovery → Focus → Deep Dive
-```mermaid
-graph LR
-    A[search_codebase] --> B[traverse_from_node] --> C[traverse_from_node with skip]
-    A --> D[traverse_from_node] --> E[traverse_from_node deeper]
-```
-
-#### Pattern 2: Broad Search → Targeted Analysis
-1. **Start Broad**: Use `search_codebase` to find relevant starting points
-2. **Focus**: Use `traverse_from_node` to explore specific relationships
-3. **Paginate**: Use `skip` parameter to explore different sections of the graph
 
-### Tool Deep Dive
-
-#### 1. `search_codebase` - Your Starting Point
-**Purpose**: Semantic search using vector embeddings to find the most relevant code nodes.
-
-**Response Structure**: Returns normalized JSON using JSON:API pattern to eliminate duplication:
-- **nodes**: Map of unique nodes (stored once, referenced by ID)
-- **depths**: Array of depth levels with relationship chains
-- **Source Code**: Included by default (truncated to 1000 chars: first 500 + last 500)
-- **Statistics**: Total connections, unique files, max depth
-
-**Real Response Example**:
-```json
-// Query: "JWT token validation"
-// Returns:
+// Returns a plan:
 {
-  "totalConnections": 22,
-  "uniqueFiles": 2,
-  "maxDepth": 3,
-  "startNodeId": "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b",
-  "nodes": {
-    "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b": {
-      "id": "MethodDeclaration:697d2c96-1f91-4894-985d-1eece117b72b",
-      "type": "MethodDeclaration",
-      "filePath": "/packages/jwt-validation/src/lib/jwt.strategy.ts",
-      "name": "validate",
-      "sourceCode": "validate(payload: EmJwtPayload): EmJwtPayload {\n  ...\n\n... [truncated] ...\n\n  return payload;\n}",
-      "hasMore": true,
-      "truncated": 1250
-    },
-    "ClassDeclaration:abc-123": {
-      "id": "ClassDeclaration:abc-123",
-      "type": "Service",
-      "filePath": "/packages/jwt-validation/src/lib/jwt.strategy.ts",
-      "name": "JwtStrategy"
-    }
+  swarmId: "swarm_abc123",
+  plan: {
+    totalTasks: 12,
+    parallelizable: 8,
+    sequential: 4,  // These have dependencies
+    tasks: [
+      { id: "task_1", title: "Update UserService.findUserById", status: "available" },
+      { id: "task_2", title: "Update UserController references", status: "blocked", depends: ["task_1"] },
+      ...
+    ]
   },
-  "depths": [
-    {
-      "depth": 1,
-      "count": 8,
-      "chains": [
-        {
-          "via": "HAS_MEMBER",
-          "direction": "INCOMING",
-          "count": 1,
-          "nodeIds": ["ClassDeclaration:abc-123"]
-        },
-        {
-          "via": "HAS_PARAMETER",
-          "direction": "OUTGOING",
-          "count": 2,
-          "nodeIds": ["Parameter:xyz-456", "Parameter:def-789"]
-        }
-      ]
-    },
-    {
-      "depth": 2,
-      "count": 14,
-      "chains": [
-        {
-          "via": "HAS_MEMBER → INJECTS",
-          "direction": "INCOMING",
-          "count": 3,
-          "nodeIds": ["Service:auth-service", "Service:user-service", "Repository:user-repo"],
-          "hasMore": 2
-        }
-      ]
-    }
-  ]
+  workerInstructions: "..."  // Copy-paste to spawn workers
 }
 ```
 
-**Key Features**:
-- **JSON:API Normalization**: Nodes stored once in `nodes` map, referenced by ID to eliminate duplication
-- **Source Code Truncation**: Max 1000 chars per snippet (first 500 + last 500 chars)
-- **Relationship Chains**: Shows full path like "HAS_MEMBER → INJECTS → USES_REPOSITORY"
-- **Direction Indicators**: OUTGOING (what this calls), INCOMING (who calls this)
-
-**Pro Tips**:
-- Use specific domain terms: "JWT token validation" vs "authentication"
-- Start with limit=1-3 for initial exploration to avoid token limits
-- Look for node IDs in `nodes` map to use with `traverse_from_node`
-- Check `truncated` field to see how many bytes were hidden from source code
+### Install the Swarm Skill
 
-#### 2. `traverse_from_node` - Deep Relationship Exploration
-**Purpose**: Explore all connections from a specific node with precise control over depth and pagination.
+For optimal swarm execution, install the included Claude Code skill that teaches agents the coordination protocol:
 
-**Response Structure**: Identical JSON:API format to search_codebase:
-- **Focused Traversal**: Starts from your specified node
-- **Depth Control**: Configurable max depth (1-10, default 3)
-- **Pagination**: Skip parameter for exploring large graphs in chunks
-- **Source Code Included by Default**: Set `includeCode: false` for structure-only view
-
-**Real Response Example**:
-```json
-// Starting from a Service class
-// maxDepth: 2, skip: 0, includeCode: true
-{
-  "totalConnections": 15,
-  "uniqueFiles": 4,
-  "maxDepth": 2,
-  "startNodeId": "ClassDeclaration:credit-check-service",
-  "nodes": {
-    "ClassDeclaration:credit-check-service": {
-      "id": "ClassDeclaration:credit-check-service",
-      "type": "Service",
-      "filePath": "/src/modules/credit/credit-check.service.ts",
-      "name": "CreditCheckService",
-      "sourceCode": "@Injectable([CreditCheckRepository, OscilarClient])\nexport class CreditCheckService {\n  ...\n\n... [truncated] ...\n\n}",
-      "truncated": 3200
-    },
-    "Repository:credit-check-repo": {
-      "id": "Repository:credit-check-repo",
-      "type": "Repository",
-      "filePath": "/src/modules/credit/credit-check.repository.ts",
-      "name": "CreditCheckRepository"
-    }
-  },
-  "depths": [
-    {
-      "depth": 1,
-      "count": 5,
-      "chains": [
-        {
-          "via": "INJECTS",
-          "direction": "OUTGOING",
-          "count": 2,
-          "nodeIds": ["Repository:credit-check-repo", "VendorClient:oscilar"]
-        },
-        {
-          "via": "HAS_MEMBER",
-          "direction": "OUTGOING",
-          "count": 3,
-          "nodeIds": ["Method:processCheck", "Method:getResult", "Method:rerun"]
-        }
-      ]
-    },
-    {
-      "depth": 2,
-      "count": 10,
-      "chains": [
-        {
-          "via": "INJECTS → USES_DAL",
-          "direction": "OUTGOING",
-          "count": 1,
-          "nodeIds": ["DAL:application-dal"]
-        }
-      ]
-    }
-  ]
-}
+```bash
+# Copy to your global skills directory
+mkdir -p ~/.claude/skills
+cp -r skills/swarm ~/.claude/skills/
 ```
 
-**Parameters**:
-- `nodeId` (required): Node ID from search_codebase results
-- `maxDepth` (default: 3): Traversal depth (1-10)
-- `skip` (default: 0): Pagination offset
-- `includeCode` (default: **true**): Include source code snippets
-- `summaryOnly` (default: false): Just file paths and statistics
-- `direction` (default: BOTH): Filter by OUTGOING/INCOMING/BOTH
-- `relationshipTypes` (optional): Filter by specific relationships like ["INJECTS", "USES_REPOSITORY"]
-
-**Pagination Strategy**:
-```typescript
-// Note: Pagination removed in recent commits - all results returned
-// Use depth and relationship filtering instead
-traverse_from_node({
-  nodeId,
-  maxDepth: 2,
-  relationshipTypes: ["INJECTS"]  // Focus on dependency injection only
-})
+Or for a specific project:
+```bash
+cp -r skills/swarm .claude/skills/
 ```
 
-#### 3. `parse_typescript_project` - Graph Generation
-**Purpose**: Parse a TypeScript/NestJS project and build the graph database.
-
-**Parameters:**
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `projectPath` | string | required | Path to project root directory |
-| `tsconfigPath` | string | required | Path to tsconfig.json |
-| `projectId` | string | auto | Override auto-generated project ID |
-| `clearExisting` | boolean | true | Clear existing data (false = incremental) |
-| `async` | boolean | false | Run in background Worker thread |
-| `useStreaming` | enum | "auto" | "auto", "always", or "never" |
-| `chunkSize` | number | 50 | Files per chunk for streaming |
-| `projectType` | enum | "auto" | "auto", "nestjs", "vanilla" |
-| `watch` | boolean | false | Start file watching after parse (requires `async: false`) |
-| `watchDebounceMs` | number | 1000 | Debounce delay for watch mode in ms |
+The skill provides:
+- Worker agent protocol with step-by-step workflow
+- Multi-phase orchestration patterns (discovery, contracts, implementation, validation)
+- Common failure modes and how to prevent them
+- Complete tool reference
 
-```typescript
-// Standard parsing (blocking)
-await mcp.call('parse_typescript_project', {
-  projectPath: '/path/to/project',
-  tsconfigPath: '/path/to/project/tsconfig.json'
-});
-// Returns: projectId for use in queries
-
-// Async parsing for large projects (non-blocking)
-await mcp.call('parse_typescript_project', {
-  projectPath: '/path/to/large-project',
-  tsconfigPath: '/path/to/large-project/tsconfig.json',
-  async: true  // Returns immediately with job ID
-});
-// Returns: "Job ID: job_abc123... Use check_parse_status to monitor."
-
-// Check async job progress
-await mcp.call('check_parse_status', { jobId: 'job_abc123' });
-// Returns: progress %, phase, nodes/edges imported
-
-// Incremental parsing (only changed files)
-await mcp.call('parse_typescript_project', {
-  projectPath: '/path/to/project',
-  tsconfigPath: '/path/to/project/tsconfig.json',
-  clearExisting: false  // Keep existing, only reparse changed files
-});
-
-// Parse and start file watching
-await mcp.call('parse_typescript_project', {
-  projectPath: '/path/to/project',
-  tsconfigPath: '/path/to/project/tsconfig.json',
-  watch: true,           // Start watching after parse completes
-  watchDebounceMs: 1000  // Wait 1s after last change before updating
-});
-// File changes now automatically trigger incremental graph updates
-```
+Once installed, just say "swarm" or "parallel agents" and Claude will use the skill automatically.
 
-**Modes:**
-- **Standard**: Blocks until complete, best for small-medium projects
-- **Async**: Returns immediately, use `check_parse_status` to monitor
-- **Streaming**: Auto-enabled for projects >100 files, prevents OOM
-- **Incremental**: Set `clearExisting: false` to only reparse changed files
-- **Watch**: Set `watch: true` to automatically update graph on file changes (requires sync mode)
+See [`skills/swarm/SKILL.md`](skills/swarm/SKILL.md) for the full documentation.
 
-**Performance Notes**:
-- Large projects (>1000 files) should use `async: true`
-- Streaming is auto-enabled for projects >100 files
-- Incremental mode detects changes via mtime, size, and content hash
-- Worker threads have 30-minute timeout and 8GB heap limit
+---
 
-#### 4. `test_neo4j_connection` - Health Check
-**Purpose**: Verify database connectivity and APOC plugin availability.
+## All Tools
 
-```typescript
-// Simple health check
-await mcp.call('test_neo4j_connection');
+| Tool | Description |
+|------|-------------|
+| **Discovery** | |
+| `list_projects` | List parsed projects in the database |
+| `search_codebase` | Semantic search using vector embeddings |
+| `traverse_from_node` | Explore relationships from a node |
+| `natural_language_to_cypher` | Convert questions to Cypher queries |
+| **Analysis** | |
+| `impact_analysis` | Assess refactoring risk (LOW/MEDIUM/HIGH/CRITICAL) |
+| `detect_dead_code` | Find unreferenced exports and methods |
+| `detect_duplicate_code` | Find structural and semantic duplicates |
+| **Parsing** | |
+| `parse_typescript_project` | Build the graph from source |
+| `check_parse_status` | Monitor async parsing jobs |
+| `start_watch_project` | Auto-update graph on file changes |
+| `stop_watch_project` | Stop file watching |
+| `list_watchers` | List active file watchers |
+| **Swarm** | |
+| `swarm_orchestrate` | Plan and spawn parallel agents |
+| `swarm_post_task` | Add task to the queue |
+| `swarm_get_tasks` | Query tasks |
+| `swarm_claim_task` | Claim/start/release tasks |
+| `swarm_complete_task` | Complete/fail/review tasks |
+| `swarm_pheromone` | Leave coordination markers |
+| `swarm_sense` | Query what others are doing |
+| `swarm_cleanup` | Clean up after swarm completion |
+| **Utility** | |
+| `test_neo4j_connection` | Verify database connectivity |
 
-// Response indicates database status
-"Neo4j connected: Connected! at 2025-07-25T19:48:42.676Z
-APOC plugin available with 438 functions"
-```
+### Tool Workflow Patterns
 
-#### 5. `detect_dead_code` - Code Cleanup Analysis
-**Purpose**: Identify potentially dead code including unreferenced exports, uncalled private methods, and unused interfaces.
-
-**Parameters:**
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `projectId` | string | required | Project ID, name, or path |
-| `excludePatterns` | string[] | [] | Additional file patterns to exclude (e.g., `["*.config.ts"]`) |
-| `excludeSemanticTypes` | string[] | [] | Additional semantic types to exclude (e.g., `["EntityClass"]`) |
-| `minConfidence` | enum | "LOW" | Minimum confidence: "LOW", "MEDIUM", "HIGH" |
-| `summaryOnly` | boolean | false | Return only statistics, not full list |
-| `limit` | number | 100 | Maximum items to return |
-| `offset` | number | 0 | Pagination offset |
-
-**Response Structure:**
-```json
-{
-  "summary": "Found 15 potentially dead code items",
-  "riskLevel": "MEDIUM",
-  "statistics": {
-    "total": 15,
-    "byConfidence": { "HIGH": 5, "MEDIUM": 7, "LOW": 3 },
-    "byCategory": { "internal-unused": 10, "library-export": 3, "ui-component": 2 },
-    "byType": { "FunctionDeclaration": 8, "InterfaceDeclaration": 4, "MethodDeclaration": 3 }
-  },
-  "deadCode": [
-    {
-      "nodeId": "proj_xxx:FunctionDeclaration:abc123",
-      "name": "unusedHelper",
-      "type": "FunctionDeclaration",
-      "filePath": "/src/utils/helpers.ts",
-      "lineNumber": 42,
-      "confidence": "HIGH",
-      "confidenceReason": "Exported but never imported anywhere",
-      "category": "internal-unused",
-      "reason": "Exported but never imported or referenced"
-    }
-  ]
-}
+**Pattern 1: Discovery → Focus → Deep Dive**
 ```
-
-**Framework-Aware Exclusions:**
-- Automatically excludes NestJS entry points (controllers, modules, guards, etc.)
-- Excludes common entry point files (`main.ts`, `*.module.ts`, `*.controller.ts`)
-- Excludes Next.js/React patterns (`page.tsx`, `layout.tsx`, `route.tsx`)
-
-```typescript
-// Basic usage
-await mcp.call('detect_dead_code', {
-  projectId: 'my-backend'
-});
-
-// High confidence only with custom exclusions
-await mcp.call('detect_dead_code', {
-  projectId: 'my-backend',
-  minConfidence: 'HIGH',
-  excludePatterns: ['*.seed.ts', '*.fixture.ts'],
-  excludeSemanticTypes: ['EntityClass', 'DTOClass']
-});
+list_projects → search_codebase → traverse_from_node → traverse (with skip for pagination)
 ```
 
-#### 6. `detect_duplicate_code` - DRY Violation Detection
-**Purpose**: Identify duplicate code using structural (identical AST) and semantic (similar embeddings) analysis.
-
-**Parameters:**
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `projectId` | string | required | Project ID, name, or path |
-| `type` | enum | "all" | Detection type: "structural", "semantic", "all" |
-| `scope` | enum | "all" | Scope: "methods", "functions", "classes", "all" |
-| `minSimilarity` | number | 0.8 | Minimum similarity threshold (0.5-1.0) |
-| `maxResults` | number | 50 | Maximum duplicate groups to return |
-| `includeCode` | boolean | true | Include source code snippets |
-| `summaryOnly` | boolean | false | Return only statistics |
-
-**Response Structure:**
-```json
-{
-  "summary": "Found 8 duplicate code groups across 12 files",
-  "statistics": {
-    "totalGroups": 8,
-    "totalDuplicates": 24,
-    "byType": {
-      "structural": { "groups": 3, "items": 9 },
-      "semantic": { "groups": 5, "items": 15 }
-    },
-    "byConfidence": { "HIGH": 4, "MEDIUM": 3, "LOW": 1 }
-  },
-  "duplicates": [
-    {
-      "groupId": "dup_1",
-      "type": "structural",
-      "similarity": 1.0,
-      "confidence": "HIGH",
-      "category": "cross-file",
-      "recommendation": "Extract to shared utility",
-      "items": [
-        {
-          "nodeId": "proj_xxx:MethodDeclaration:abc",
-          "name": "formatDate",
-          "filePath": "/src/utils/date.ts",
-          "lineNumber": 15,
-          "sourceCode": "formatDate(date: Date): string { ... }"
-        },
-        {
-          "nodeId": "proj_xxx:MethodDeclaration:def",
-          "name": "formatDate",
-          "filePath": "/src/helpers/formatting.ts",
-          "lineNumber": 42,
-          "sourceCode": "formatDate(date: Date): string { ... }"
-        }
-      ]
-    }
-  ]
-}
+**Pattern 2: Pre-Refactoring Safety**
 ```
-
-**Detection Types:**
-- **Structural**: Identical normalized code (same AST after removing comments, normalizing names)
-- **Semantic**: Similar logic via vector embeddings (requires embeddings enabled during parse)
-
-**Categories:**
-- `ui-component`: Duplicates in UI component directories
-- `cross-app`: Duplicates across monorepo apps
-- `same-file`: Duplicates within the same file
-- `cross-file`: Duplicates across different files
-
-```typescript
-// Find all duplicates
-await mcp.call('detect_duplicate_code', {
-  projectId: 'my-backend'
-});
-
-// Only structural duplicates in methods
-await mcp.call('detect_duplicate_code', {
-  projectId: 'my-backend',
-  type: 'structural',
-  scope: 'methods'
-});
-
-// High similarity semantic duplicates
-await mcp.call('detect_duplicate_code', {
-  projectId: 'my-backend',
-  type: 'semantic',
-  minSimilarity: 0.9
-});
-```
-
-#### 7. File Watching Tools
-**Purpose**: Monitor file changes and automatically update the graph.
-
-```typescript
-// Option 1: Start watching during parse
-await mcp.call('parse_typescript_project', {
-  projectPath: '/path/to/project',
-  tsconfigPath: '/path/to/project/tsconfig.json',
-  watch: true  // Starts watching after parse completes
-});
-
-// Option 2: Start watching a previously parsed project
-await mcp.call('start_watch_project', {
-  projectId: 'my-backend',      // Project name, ID, or path
-  debounceMs: 2000              // Optional: wait 2s after last change (default: 1000)
-});
-
-// List all active watchers
-await mcp.call('list_watchers');
-// Returns: watcher status, pending changes, last update time
-
-// Stop watching a project
-await mcp.call('stop_watch_project', {
-  projectId: 'my-backend'
-});
-```
-
-**How It Works:**
-1. File watcher monitors `.ts` and `.tsx` files using native OS events
-2. Changes are debounced to batch rapid edits
-3. Only modified files are re-parsed (incremental)
-4. Cross-file edges are preserved during updates
-5. Graph updates happen automatically in the background
-
-**Resource Limits:**
-- Maximum 10 concurrent watchers
-- 1000 pending events per watcher
-- Graceful cleanup on server shutdown
-
-#### 8. Swarm Coordination Tools
-**Purpose**: Enable multiple parallel agents to coordinate work through stigmergic pheromone markers in the code graph—no direct messaging needed.
-
-**Core Concepts:**
-- **Pheromones**: Markers attached to graph nodes that decay over time
-- **swarmId**: Groups related agents for bulk cleanup when done
-- **Workflow States**: `exploring`, `claiming`, `modifying`, `completed`, `blocked` (mutually exclusive per agent+node)
-- **Flags**: `warning`, `proposal`, `needs_review` (can coexist with workflow states)
-
-**Pheromone Types & Decay:**
-| Type | Half-Life | Use |
-|------|-----------|-----|
-| `exploring` | 2 min | Browsing/reading |
-| `modifying` | 10 min | Active work |
-| `claiming` | 1 hour | Ownership |
-| `completed` | 24 hours | Done |
-| `warning` | Never | Danger |
-| `blocked` | 5 min | Stuck |
-| `proposal` | 1 hour | Awaiting approval |
-| `needs_review` | 30 min | Review requested |
-
-```typescript
-// Orchestrator: Generate swarm ID and spawn agents
-const swarmId = `swarm_${Date.now()}`;
-
-// Agent: Check what's claimed before working
-await mcp.call('swarm_sense', {
-  projectId: 'my-backend',
-  swarmId,
-  types: ['claiming', 'modifying']
-});
-
-// Agent: Claim a node before working
-await mcp.call('swarm_pheromone', {
-  projectId: 'my-backend',
-  nodeId: 'proj_xxx:ClassDeclaration:abc123',  // From search_codebase or traverse_from_node
-  type: 'claiming',
-  agentId: 'agent_1',
-  swarmId
-});
-
-// Agent: Mark complete when done
-await mcp.call('swarm_pheromone', {
-  projectId: 'my-backend',
-  nodeId: 'proj_xxx:ClassDeclaration:abc123',
-  type: 'completed',
-  agentId: 'agent_1',
-  swarmId,
-  data: { summary: 'Added soft delete support' }
-});
-
-// Orchestrator: Clean up when swarm is done
-await mcp.call('swarm_cleanup', {
-  projectId: 'my-backend',
-  swarmId,
-  keepTypes: ['warning']  // Preserve warnings
-});
+search_codebase("function to change") → impact_analysis(nodeId) → review risk level
 ```
 
-**Important**: Node IDs must come from graph tool responses (`search_codebase`, `traverse_from_node`). Never fabricate node IDs—they are hash-based strings like `proj_xxx:ClassDeclaration:abc123`.
-
-### Workflow Examples
-
-#### Example 1: Understanding Authentication Flow
-```typescript
-// Step 1: Find authentication-related code
-const searchResult = await mcp.call('search_codebase', {
-  projectId: 'my-backend',  // Required: project name, ID, or path
-  query: 'JWT token validation authentication'
-});
-
-// Step 2: Extract node ID from most relevant result
-const nodeId = "proj_abc123:MethodDeclaration:697d2c96";
-
-// Step 3: Explore immediate relationships
-const immediateConnections = await mcp.call('traverse_from_node', {
-  projectId: 'my-backend',
-  nodeId,
-  maxDepth: 2
-});
-
-// Step 4: Go deeper to understand full authentication chain
-const deepConnections = await mcp.call('traverse_from_node', {
-  projectId: 'my-backend',
-  nodeId,
-  maxDepth: 4
-});
-
-// Step 5: Assess refactoring impact
-const impact = await mcp.call('impact_analysis', {
-  projectId: 'my-backend',
-  nodeId
-});
-// Returns: risk level (LOW/MEDIUM/HIGH/CRITICAL), dependents, affected files
+**Pattern 3: Code Health Audit**
 ```
-
-#### Example 2: API Endpoint Analysis
-```typescript
-// Step 1: Search for controller endpoints
-const controllerSearch = await mcp.call('search_codebase', {
-  projectId: 'my-backend',
-  query: 'HTTP controller endpoints routes POST GET'
-});
-
-// Step 2: Find a controller node ID from results
-const controllerNodeId = "proj_abc123:ClassDeclaration:controller-uuid";
-
-// Step 3: Explore what endpoints this controller exposes
-const endpoints = await mcp.call('traverse_from_node', {
-  projectId: 'my-backend',
-  nodeId: controllerNodeId,
-  maxDepth: 2
-});
-
-// Step 4: For each endpoint found, explore its dependencies
-const endpointNodeId = "proj_abc123:MethodDeclaration:endpoint-uuid";
-const endpointDeps = await mcp.call('traverse_from_node', {
-  projectId: 'my-backend',
-  nodeId: endpointNodeId,
-  maxDepth: 3
-});
+detect_dead_code → detect_duplicate_code → prioritize cleanup
 ```
 
-#### Example 3: Service Dependency Mapping
-```typescript
-// Step 1: Find a specific service
-const serviceSearch = await mcp.call('search_codebase', {
-  projectId: 'my-backend',
-  query: 'UserService injectable dependency injection'
-});
-
-// Step 2: Map all its dependencies (what it injects)
-const serviceDeps = await mcp.call('traverse_from_node', {
-  projectId: 'my-backend',
-  nodeId: "proj_abc123:ClassDeclaration:user-service-uuid",
-  maxDepth: 2,
-  direction: "OUTGOING"  // What this service depends on
-});
-
-// Step 3: Impact analysis - what depends on this service
-const impact = await mcp.call('impact_analysis', {
-  projectId: 'my-backend',
-  nodeId: "proj_abc123:ClassDeclaration:user-service-uuid"
-});
-// Returns: risk level, all dependents, affected files
+**Pattern 4: Multi-Agent Work**
 ```
-
-### Advanced Usage Tips
-
-#### Understanding Response Format (JSON:API Normalization)
-
-**Key Insight**: All responses use JSON:API pattern to eliminate duplication by storing each node once and referencing by ID.
-
-**How to Read Responses**:
-1. **Start with `nodes` map**: All unique nodes are stored here once
-2. **Look at `depths` array**: Shows how nodes are connected at each depth level
-3. **Follow `nodeIds` references**: Use IDs to look up full node data in `nodes` map
-4. **Check `truncated` field**: Indicates how many bytes of source code were hidden
-
-**Example Reading Pattern**:
-```typescript
-const response = await search_codebase({
-  projectId: "my-backend",
-  query: "authentication"
-});
-
-// 1. Get overview statistics
-console.log(`Found ${response.totalConnections} connections across ${response.uniqueFiles} files`);
-
-// 2. Examine the starting node
-const startNode = response.nodes[response.startNodeId];
-console.log(`Starting from: ${startNode.name} in ${startNode.filePath}`);
-
-// 3. Explore first depth level
-const firstDepth = response.depths[0];
-firstDepth.chains.forEach(chain => {
-  console.log(`Via ${chain.via}: ${chain.count} connections (${chain.direction})`);
-
-  // 4. Look up actual node details
-  chain.nodeIds.forEach(nodeId => {
-    const node = response.nodes[nodeId];
-    console.log(`  - ${node.name} (${node.type})`);
-  });
-});
+swarm_orchestrate → spawn workers → swarm_get_tasks(includeStats) → swarm_cleanup
 ```
 
-#### Managing Large Responses
-- **Relationship Filtering**: Use `relationshipTypes` to focus on specific connections
-- **Structure-Only View**: Set `includeCode: false` to exclude source code snippets
-- **Summary Mode**: Use `summaryOnly: true` for just file paths and statistics
-
-#### Efficient Graph Exploration
-- **Breadth First**: Start with low `maxDepth` (1-2) to get overview
-- **Depth Second**: Increase `maxDepth` (3-5) for detailed analysis
-- **Direction Filtering**: Use `direction: "OUTGOING"` or `"INCOMING"` to focus exploration
-- **Source Code on Demand**: Source code included by default but truncated to 1000 chars
+### Multi-Project Support
 
-#### Weighted Traversal
+All query tools require `projectId` for isolation. You can use:
+- **Project ID**: `proj_a1b2c3d4e5f6` (auto-generated)
+- **Project name**: `my-backend` (from package.json)
+- **Project path**: `/path/to/project` (resolved automatically)
 
-The `search_codebase` tool uses **weighted traversal** by default (`useWeightedTraversal: true`) to intelligently prioritize which relationships to explore. This produces more relevant results by scoring each node at every depth level.
-
-**How Scoring Works**:
-
-Each potential path is scored using three factors multiplied together:
-
-1. **Edge Weight** (0.0-1.0): How important is this relationship type?
-   - Critical (0.9-0.95): `INJECTS`, `EXPOSES`, `ROUTES_TO` - core architectural relationships
-   - High (0.8-0.88): `EXTENDS`, `IMPLEMENTS`, `USES_REPOSITORY` - important semantic links
-   - Medium (0.5-0.6): `IMPORTS`, `EXPORTS`, `HAS_MEMBER` - structural relationships
-   - Low (0.3-0.4): `DECORATED_WITH`, `HAS_PARAMETER` - metadata relationships
-
-2. **Node Similarity**: Cosine similarity between the node's embedding and your query embedding. Nodes semantically related to your search rank higher.
-
-3. **Depth Penalty**: Exponential decay (default 0.85 per level). Closer nodes are preferred:
-   - Depth 1: 1.0 (no penalty)
-   - Depth 2: 0.85
-   - Depth 3: 0.72
-
-**When to Disable**:
 ```typescript
-// Use standard traversal for exhaustive exploration
-search_codebase({
-  projectId: "my-backend",
-  query: "...",
-  useWeightedTraversal: false
-})
-```
-
-#### Performance Optimization
-- **Token Efficiency**: JSON:API normalization eliminates duplicate nodes in responses
-- **Code Truncation**: Source code limited to 1000 chars (first 500 + last 500) to prevent token overflow
-- **Memory**: Large traversals may hit Neo4j memory limits (increase heap size if needed)
-- **Caching**: Node IDs are persistent; save interesting ones for later exploration
-
-## Claude Code Integration Tips
-
-### Guiding Tool Usage with claude.md
-
-You can add a `claude.md` file to your repository root to help Claude Code understand when to use these MCP tools effectively. Here are some useful patterns:
-
-#### Trigger Word Hints
-
-```markdown
-## Code Search Tools
-
-**Use `search_codebase` for:**
-- "Where is...", "Find...", "Show me [specific thing]"
-- Example: "Where is the authentication middleware?"
-
-**Use `natural_language_to_cypher` for:**
-- "List all...", "How many...", "Count..."
-- Example: "List all API controllers"
-
-**Use `traverse_from_node` for:**
-- Deep dependency analysis after initial search
-- "What depends on X?", "Trace the flow..."
-```
-
-#### Weighted Traversal Hints
-
-```markdown
-**Use `useWeightedTraversal: true` for:**
-- Service/Controller classes with many dependencies
-- Queries with depth > 3
-- Cleaner, more relevant results
-
-**Recommended settings:**
-- Default: `maxDepth: 5, snippetLength: 900`
-- Simple lookups: `maxDepth: 2`
+// These all work:
+search_codebase({ projectId: "my-backend", query: "auth" })
+search_codebase({ projectId: "proj_a1b2c3d4e5f6", query: "auth" })
+search_codebase({ projectId: "/path/to/my-backend", query: "auth" })
 ```
 
-#### Framework-Specific Patterns
-
-Document your custom node types and relationships so Claude knows what to search for:
-
-```markdown
-**Custom Node Types:**
-- `PaymentProcessor` - Payment integrations
-- `EmailTemplate` - Email templates
-
-**Custom Relationships:**
-- `PROCESSES_PAYMENT` - Service → PaymentProcessor
-- `SENDS_EMAIL` - Service → EmailTemplate
-```
-
-#### Common Query Examples
-
-```markdown
-**Finding authentication:**
-search_codebase({ projectId: "my-project", query: "JWT authentication middleware" })
-
-**Tracing dependencies:**
-traverse_from_node({ projectId: "my-project", nodeId: "...", direction: "OUTGOING", maxDepth: 5 })
-
-**Impact analysis:**
-impact_analysis({ projectId: "my-project", nodeId: "..." })
-```
+---
 
 ## Framework Support
 
-### NestJS Framework Schema
+### NestJS (Built-in)
 
-The server provides deep understanding of NestJS patterns:
+Deep understanding of NestJS patterns:
 
-#### Node Types
-- **Controllers**: HTTP endpoint handlers with route analysis
-- **Services**: Business logic providers with dependency injection mapping
-- **Modules**: Application structure with import/export relationships
-- **Guards**: Authentication and authorization components
-- **Pipes**: Request validation and transformation
-- **Interceptors**: Request/response processing middleware
-- **DTOs**: Data transfer objects with validation decorators
-- **Entities**: Database models with relationship mapping
+- **Controllers** with route analysis (`@Controller`, `@Get`, `@Post`, etc.)
+- **Services** with dependency injection mapping (`@Injectable`)
+- **Modules** with import/export relationships (`@Module`)
+- **Guards, Pipes, Interceptors** as middleware chains
+- **DTOs** with validation decorators (`@IsString`, `@IsEmail`, etc.)
+- **Entities** with TypeORM relationship mapping
 
-#### Relationship Types
-- **Module System**: `MODULE_IMPORTS`, `MODULE_PROVIDES`, `MODULE_EXPORTS`
-- **Dependency Injection**: `INJECTS`, `PROVIDED_BY`
-- **HTTP API**: `EXPOSES`, `ACCEPTS`, `RESPONDS_WITH`
-- **Security**: `GUARDED_BY`, `TRANSFORMED_BY`, `INTERCEPTED_BY`
+**NestJS-Specific Relationships:**
+- `INJECTS` - Dependency injection
+- `EXPOSES` - Controller exposes HTTP endpoint
+- `MODULE_IMPORTS`, `MODULE_PROVIDES`, `MODULE_EXPORTS` - Module system
+- `GUARDED_BY`, `TRANSFORMED_BY`, `INTERCEPTED_BY` - Middleware
 
-### Example Graph Structure
+### Custom Framework Schemas
 
-```
-┌─────────────────┐    EXPOSES     ┌──────────────────┐
-│   UserController│──────────────→│  POST /users     │
-│   @Controller   │                │  @Post()         │
-└─────────────────┘                └──────────────────┘
-         │                                   │
-      INJECTS                           ACCEPTS
-         ↓                                   ↓
-┌─────────────────┐                ┌──────────────────┐
-│   UserService   │                │   CreateUserDto  │
-│   @Injectable   │                │   @IsString()    │
-└─────────────────┘                └──────────────────┘
-         │
-      MANAGES
-         ↓
-┌─────────────────┐
-│   User Entity   │
-│   @Entity()     │
-└─────────────────┘
-```
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OPENAI_API_KEY` | OpenAI API key for embeddings and LLM | Required |
-| `OPENAI_ASSISTANT_ID` | Reuse existing OpenAI assistant | Optional |
-| `NEO4J_URI` | Neo4j database URI | `bolt://localhost:7687` |
-| `NEO4J_USER` | Neo4j username | `neo4j` |
-| `NEO4J_PASSWORD` | Neo4j password | `PASSWORD` |
-| `NEO4J_QUERY_TIMEOUT_MS` | Neo4j query timeout | `30000` (30s) |
-| `NEO4J_CONNECTION_TIMEOUT_MS` | Neo4j connection timeout | `10000` (10s) |
-| `OPENAI_EMBEDDING_TIMEOUT_MS` | Embedding API timeout | `60000` (60s) |
-| `OPENAI_ASSISTANT_TIMEOUT_MS` | Assistant API timeout | `120000` (120s) |
-
-### Parse Options
-
-Customize parsing behavior:
+The parser is **config-driven**. Define your own framework patterns:
 
 ```typescript
-const parseOptions = {
-  includePatterns: ['**/*.ts', '**/*.tsx'],
-  excludePatterns: [
-    'node_modules/',
-    'dist/',
-    'coverage/',
-    '.d.ts',
-    '.spec.ts',
-    '.test.ts'
+// Example: Custom React schema
+const REACT_SCHEMA = {
+  name: 'react',
+  decoratorPatterns: [
+    { pattern: /^use[A-Z]/, semanticType: 'ReactHook' },
+    { pattern: /^with[A-Z]/, semanticType: 'HOC' },
+  ],
+  nodeTypes: [
+    { coreType: 'FunctionDeclaration', condition: (node) => node.name?.endsWith('Provider'), semanticType: 'ContextProvider' },
   ],
-  maxFiles: 1000,
-  frameworkSchemas: [NESTJS_FRAMEWORK_SCHEMA]
+  relationships: [
+    { type: 'PROVIDES_CONTEXT', from: 'ContextProvider', to: 'ReactHook' },
+  ]
 };
 ```
 
-## Limitations
-
-### Current Limitations
-
-1. **Language Support**: Currently supports TypeScript/NestJS only
-2. **Framework Support**: Primary focus on NestJS patterns (React, Angular, Vue planned)
-3. **File Size**: Large files (>10MB) may cause parsing performance issues
-4. **Memory Usage**: Mitigated by streaming import for large projects
-5. **Vector Search**: Requires OpenAI API for semantic search functionality
-6. **Response Size**: Large graph traversals can exceed token limits (25,000 tokens max)
-7. **Neo4j Memory**: Database memory limits can cause query failures on large graphs
+The dual-schema system means every node has:
+- `coreType`: AST-level (ClassDeclaration, FunctionDeclaration)
+- `semanticType`: Framework meaning (NestController, ReactHook)
 
-### Performance Considerations
+This enables queries like "find all hooks that use context" while maintaining AST precision for refactoring.
 
-- **Large Projects**: Use `async: true` for projects with >1000 files
-- **Streaming**: Auto-enabled for >100 files to prevent memory issues
-- **Graph Traversal**: Deep traversals (>5 levels) may be slow for highly connected graphs
-- **Embedding Generation**: Initial parsing with embeddings can take several minutes for large codebases
-- **Neo4j Memory**: Recommend at least 4GB RAM allocation for Neo4j with large graphs
-- **Worker Timeout**: Async parsing has 30-minute timeout for safety
-
-### Known Issues
-
-1. **Complex Type Inference**: Advanced TypeScript type gymnastics may not be fully captured
-2. **Dynamic Imports**: Runtime module loading not tracked in static analysis
-3. **Decorator Arguments**: Complex decorator argument patterns may not be fully parsed
+---
 
 ## Troubleshooting
 
-### Common Issues
+### MCP Server Not Connecting
 
-#### Neo4j Connection Failed
 ```bash
-# Check if Neo4j is running
-docker ps | grep neo4j
+# Check the server is registered
+claude mcp list
 
-# Check Neo4j logs
-docker logs codebase-neo4j
+# Verify Neo4j is running
+docker ps | grep neo4j
 
-# Verify APOC plugin
-curl -u neo4j:PASSWORD http://localhost:7474/db/neo4j/tx/commit \
-  -H "Content-Type: application/json" \
-  -d '{"statements":[{"statement":"CALL apoc.help(\"apoc\") YIELD name RETURN count(name) as count"}]}'
+# Test manually
+code-graph-context status
 ```
 
-#### Neo4j Memory Issues
-If you encounter errors like "allocation of an extra X MiB would use more than the limit":
+### Missing OPENAI_API_KEY
+
+Symptoms: "Failed to generate embedding" errors
 
+Fix: Ensure the key is in your config file:
 ```bash
-# Increase Neo4j memory limits in docker-compose.yml
-NEO4J_server_memory_heap_max__size=8G
-NEO4J_server_memory_pagecache_size=4G
-NEO4J_dbms_memory_transaction_total_max=8G
+# Check current config
+cat ~/.claude.json | grep -A5 "code-graph-context"
 
-# Restart Neo4j
-docker-compose restart neo4j
+# Re-add with key
+claude mcp remove code-graph-context
+claude mcp add --scope user code-graph-context \
+  -e OPENAI_API_KEY=sk-your-key-here \
+  -- code-graph-context
 ```
 
-#### Token Limit Exceeded
-If responses exceed token limits:
+### Neo4j Memory Issues
 
-```typescript
-// Reduce depth or use structure-only view
-traverse_from_node({ nodeId: "...", maxDepth: 2, includeCode: false })
-
-// Use pagination with skip
-traverse_from_node({ nodeId: "...", maxDepth: 2, skip: 0 })
-traverse_from_node({ nodeId: "...", maxDepth: 2, skip: 20 })
-```
+For large codebases, increase memory limits:
 
-#### OpenAI API Issues
 ```bash
-# Test API key
-curl https://api.openai.com/v1/models \
-  -H "Authorization: Bearer $OPENAI_API_KEY"
-
-# Check embedding model availability
-curl https://api.openai.com/v1/models/text-embedding-3-large \
-  -H "Authorization: Bearer $OPENAI_API_KEY"
+# Stop and recreate with more memory
+code-graph-context stop
+code-graph-context init --memory 4G
 ```
 
-#### Parsing Failures
-```bash
-# Check TypeScript configuration
-npx tsc --noEmit --project /path/to/tsconfig.json
-
-# Verify file permissions
-ls -la /path/to/project
+### Parsing Timeouts
 
-# Check memory usage during parsing
-node --max-old-space-size=8192 dist/mcp/mcp.server.js
+Use async mode for large projects:
+```typescript
+parse_typescript_project({
+  projectPath: "/path/to/project",
+  tsconfigPath: "/path/to/project/tsconfig.json",
+  async: true  // Returns immediately, poll with check_parse_status
+})
 ```
 
-### Debug Mode
+---
 
-Enable detailed logging:
+## CLI Commands
 
 ```bash
-export DEBUG=mcp:*
-export NODE_ENV=development
+code-graph-context init [options]   # Set up Neo4j container
+code-graph-context status           # Check Docker/Neo4j status
+code-graph-context stop             # Stop Neo4j container
 ```
 
-## Contributing
+**Init options:**
+- `-p, --port <port>` - Bolt port (default: 7687)
+- `--http-port <port>` - Browser port (default: 7474)
+- `--password <password>` - Neo4j password (default: PASSWORD)
+- `-m, --memory <size>` - Heap memory (default: 2G)
+- `-f, --force` - Recreate container
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Commit your changes: `git commit -m 'Add amazing feature'`
-4. Push to the branch: `git push origin feature/amazing-feature`
-5. Open a Pull Request
+---
 
-### Development Setup
+## Contributing
 
 ```bash
-# Install dependencies
+git clone https://github.com/drewdrewH/code-graph-context.git
+cd code-graph-context
 npm install
+npm run build
+npm run dev  # Watch mode
+```
 
-# Run in development mode
-npm run dev
-
-# Run tests
-npm test
-
-# Lint code
-npm run lint
+Conventional Commits: `feat|fix|docs|refactor(scope): description`
 
-# Format code
-npm run format
-```
+---
 
 ## License
 
-This project is proprietary software. All rights reserved - see the [LICENSE](LICENSE) file for details.
-
-## Acknowledgments
+MIT - see [LICENSE](LICENSE)
 
-- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
-- [Neo4j](https://neo4j.com/) for graph database technology
-- [ts-morph](https://ts-morph.com/) for TypeScript AST manipulation
-- [OpenAI](https://openai.com/) for embeddings and natural language processing
-- [NestJS](https://nestjs.com/) for the framework patterns and conventions
+---
 
-## Support
+## Documentation
 
-- Create an [Issue](https://github.com/drewdrewH/code-graph-context/issues) for bug reports or feature requests
-- Join the [MCP Discord](https://discord.gg/mcp) for community support
-- Check the [MCP Documentation](https://modelcontextprotocol.io/docs) for MCP-specific questions
+- [Graph + LLM Inference Research](docs/GRAPH_LLM_INFERENCE_RESEARCH.md) - Research on GNN embeddings, Graph Neural Prompting, and inference integration
 
 ---
+
+## Links
+
+- [Issues](https://github.com/drewdrewH/code-graph-context/issues)
+- [MCP Documentation](https://modelcontextprotocol.io/docs)
+- [Neo4j](https://neo4j.com/)