agentic-flow 1.1.10 → 1.1.12

package/README.md

@@ -1,476 +1,250 @@
 # 🤖 Agentic Flow
 
-**Production-Ready AI Agent Orchestration with Multi-Model Router, OpenRouter Integration & Free Local Inference**
-
-Agentic Flow works with any agent or command built or used in Claude Code. It automatically runs through the Claude Agent SDK, forming swarms of intelligent, cost and performance-optimized agents that decide how to execute each task. Built for business, government, and commercial use where cost, traceability, and reliability matter.
-
-Agentic Flow runs Claude Code agents at near zero cost without rewriting a thing. It routes every task to the cheapest lane that still meets the bar. Local ONNX when privacy or price wins. OpenRouter for breadth. Gemini for speed. Anthropic when quality matters most. One agent. Any model. Lowest viable cost.
-
-The system takes the Claude SDK's logic and merges it with Claude Flow memory to give every agent a durable brain. Each run logs inputs, outputs, and route decisions with artifacts, manifests, and checksums for proof and reproducibility. It self-optimizes in real time, balancing price, latency, and accuracy through a simple policy file.
-
-Strict mode keeps sensitive data offline. Economy mode prefers ONNX or OpenRouter. Premium mode goes Anthropic first. The policy defines the rules, and the swarm enforces them automatically.
-
-It runs anywhere: local for dev, Docker for CI, or Flow Nexus for scale. With project-scoped settings, explicit tool allowlists, and an offline privacy lane, it stays secure by default.
-
-**Agentic Flow is the framework for autonomous efficiency—one unified runner for every Claude Code agent, self-tuning, self-routing, and built for real-world deployment.**
-
-Built on **[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk)** by Anthropic, powered by **[Claude Flow](https://github.com/ruvnet/claude-flow)** (101 MCP tools), **[Flow Nexus](https://github.com/ruvnet/flow-nexus)** (96 cloud tools), **[OpenRouter](https://openrouter.ai)** (100+ LLM models), **Google Gemini** (fast, cost-effective inference), **[Agentic Payments](https://www.npmjs.com/package/agentic-payments)** (payment authorization), and **ONNX Runtime** (free local CPU or GPU inference).
-
 [![npm version](https://img.shields.io/npm/v/agentic-flow.svg)](https://www.npmjs.com/package/agentic-flow)
 [![npm downloads](https://img.shields.io/npm/dm/agentic-flow.svg)](https://www.npmjs.com/package/agentic-flow)
-[![npm total downloads](https://img.shields.io/npm/dt/agentic-flow.svg)](https://www.npmjs.com/package/agentic-flow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
 [![rUv](https://img.shields.io/badge/by-rUv-purple.svg)](https://github.com/ruvnet/)
-[![Agentic Engineering](https://img.shields.io/badge/Agentic-Engineering-orange.svg)](https://github.com/ruvnet/agentic-flow#-agent-types)
-
----
-
-## Why Agentic Flow?
-
-**The Problem:** You need agents that actually complete tasks, not chatbots that need constant supervision. Long-running workflows - migrating codebases, generating documentation, analyzing datasets - shouldn't require you to sit there clicking "continue."
 
-**What True Agentic Systems Need:**
-- **Autonomy** - Agents that plan, execute, and recover from errors without hand-holding
-- **Persistence** - Tasks that run for hours, even when you're offline
-- **Collaboration** - Multiple agents coordinating on complex work
-- **Tool Access** - Real capabilities: file systems, APIs, databases, not just text generation
-- **Cost Control** - Run cheap models for grunt work, expensive ones only when needed
+**Production-ready AI agent orchestration with 66+ specialized agents, 213 MCP tools, and multi-model routing (Anthropic, OpenRouter, Gemini, ONNX).**
 
-**What You Get:**
-
-- **150+ Specialized Agents** - Researcher, coder, reviewer, tester, architect - each with domain expertise and tool access
-- **Multi-Agent Swarms** - Deploy 3, 10, or 100 agents that collaborate via shared memory to complete complex projects
-- **Long-Running Tasks** - Agents persist through hours-long operations: full codebase refactors, comprehensive audits, dataset processing
-- **213 MCP Tools** - Agents have real capabilities: GitHub operations, neural network training, workflow automation, memory persistence
-- **Auto Model Optimization** - `--optimize` flag intelligently selects best model for each task. DeepSeek R1 costs 85% less than Claude with similar quality. Save $2,400/month on 100 daily reviews.
-- **Deploy Anywhere** - Same agentic capabilities locally, in Docker/Kubernetes, or cloud sandboxes
+---
 
-**Real Agentic Use Cases:**
-- **Overnight Code Migration** - Deploy a swarm to migrate a 50K line codebase from JavaScript to TypeScript while you sleep
-- **Continuous Security Audits** - Agents monitor repos, analyze PRs, and flag vulnerabilities 24/7
-- **Automated API Development** - One agent designs schema, another implements endpoints, a third writes tests - all coordinated
-- **Data Pipeline Processing** - Agents process TBs of data across distributed sandboxes, checkpoint progress, and recover from failures
+## 📖 Introduction
 
-> **True autonomy at commodity prices.** Your agents work independently on long-running tasks, coordinate when needed, and cost pennies per hour instead of dollars.
+Agentic Flow is a framework for running AI agents at scale with intelligent cost optimization. It runs any Claude Code agent through the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk), automatically routing tasks to the cheapest model that meets quality requirements.
 
-### Built on Industry Standards
+**Key Capabilities:**
+- ✅ **66 Specialized Agents** - Pre-built experts for coding, research, review, testing, DevOps
+- ✅ **213 MCP Tools** - Memory, GitHub, neural networks, sandboxes, workflows, payments
+- ✅ **Multi-Model Router** - Anthropic, OpenRouter (100+ models), Gemini, ONNX (free local)
+- ✅ **Cost Optimization** - 85-99% savings with DeepSeek, Llama, Gemini vs Claude
+- ✅ **Standalone Proxy** - Use Gemini/OpenRouter with Claude Code at 85% cost savings
 
-- **[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk)** - Anthropic's official SDK for building AI agents
-- **[Claude Flow](https://github.com/ruvnet/claude-flow)** - 101 MCP tools for orchestration, memory, GitHub, neural networks
-- **[Flow Nexus](https://github.com/ruvnet/flow-nexus)** - 96 cloud tools for sandboxes, distributed swarms, workflows
-- **[OpenRouter](https://openrouter.ai)** - Access to 100+ LLM models at 99% cost savings (Llama, DeepSeek, Gemini, etc.)
-- **[Agentic Payments](https://www.npmjs.com/package/agentic-payments)** - Multi-agent payment authorization with Ed25519 cryptography
-- **[ONNX Runtime](https://onnxruntime.ai)** - Free local CPU/GPU inference with Microsoft Phi-4
+**Built On:**
+- [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk) by Anthropic
+- [Claude Flow](https://github.com/ruvnet/claude-flow) - 101 MCP tools
+- [Flow Nexus](https://github.com/ruvnet/flow-nexus) - 96 cloud tools
+- [OpenRouter](https://openrouter.ai) - 100+ LLM models
+- [Agentic Payments](https://www.npmjs.com/package/agentic-payments) - Multi-agent payments
 
 ---
 
 ## 🚀 Quick Start
 
-### Local Installation (Recommended for Development)
+### Option 1: CLI Agent Execution (Fastest)
+
+Run specialized agents for coding, research, testing, and more:
 
 ```bash
-# Global installation
+# Install globally
 npm install -g agentic-flow
 
-# Or use directly with npx (no installation)
-npx agentic-flow --help
-
-# Set your API key
+# Run with Claude (Anthropic)
 export ANTHROPIC_API_KEY=sk-ant-...
-```
+npx agentic-flow --agent coder --task "Build a REST API with authentication"
 
-### Your First Agent (Local Execution)
-
-```bash
-# Run locally with full 203 MCP tool access (Claude)
-npx agentic-flow \
-  --agent researcher \
-  --task "Analyze microservices architecture trends in 2025"
-
-# Run with OpenRouter for 99% cost savings
+# Run with OpenRouter (99% cost savings)
 export OPENROUTER_API_KEY=sk-or-v1-...
-npx agentic-flow \
-  --agent coder \
-  --task "Build a REST API with authentication" \
-  --model "meta-llama/llama-3.1-8b-instruct"
+npx agentic-flow --agent coder --task "Build REST API" --model "meta-llama/llama-3.1-8b-instruct"
 
-# The agent executes on your machine, uses all MCP tools, and terminates
-```
+# Run with Gemini (free tier)
+export GOOGLE_GEMINI_API_KEY=AIza...
+npx agentic-flow --agent coder --task "Build REST API" --provider gemini
 
-### Multi-Agent Swarm (Local)
+# List all 66 available agents
+npx agentic-flow --list
+```
 
-```bash
-# 3 agents work in parallel on your machine
-export TOPIC="API security best practices"
-export DIFF="feat: add OAuth2 authentication"
-export DATASET="API response times last 30 days"
+**Available Agents:**
+- `coder`, `reviewer`, `tester`, `planner`, `researcher`
+- `backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`
+- `pr-manager`, `code-review-swarm`, `release-manager`
+- `perf-analyzer`, `production-validator`, `system-architect`
+- And 50+ more...
 
-npx agentic-flow  # Spawns: researcher + code-reviewer + data-analyst
-```
+---
 
-**Local Benefits:**
-- ✅ All 203 MCP tools work (full subprocess support)
-- ✅ Fast iteration and debugging
-- ✅ No cloud costs during development
-- ✅ Full access to local filesystem and resources
+### Option 2: MCP Tools (Direct Access)
 
-### Docker Deployment (Production)
+Access 213 MCP tools for memory, swarms, GitHub, neural networks, and cloud sandboxes:
 
 ```bash
-# Build container
-docker build -f deployment/Dockerfile -t agentic-flow .
-
-# Run agent with Claude (Anthropic)
-docker run --rm \
-  -e ANTHROPIC_API_KEY=sk-ant-... \
-  agentic-flow \
-  --agent researcher \
-  --task "Analyze cloud patterns"
+# Start all MCP servers (213 tools)
+npx agentic-flow mcp start
 
-# Run agent with OpenRouter (99% cost savings)
-docker run --rm \
-  -e OPENROUTER_API_KEY=sk-or-v1-... \
-  agentic-flow \
-  --agent coder \
-  --task "Build REST API" \
-  --model "meta-llama/llama-3.1-8b-instruct"
-```
+# List all available tools
+npx agentic-flow mcp list
 
-**Container Benefits:**
-- ✅ All 203 MCP tools work (full subprocess support)
-- ✅ OpenRouter proxy auto-starts in container
-- ✅ Reproducible builds and deployments
-- ✅ Works on Kubernetes, ECS, Cloud Run, Fargate
-- ✅ Isolated execution environment
+# Check server status
+npx agentic-flow mcp status
 
----
+# Use tools in any agent automatically
+export ENABLE_CLAUDE_FLOW_SDK=true
+npx agentic-flow --agent coder --task "Store config in memory using memory_store"
+```
 
-## ✨ Key Features
-
-### 🔄 Ephemeral Architecture
-- **On-Demand Spawning** - Agents created only when needed
-- **Automatic Cleanup** - Terminate after task completion
-- **Stateless Execution** - No persistent state between runs
-- **Cost-Optimized** - Pay only for actual compute time
-
-### 🤖 Multi-Model Router with ONNX Local Inference
-- **Intelligent Provider Routing** - Automatic selection between Anthropic, OpenRouter, and ONNX based on task requirements
-- **100% Free Local Inference** - ONNX Runtime CPU/GPU execution with Microsoft Phi-4 (zero API costs)
-- **Privacy-First Processing** - GDPR/HIPAA-compliant local processing for sensitive workloads
-- **Cost Optimization** - Route privacy tasks to free ONNX, complex reasoning to cloud APIs
-- **Rule-Based Routing** - Automatic provider selection based on privacy, cost, and performance
-- **GPU Acceleration Ready** - CPU inference at 6 tokens/sec, GPU capable of 60-300 tokens/sec
-- **Zero-Cost Agents** - Run agents entirely offline with local ONNX models
-
-### 💻 Local Development (Full Features)
-- **Native Execution** - Run directly on macOS, Linux, Windows
-- **All 203 MCP Tools** - Full subprocess support, no restrictions
-- **Fast Iteration** - Instant feedback, no cold starts
-- **Persistent Memory** - Claude Flow memory persists across runs
-- **File System Access** - Full access to local files and directories
-- **Git Integration** - Direct GitHub operations and repository management
-- **Zero Cloud Costs** - Free during development
-
-### 🐳 Container Deployment (Production Ready)
-- **Docker Support** - Complete feature set for ECS, Cloud Run, Kubernetes
-- **All 203 MCP Tools** - Full subprocess support in containers
-- **Reproducible Builds** - Same environment across dev/staging/prod
-- **Orchestration Ready** - Works with Kubernetes Jobs, ECS Tasks, Cloud Run
-- **Health Checks Built-in** - `/health` endpoint for load balancers
-- **Resource Controls** - CPU/memory limits via container configs
-
-### ☁️ Cloud Sandboxes (Scalable Execution)
-- **Flow Nexus E2B Sandboxes** - Fully isolated execution environments
-- **All 203 MCP Tools** - Complete tool access in cloud sandboxes
-- **Multi-Language Templates** - Node.js, Python, React, Next.js
-- **Real-Time Streaming** - Live output and monitoring
-- **Auto-Scaling** - Spin up 1 to 100+ sandboxes on demand
-- **Pay-Per-Use** - Only pay for actual sandbox runtime (≈$1/hour)
-
-### 🤖 Intelligent Agents
-- **150+ Pre-Built Specialists** - Researchers, coders, testers, reviewers, architects
-- **Swarm Coordination** - Agents collaborate via shared memory
-- **Tool Access** - 200+ MCP tools for GitHub, neural networks, workflows
-- **Custom Agents** - Define your own in YAML with system prompts
-
-### 📊 Observability
-- **Real-Time Streaming** - See agent output as it happens
-- **Structured Logging** - JSON logs for aggregation and analysis
-- **Performance Metrics** - Track agent duration, tool usage, token consumption
-- **Health Checks** - Built-in healthcheck endpoint for orchestrators
+**MCP Tool Categories:**
+- **Claude Flow SDK** (6 tools): In-process memory and swarm coordination
+- **Claude Flow** (101 tools): Neural networks, GitHub, workflows, performance, DAA
+- **Flow Nexus** (96 tools): E2B sandboxes, distributed swarms, templates, storage
+- **Agentic Payments** (10 tools): Payment authorization, Ed25519 signatures, consensus
 
 ---
 
-## 🚀 Deployment Options
+### Option 3: Standalone Proxy (NEW in v1.1.11)
 
-### 💻 Local Execution (Best for Development)
-
-**Full-featured, all 203 MCP tools work:**
+Use Gemini or OpenRouter with Claude Code at 85-90% cost savings:
 
 ```bash
-# Install globally
-npm install -g agentic-flow
+# Terminal 1: Start proxy server
+export GOOGLE_GEMINI_API_KEY=your-key-here
+npx agentic-flow proxy
 
-# Set API key
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Run any agent locally
-npx agentic-flow --agent coder --task "Build REST API"
+# Terminal 2: Use Claude Code with proxy
+export ANTHROPIC_BASE_URL=http://localhost:3000
+export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
+claude  # Now uses Gemini instead of Anthropic!
 
-# Multi-agent swarm (3 agents in parallel)
-npx agentic-flow  # Uses TOPIC, DIFF, DATASET env vars
+# Or use OpenRouter (90% savings)
+npx agentic-flow proxy --provider openrouter --model "openai/gpt-4o-mini"
 ```
 
-**Why Local Development?**
-- ✅ **All 203 MCP Tools**: Full subprocess support (claude-flow, flow-nexus, agentic-payments)
-- ✅ **Fast Iteration**: No cold starts, instant feedback
-- ✅ **Free**: No cloud costs during development
-- ✅ **File Access**: Direct access to local filesystem
-- ✅ **Git Integration**: Full GitHub operations
-- ✅ **Memory Persistence**: Claude Flow memory persists across runs
-- ✅ **Easy Debugging**: Standard Node.js debugging tools work
+**Features:**
+- ✅ MCP tools work through proxy (all 213 tools)
+- ✅ Compatible with Claude Code official CLI
+- ✅ Future Cursor IDE support (waiting for ANTHROPIC_BASE_URL)
+- ✅ 85-90% cost savings vs direct Anthropic API
 
-**System Requirements:**
-- Node.js ≥18.0.0
-- npm or pnpm
-- 2GB RAM minimum (4GB recommended for swarms)
-- macOS, Linux, or Windows
+**Cost Savings:**
+| Provider | Model | Cost per 1M tokens | Savings |
+|----------|-------|-------------------|---------|
+| Anthropic | Claude Sonnet 4.5 | $3.00 | Baseline |
+| Gemini (proxy) | gemini-2.0-flash | $0.00 (free tier) | **100%** |
+| OpenRouter (proxy) | gpt-4o-mini | $0.15 | **95%** |
+| OpenRouter (proxy) | deepseek-v3 | $0.014 | **99.5%** |
+
+📚 **See [Standalone Proxy Guide](docs/STANDALONE_PROXY_GUIDE.md) for details**
 
 ---
 
-### 🎯 Flow Nexus Cloud Sandboxes (Best for Production Scale)
-```javascript
-// Create isolated sandbox and execute agent with full MCP tool access
-const { query } = require('@anthropic-ai/claude-agent-sdk');
+## 📚 Tutorial: Agent Execution
 
-// 1. Login to Flow Nexus
-await flowNexus.login({ email: 'user@example.com', password: 'secure' });
+### 1. Basic Agent Usage
 
-// 2. Create E2B sandbox with Node.js template
-const sandbox = await flowNexus.sandboxCreate({
-  template: 'node',
-  name: 'agent-execution',
-  env_vars: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }
-});
+**What it does:** Runs a specialized agent with Claude SDK and all 213 MCP tools.
 
-// 3. Execute agent in sandbox with all 203 MCP tools
-const result = await flowNexus.sandboxExecute({
-  sandbox_id: sandbox.id,
-  code: `
-    const { query } = require('@anthropic-ai/claude-agent-sdk');
-    const result = await query({
-      prompt: "Analyze API security patterns",
-      options: {
-        mcpServers: { /* all 3 MCP servers available */ }
-      }
-    });
-    console.log(result);
-  `
-});
+**When to use:** Quick tasks that need one expert (code review, API generation, testing).
 
-// 4. Automatic cleanup
-await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });
+```bash
+# Code generation
+npx agentic-flow --agent coder --task "Create a REST API with OAuth2 authentication"
+
+# Security review
+npx agentic-flow --agent reviewer --task "Review this code for security vulnerabilities"
+
+# Test generation
+npx agentic-flow --agent tester --task "Write comprehensive tests for this API"
 ```
 
-**Why Flow Nexus?**
-- ✅ Full 203 MCP tool support (all subprocess servers work)
-- ✅ Persistent memory across sandbox instances
-- ✅ Multi-language templates (Node.js, Python, React, Next.js)
-- ✅ Real-time output streaming
-- ✅ Secure process isolation
-- ✅ Pay-per-use pricing (10 credits/hour)
+**Technical Details:**
+- Uses Claude Agent SDK's `query()` function
+- Automatically loads agent's system prompt from `.claude/agents/`
+- All 213 MCP tools available via `mcpServers` configuration
+- Streams output in real-time with `--stream` flag
 
 ---
 
-### 🐳 Docker Containers (Best for Production Deployments)
+### 2. Multi-Agent Swarms
 
-**Full 203 MCP tool support in containers:**
+**What it does:** Runs 3 agents in parallel for complex workflows.
 
-```bash
-# Build image
-docker build -t agentic-flow .
+**When to use:** Multi-faceted tasks requiring research + coding + analysis.
 
-# Run single agent
-docker run --rm \
-  -e ANTHROPIC_API_KEY=sk-ant-... \
-  agentic-flow \
-  --agent researcher \
-  --task "Analyze microservices patterns"
+```bash
+# Set environment variables
+export TOPIC="API security best practices"
+export DIFF="feat: add OAuth2 authentication"
+export DATASET="API response times last 30 days"
 
-# Multi-agent swarm in container
-docker run --rm \
-  -e ANTHROPIC_API_KEY=sk-ant-... \
-  -e TOPIC="API security" \
-  -e DIFF="feat: auth" \
-  -e DATASET="logs.json" \
-  agentic-flow
+# Run parallel swarm (researcher + code-reviewer + data-analyst)
+npx agentic-flow
 ```
 
-**Why Docker?**
-- ✅ **All 203 MCP Tools**: Full subprocess support
-- ✅ **Production Ready**: Works on Kubernetes, ECS, Cloud Run, Fargate
-- ✅ **Reproducible**: Same environment everywhere
-- ✅ **Isolated**: Process isolation and security
-- ✅ **Orchestration**: Integrates with container orchestrators
-- ✅ **CI/CD**: Perfect for automated workflows
+**Technical Details:**
+- Spawns 3 agents concurrently: `researcher`, `code-review`, `data-analyst`
+- Agents coordinate via Claude Flow memory tools
+- Each agent has access to all 213 MCP tools
+- Results aggregated and returned together
 
-**Container Orchestration Examples:**
+---
 
-```yaml
-# Kubernetes Job
-apiVersion: batch/v1
-kind: Job
-metadata:
-  name: code-review
-spec:
-  template:
-    spec:
-      containers:
-      - name: agent
-        image: agentic-flow:latest
-        args: ["--agent", "code-review", "--task", "Review PR #123"]
-        env:
-        - name: ANTHROPIC_API_KEY
-          valueFrom:
-            secretKeyRef:
-              name: anthropic
-              key: api-key
-      restartPolicy: Never
+### 3. Cost Optimization with OpenRouter
 
-# GitHub Actions
-- name: AI Code Review
-  run: |
-    docker run -e ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }} \
-      agentic-flow:latest \
-      --agent code-review \
-      --task "${{ github.event.pull_request.diff }}"
+**What it does:** Uses OpenRouter models for 90-99% cost savings vs Claude.
 
-# AWS ECS Task Definition
-{
-  "family": "agentic-flow-task",
-  "containerDefinitions": [{
-    "name": "agent",
-    "image": "agentic-flow:latest",
-    "command": ["--agent", "researcher", "--task", "$(TASK)"],
-    "environment": [
-      {"name": "ANTHROPIC_API_KEY", "value": "from-secrets-manager"}
-    ]
-  }]
-}
-```
+**When to use:** Development, testing, or budget-conscious production workloads.
+
+```bash
+# Ultra-low cost with Llama 3.1 8B (99% savings)
+export OPENROUTER_API_KEY=sk-or-v1-...
+npx agentic-flow --agent coder --task "Build REST API" --model "meta-llama/llama-3.1-8b-instruct"
 
-### 🔓 ONNX Local Inference (Free Offline AI)
+# Balanced cost/quality with DeepSeek (97% savings)
+npx agentic-flow --agent coder --task "Production code" --model "deepseek/deepseek-chat-v3.1"
 
-**Run agents completely offline with zero API costs:**
+# Fast responses with Gemini (95% savings)
+npx agentic-flow --agent researcher --task "Analyze trends" --model "google/gemini-2.5-flash-preview"
+```
 
-```bash
-# Auto-downloads Phi-4 model (~4.9GB one-time download)
-npx agentic-flow \
-  --agent coder \
-  --task "Build a REST API" \
-  --provider onnx
+**Technical Details:**
+- Proxy auto-starts on port 3000 when OpenRouter model detected
+- Translates Anthropic Messages API ↔ OpenAI Chat Completions API
+- All 213 MCP tools work through proxy
+- No code changes needed - transparent to Claude SDK
 
-# Router auto-selects ONNX for privacy-sensitive tasks
-npx agentic-flow \
-  --agent researcher \
-  --task "Analyze confidential medical records" \
-  --privacy high \
-  --local-only
+**Cost Comparison:**
 ```
+Task: Generate 100K tokens (200 functions)
 
-**ONNX Capabilities:**
-- ✅ 100% free local inference (Microsoft Phi-4 model)
-- ✅ Privacy: All processing stays on your machine
-- ✅ Offline: No internet required after model download
-- ✅ Performance: ~6 tokens/sec CPU, 60-300 tokens/sec GPU
-- ✅ Auto-download: Model fetches automatically on first use
-- ✅ Quantized: INT4 optimization for efficiency (~4.9GB total)
-- ⚠️ Limited to 6 in-SDK tools (no subprocess MCP servers)
-- 📚 See [docs](docs/ONNX_INTEGRATION.md) for full capabilities
+Anthropic Claude Sonnet 4.5: $1.80
+DeepSeek V3 (OpenRouter):    $0.028  (98% savings)
+Llama 3.1 8B (OpenRouter):   $0.011  (99% savings)
+```
 
 ---
 
-## 🎯 Use Cases & Costs
+### 4. Free Local Inference with ONNX
 
-| Use Case | Agent Type | Execution Time | Local Cost | Docker Cost | Flow Nexus Cost |
-|----------|-----------|----------------|------------|-------------|-----------------|
-| **Code Review** | `code-review` | 15-45s | Free* | Self-hosted | 0.13-0.38 credits |
-| **API Testing** | `tester` | 10-30s | Free* | Self-hosted | 0.08-0.25 credits |
-| **Documentation** | `api-docs` | 20-60s | Free* | Self-hosted | 0.17-0.50 credits |
-| **Data Analysis** | `data-analyst` | 30-90s | Free* | Self-hosted | 0.25-0.75 credits |
-| **Security Audit** | `reviewer` | 45-120s | Free* | Self-hosted | 0.38-1.00 credits |
-| **Microservice Generation** | `backend-dev` | 60-180s | Free* | Self-hosted | 0.50-1.50 credits |
-| **Performance Analysis** | `perf-analyzer` | 20-60s | Free* | Self-hosted | 0.17-0.50 credits |
+**What it does:** Runs agents completely offline with zero API costs.
 
-*Local: Free infrastructure, Claude API costs only ($0.003-0.015 per input 1K tokens, $0.015-0.075 per output 1K tokens)
-Flow Nexus: 10 credits/hour sandbox (≈$1/hour) + Claude API costs. 1 credit ≈ $0.10.
-Docker: Infrastructure costs (AWS/GCP/Azure) + Claude API costs.*
+**When to use:** Privacy-sensitive data, air-gapped environments, development without API costs.
 
-**Recommendation by Scenario:**
-- **Development/Testing**: Use **Local** - free, fast, full tools
-- **CI/CD Pipelines**: Use **Docker** - reproducible, isolated
-- **Production Scale**: Use **Flow Nexus** - auto-scaling, cloud-native
+```bash
+# Auto-downloads Phi-4 model (~4.9GB one-time)
+npx agentic-flow --agent coder --task "Build REST API" --provider onnx
 
----
+# Privacy-first routing (auto-selects ONNX)
+npx agentic-flow --agent researcher --task "Analyze medical records" --privacy high --local-only
+```
 
-## 🤖 Agent Types
-
-### Core Development Agents
-- **`coder`** - Implementation specialist for writing clean, efficient code
-- **`reviewer`** - Code review and quality assurance
-- **`tester`** - Comprehensive testing with 90%+ coverage
-- **`planner`** - Strategic planning and task decomposition
-- **`researcher`** - Deep research and information gathering
-
-### Specialized Agents
-- **`backend-dev`** - REST/GraphQL API development
-- **`mobile-dev`** - React Native mobile apps
-- **`ml-developer`** - Machine learning model creation
-- **`system-architect`** - System design and architecture
-- **`cicd-engineer`** - CI/CD pipeline creation
-- **`api-docs`** - OpenAPI/Swagger documentation
-
-### Swarm Coordinators
-- **`hierarchical-coordinator`** - Tree-based leadership
-- **`mesh-coordinator`** - Peer-to-peer coordination
-- **`adaptive-coordinator`** - Dynamic topology switching
-- **`swarm-memory-manager`** - Cross-agent memory sync
-
-### GitHub Integration
-- **`pr-manager`** - Pull request lifecycle management
-- **`code-review-swarm`** - Multi-agent code review
-- **`issue-tracker`** - Intelligent issue management
-- **`release-manager`** - Automated release coordination
-- **`workflow-automation`** - GitHub Actions specialist
-
-### Performance & Analysis
-- **`perf-analyzer`** - Performance bottleneck detection
-- **`production-validator`** - Deployment readiness checks
-- **`tdd-london-swarm`** - Test-driven development
-
-*Use `npx agentic-flow --list` to see all 150+ agents*
+**Technical Details:**
+- Uses Microsoft Phi-4 (INT4 quantized) via ONNX Runtime
+- CPU: ~6 tokens/sec, GPU: 60-300 tokens/sec
+- 100% offline after model download
+- Limited to 6 in-SDK tools (no subprocess MCP servers)
+- Zero API costs forever
 
 ---
 
-## 🎯 Model Optimization (NEW!)
-
-**Automatically select the optimal model for any agent and task**, balancing quality, cost, and speed based on your priorities.
-
-### Why Model Optimization?
+### 5. Model Optimization (Auto-Select Best Model)
 
-Different tasks need different models:
-- **Production code** → Claude Sonnet 4.5 (highest quality)
-- **Code reviews** → DeepSeek R1 (85% cheaper, nearly same quality)
-- **Simple functions** → Llama 3.1 8B (99% cheaper)
-- **Privacy-critical** → ONNX Phi-4 (free, local, offline)
+**What it does:** Automatically picks optimal model based on task complexity and priorities.
 
-**The optimizer analyzes your agent type + task complexity and recommends the best model automatically.**
-
-### Quick Examples
+**When to use:** You want best quality/cost/speed balance without manual selection.
 
 ```bash
-# Let the optimizer choose (balanced quality vs cost)
+# Let optimizer choose (balanced quality vs cost)
 npx agentic-flow --agent coder --task "Build REST API" --optimize
 
 # Optimize for lowest cost
@@ -479,975 +253,526 @@ npx agentic-flow --agent coder --task "Simple function" --optimize --priority co
 # Optimize for highest quality
 npx agentic-flow --agent reviewer --task "Security audit" --optimize --priority quality
 
-# Optimize for speed
-npx agentic-flow --agent researcher --task "Quick analysis" --optimize --priority speed
-
-# Set maximum budget ($0.001 per task)
+# Set budget cap ($0.001 per task max)
 npx agentic-flow --agent coder --task "Code cleanup" --optimize --max-cost 0.001
 ```
 
-### Optimization Priorities
-
-- **`quality`** (70% quality, 20% speed, 10% cost) - Best results, production code
-- **`balanced`** (40% quality, 40% cost, 20% speed) - Default, good mix
-- **`cost`** (70% cost, 20% quality, 10% speed) - Cheapest, development/testing
-- **`speed`** (70% speed, 20% quality, 10% cost) - Fastest responses
-- **`privacy`** - Local-only models (ONNX), zero cloud API calls
-
-### Model Tier Examples
-
-The optimizer chooses from 10+ models across 5 tiers:
-
-**Tier 1: Flagship** (premium quality)
-- Claude Sonnet 4.5 - $3/$15 per 1M tokens
-- GPT-4o - $2.50/$10 per 1M tokens
-- Gemini 2.5 Pro - $0.00/$2.00 per 1M tokens
-
-**Tier 2: Cost-Effective** (2025 breakthrough models)
-- **DeepSeek R1** - $0.55/$2.19 per 1M tokens (85% cheaper, flagship quality)
-- **DeepSeek Chat V3** - $0.14/$0.28 per 1M tokens (98% cheaper)
-
-**Tier 3: Balanced**
-- Gemini 2.5 Flash - $0.07/$0.30 per 1M tokens (fastest)
-- Llama 3.3 70B - $0.30/$0.30 per 1M tokens (open-source)
-
-**Tier 4: Budget**
-- Llama 3.1 8B - $0.055/$0.055 per 1M tokens (ultra-low cost)
-
-**Tier 5: Local/Privacy**
-- **ONNX Phi-4** - FREE (offline, private, no API)
-
-### Agent-Specific Recommendations
-
-The optimizer knows what each agent needs:
-
-```bash
-# Coder agent → prefers high quality (min 85/100)
-npx agentic-flow --agent coder --task "Production API" --optimize
-# → Selects: DeepSeek R1 (quality 90, cost 85)
-
-# Researcher agent → flexible, can use cheaper models
-npx agentic-flow --agent researcher --task "Trend analysis" --optimize --priority cost
-# → Selects: Gemini 2.5 Flash (quality 78, cost 98)
-
-# Reviewer agent → needs reasoning (min 85/100)
-npx agentic-flow --agent reviewer --task "Security review" --optimize
-# → Selects: DeepSeek R1 (quality 90, reasoning-optimized)
-
-# Tester agent → simple tasks, use budget models
-npx agentic-flow --agent tester --task "Unit tests" --optimize --priority cost
-# → Selects: Llama 3.1 8B (cost 95)
-```
-
-### Cost Savings Examples
-
-**Without Optimization** (always using Claude Sonnet 4.5):
-- 100 code reviews/day × $0.08 each = **$8/day = $240/month**
-
-**With Optimization** (DeepSeek R1 for reviews):
-- 100 code reviews/day × $0.012 each = **$1.20/day = $36/month**
-- **Savings: $204/month (85% reduction)**
-
-### Comprehensive Model Guide
-
-For detailed analysis of all 10 models, see:
-📖 **[Model Capabilities Guide](docs/agentic-flow/benchmarks/MODEL_CAPABILITIES.md)**
+**Technical Details:**
+- Analyzes agent requirements (coder needs 85+ quality score)
+- Evaluates task complexity via keyword analysis
+- Scores 10+ models across quality, cost, speed, privacy
+- Returns recommendation with reasoning
 
-Includes:
-- Full benchmark results across 6 task types
-- Cost comparison tables
-- Use case decision matrices
-- Performance characteristics
-- Best practices by model
+**Optimization Priorities:**
+- `quality` - Best results (70% quality, 20% speed, 10% cost)
+- `balanced` - Default mix (40% quality, 40% cost, 20% speed)
+- `cost` - Cheapest (70% cost, 20% quality, 10% speed)
+- `speed` - Fastest (70% speed, 20% quality, 10% cost)
+- `privacy` - Local-only (ONNX models, zero cloud API calls)
 
-### MCP Tool for Optimization
-
-```javascript
-// Get model recommendation via MCP tool
-await query({
-  mcp: {
-    server: 'agentic-flow',
-    tool: 'agentic_flow_optimize_model',
-    params: {
-      agent: 'coder',
-      task: 'Build REST API with auth',
-      priority: 'balanced',  // quality | balanced | cost | speed | privacy
-      max_cost: 0.01         // optional budget cap in dollars
-    }
-  }
-});
-```
+---
 
-**Learn More:**
-- See [benchmarks/README.md](docs/agentic-flow/benchmarks/README.md) for quick results
-- Run your own tests: `cd docs/agentic-flow/benchmarks && ./quick-benchmark.sh`
+## 📚 Tutorial: MCP Tools
 
----
+### What are MCP Tools?
 
-## 📋 Commands
+MCP (Model Context Protocol) tools extend agent capabilities beyond text generation. They provide:
+- **Memory** - Persistent storage across sessions
+- **GitHub** - Repository operations, PR management, code review
+- **Sandboxes** - Isolated execution environments in the cloud
+- **Neural Networks** - Training, inference, model management
+- **Workflows** - Event-driven automation with message queues
+- **Payments** - Multi-agent payment authorization
 
-### MCP Server Management (Direct Tool Access)
+### Starting MCP Servers
 
 ```bash
-# Start all MCP servers (213 tools)
+# Start all 213 tools (4 servers)
 npx agentic-flow mcp start
 
-# Start specific MCP server
+# Start specific server
 npx agentic-flow mcp start claude-flow      # 101 tools
-npx agentic-flow mcp start flow-nexus       # 96 cloud tools
-npx agentic-flow mcp start agentic-payments # Payment tools
+npx agentic-flow mcp start flow-nexus       # 96 tools (requires registration)
+npx agentic-flow mcp start agentic-payments # 10 tools
 
-# List all available MCP tools (213 total)
+# List all tools
 npx agentic-flow mcp list
 
-# Check MCP server status
+# Check status
 npx agentic-flow mcp status
 
-# Stop MCP servers
-npx agentic-flow mcp stop [server]
+# Stop servers
+npx agentic-flow mcp stop
 ```
 
-**MCP Servers Available:**
-- **claude-flow** (101 tools): Neural networks, GitHub integration, workflows, DAA, performance
-- **flow-nexus** (96 tools): E2B sandboxes, distributed swarms, templates, cloud storage
-- **agentic-payments** (10 tools): Payment authorization, Ed25519 signatures, consensus
-- **claude-flow-sdk** (6 tools): In-process memory and swarm coordination
-
-### Basic Operations (Works Locally, Docker, Cloud)
+### Using MCP Tools in Agents
 
+**Automatic (Recommended):**
 ```bash
-# List all available agents (150+ total)
-npx agentic-flow --list
-
-# Run specific agent (local execution)
-npx agentic-flow --agent <name> --task "<description>"
-
-# Enable real-time streaming
-npx agentic-flow --agent coder --task "Build API" --stream
-
-# Run parallel mode (3 agents simultaneously)
-npx agentic-flow  # Requires TOPIC, DIFF, DATASET env vars
-```
-
-### Environment Configuration
-
-```bash
-# Required
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Agent mode (optional)
-export AGENT=researcher
-export TASK="Your task description"
-
-# Parallel mode (optional)
-export TOPIC="research topic"
-export DIFF="code changes"
-export DATASET="data to analyze"
-
-# Options
-export ENABLE_STREAMING=true
-export HEALTH_PORT=8080
-```
-
-### Docker Deployment
-
-```bash
-# Build image
-docker build -t agentic-flow .
-
-# Run agent in container
-docker run --rm \
-  -e ANTHROPIC_API_KEY=sk-ant-... \
-  agentic-flow \
-  --agent researcher \
-  --task "Analyze cloud patterns"
-
-# Run with streaming
-docker run --rm \
-  -e ANTHROPIC_API_KEY=sk-ant-... \
-  -e ENABLE_STREAMING=true \
-  agentic-flow \
-  --agent coder --task "Build REST API" --stream
+# Tools available automatically when ENABLE_CLAUDE_FLOW_SDK=true
+export ENABLE_CLAUDE_FLOW_SDK=true
+npx agentic-flow --agent coder --task "Store config in memory_store"
 ```
 
----
-
----
-
-## 🎛️ Using the Multi-Model Router
-
-### Quick Start with Router
-
+**Manual (Advanced):**
 ```javascript
-import { ModelRouter } from 'agentic-flow/router';
-
-// Initialize router (auto-loads configuration)
-const router = new ModelRouter();
-
-// Use default provider (Anthropic)
-const response = await router.chat({
-  model: 'claude-3-5-sonnet-20241022',
-  messages: [{ role: 'user', content: 'Your prompt here' }]
-});
-
-console.log(response.content[0].text);
-console.log(`Cost: $${response.metadata.cost}`);
-```
+import { query } from '@anthropic-ai/claude-agent-sdk';
 
-### Available Providers
-
-The router supports multiple LLM providers with automatic fallback:
-
-**Anthropic (Cloud)**
-- Models: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus
-- Cost: $0.003/1K input tokens, $0.015/1K output tokens
-- Best for: Complex reasoning, advanced coding, long conversations
-
-**OpenRouter (Multi-Model Gateway)**
-- Models: 100+ models from multiple providers
-- Cost: $0.002-0.10/1K tokens (varies by model)
-- Best for: Cost optimization, model diversity, fallback
-
-**ONNX Runtime (Free Local)**
-- Models: Microsoft Phi-4-mini-instruct (INT4 quantized)
-- Cost: **$0.00** (100% free)
-- Best for: Privacy-sensitive data, offline operation, zero-cost development
-
-**Ollama (Local Server - Coming Soon)**
-- Models: Any Ollama-supported model
-- Cost: Free (requires local Ollama server)
-- Best for: Local development with larger models
-
-**LiteLLM (Gateway - Coming Soon)**
-- Models: Unified API for 100+ providers
-- Cost: Varies by provider
-- Best for: Multi-cloud deployments
-
-**Configuration Example:**
-```json
-// router.config.json
-{
-  "defaultProvider": "anthropic",
-  "fallbackChain": ["anthropic", "onnx", "openrouter"],
-  "providers": {
-    "anthropic": {
-      "apiKey": "sk-ant-...",
-      "models": { "default": "claude-3-5-sonnet-20241022" }
-    },
-    "openrouter": {
-      "apiKey": "sk-or-...",
-      "baseUrl": "https://openrouter.ai/api/v1",
-      "models": { "default": "anthropic/claude-3.5-sonnet" }
-    },
-    "onnx": {
-      "modelPath": "./models/phi-4/.../model.onnx",
-      "executionProviders": ["cpu"],
-      "localInference": true
+const result = await query({
+  prompt: 'Store API key in memory',
+  options: {
+    mcpServers: {
+      'claude-flow-sdk': {
+        command: 'npx',
+        args: ['claude-flow', 'mcp', 'start'],
+        env: { ENABLE_CLAUDE_FLOW_SDK: 'true' }
+      }
     }
   }
-}
+});
 ```
 
-### OpenRouter Integration (99% Cost Savings)
+### MCP Tool Categories
+
+**1. Memory & Storage (claude-flow-sdk)**
+- `memory_store` - Store persistent key-value data
+- `memory_retrieve` - Retrieve stored data
+- `memory_search` - Search memory by pattern
+- `memory_list` - List all stored keys
+- `memory_delete` - Delete stored data
+
+**2. Swarm Coordination (claude-flow)**
+- `swarm_init` - Initialize multi-agent swarm
+- `agent_spawn` - Create specialized agents
+- `task_orchestrate` - Distribute work across agents
+- `swarm_status` - Monitor swarm health
+- `coordination_sync` - Synchronize agent state
+
+**3. GitHub Integration (claude-flow)**
+- `github_repo_analyze` - Repository analysis
+- `github_pr_manage` - PR lifecycle management
+- `github_code_review` - Automated code review
+- `github_issue_track` - Issue triage and tracking
+- `github_workflow_auto` - CI/CD automation
+
+**4. Cloud Sandboxes (flow-nexus)**
+- `sandbox_create` - Isolated execution environments
+- `sandbox_execute` - Run code in sandbox
+- `sandbox_upload` - Upload files to sandbox
+- `sandbox_status` - Check sandbox health
+- `sandbox_delete` - Cleanup sandbox
+
+**5. Neural Networks (claude-flow)**
+- `neural_train` - Train models with WASM acceleration
+- `neural_predict` - Run inference
+- `neural_patterns` - Analyze cognitive patterns
+- `neural_status` - Model metrics
+
+**6. Workflows (flow-nexus)**
+- `workflow_create` - Event-driven automation
+- `workflow_execute` - Run workflow with message queues
+- `workflow_status` - Monitor execution
+- `workflow_agent_assign` - Optimal agent assignment
+
+**7. Payments (agentic-payments)**
+- `create_active_mandate` - Payment authorization with spend caps
+- `sign_mandate` - Ed25519 cryptographic signing
+- `verify_mandate` - Signature verification
+- `verify_consensus` - Multi-agent Byzantine consensus
 
-Access 100+ LLM models through OpenRouter for dramatic cost savings while maintaining full functionality:
+---
 
-```bash
-# Set OpenRouter API key
-export OPENROUTER_API_KEY=sk-or-v1-...
+## 📚 Tutorial: Standalone Proxy
 
-# Use any OpenRouter model (proxy auto-starts)
-npx agentic-flow \
-  --agent coder \
-  --task "Build REST API" \
-  --model "meta-llama/llama-3.1-8b-instruct"
+### What is the Standalone Proxy?
 
-# Or force OpenRouter mode
-export USE_OPENROUTER=true
-npx agentic-flow --agent coder --task "Build REST API"
-```
+The standalone proxy lets you use **cheaper models** (Gemini, OpenRouter) with tools that expect the **Anthropic API** (Claude Code, future Cursor).
 
-**Popular OpenRouter Models:**
-- `meta-llama/llama-3.1-8b-instruct` - 99% cost savings, excellent coding
-- `deepseek/deepseek-chat-v3.1` - Superior code generation at 97% savings
-- `google/gemini-2.5-flash-preview-09-2025` - Fastest responses, 95% savings
-- `anthropic/claude-3.5-sonnet` - Full Claude via OpenRouter
+**How it works:**
+1. Proxy server translates Anthropic API ↔ Gemini/OpenRouter API
+2. Claude Code sends requests to proxy instead of Anthropic
+3. Proxy forwards to cheaper provider and translates responses
+4. MCP tools work seamlessly through proxy
 
-**Cost Comparison:**
-| Provider | Model | Input (1K tokens) | Output (1K tokens) | Savings |
-|----------|-------|-------------------|-------------------|---------|
-| Anthropic Direct | Claude 3.5 Sonnet | $0.003 | $0.015 | Baseline |
-| OpenRouter | Llama 3.1 8B | $0.00003 | $0.00006 | **99%** |
-| OpenRouter | DeepSeek V3.1 | $0.00014 | $0.00028 | **97%** |
-| OpenRouter | Gemini 2.5 Flash | $0.000075 | $0.0003 | **95%** |
-
-**How It Works:**
-1. Detects OpenRouter model (contains "/") or USE_OPENROUTER=true
-2. Auto-starts integrated proxy server on port 3000
-3. Translates Anthropic Messages API ↔ OpenAI Chat Completions API
-4. Claude Agent SDK transparently uses OpenRouter via ANTHROPIC_BASE_URL
-5. Full MCP tool support (all 203 tools work)
-
-**Environment Variables:**
-```bash
-# Required for OpenRouter
-export OPENROUTER_API_KEY=sk-or-v1-...
+### Setup: Gemini Proxy (85% savings)
 
-# Optional configuration
-export USE_OPENROUTER=true              # Force OpenRouter usage
-export COMPLETION_MODEL=meta-llama/...  # Default OpenRouter model
-export PROXY_PORT=3000                  # Proxy server port
-```
+```bash
+# Terminal 1: Start Gemini proxy
+export GOOGLE_GEMINI_API_KEY=your-key-here
+npx agentic-flow proxy
 
-### Free ONNX Local Inference
+# Proxy starts on http://localhost:3000
+# Instructions displayed for configuring Claude Code
 
-Run agents with **zero API costs** using local ONNX models:
+# Terminal 2: Configure Claude Code to use proxy
+export ANTHROPIC_BASE_URL=http://localhost:3000
+export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key  # Any value works
 
-```javascript
-// CPU Inference (6 tokens/sec, 100% free)
-const router = new ModelRouter();
-const onnxProvider = router.providers.get('onnx');
-
-const response = await onnxProvider.chat({
-  model: 'phi-4',
-  messages: [{ role: 'user', content: 'Analyze this sensitive data...' }],
-  maxTokens: 100
-});
+# Now use Claude Code normally
+claude
 
-console.log(response.content[0].text);
-console.log(`Cost: $${response.metadata.cost}`);  // $0.00
-console.log(`Latency: ${response.metadata.latency}ms`);
-console.log(`Privacy: 100% local processing`);
+# Or run agent directly
+claude --agent coder --task "Build REST API"
 ```
 
-### Privacy-Based Routing
-
-Automatically route privacy-sensitive workloads to free local ONNX inference:
-
-```javascript
-// Configure privacy routing in router.config.json
-{
-  "routing": {
-    "mode": "rule-based",
-    "rules": [
-      {
-        "condition": { "privacy": "high", "localOnly": true },
-        "action": { "provider": "onnx" },
-        "reason": "Privacy-sensitive tasks use free ONNX local models"
-      }
-    ]
-  }
-}
-
-// Router automatically uses ONNX for privacy workloads
-const response = await router.chat({
-  model: 'any-model',
-  messages: [{ role: 'user', content: 'Process medical records...' }],
-  metadata: { privacy: 'high', localOnly: true }
-});
-
-// Routed to ONNX automatically (zero cost, 100% local)
-console.log(response.metadata.provider);  // "onnx-local"
-```
+**Cost Savings:**
+- Gemini free tier: 100% savings vs Anthropic
+- All MCP tools work through proxy
+- Real-time streaming supported
 
-### GPU Acceleration
+### Setup: OpenRouter Proxy (90-99% savings)
 
-Enable GPU acceleration for 10-50x performance boost:
+```bash
+# Terminal 1: Start OpenRouter proxy
+export OPENROUTER_API_KEY=sk-or-v1-...
+npx agentic-flow proxy --provider openrouter --model "openai/gpt-4o-mini"
 
-```json
-// router.config.json
-{
-  "providers": {
-    "onnx": {
-      "executionProviders": ["cuda"],  // or ["dml"] for Windows
-      "gpuAcceleration": true,
-      "modelPath": "./models/phi-4/...",
-      "maxTokens": 100
-    }
-  }
-}
+# Terminal 2: Use Claude Code
+export ANTHROPIC_BASE_URL=http://localhost:3000
+export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
+claude --agent coder --task "Build web scraper"
 ```
 
-**Performance Comparison:**
-- CPU: 6 tokens/sec (free)
-- GPU (CUDA): 60-300 tokens/sec (free)
-- Cloud API: Variable (costs $0.002-0.003/request)
-
-### Zero-Cost Agent Execution
+**Popular OpenRouter Models:**
+- `openai/gpt-4o-mini` - $0.15/1M tokens (95% savings)
+- `deepseek/deepseek-chat-v3.1` - $0.014/1M tokens (99.5% savings)
+- `meta-llama/llama-3.3-70b-instruct` - $0.30/1M tokens (90% savings)
 
-Run agents entirely offline with local ONNX models:
+### Proxy Command Reference
 
 ```bash
-# Use ONNX provider for free inference
-npx agentic-flow \
-  --agent researcher \
-  --task "Analyze this privacy-sensitive data" \
-  --provider onnx \
-  --local-only
+# Start Gemini proxy (default)
+npx agentic-flow proxy
 
-# Result: $0.00 cost, 100% local processing
-```
+# Start OpenRouter proxy
+npx agentic-flow proxy --provider openrouter
 
-### Cost Comparison
+# Custom port
+npx agentic-flow proxy --port 8080
 
-| Workload Type | Provider | Cost per Request | Privacy | Performance |
-|---------------|----------|------------------|---------|-------------|
-| **Privacy-Sensitive** | ONNX (CPU) | **$0.00** | 100% local | 6 tokens/sec |
-| **Privacy-Sensitive** | ONNX (GPU) | **$0.00** | 100% local | 60-300 tokens/sec |
-| **Complex Reasoning** | Anthropic Claude | $0.003 | Cloud | Fast |
-| **General Tasks** | OpenRouter | $0.002 | Cloud | Variable |
+# Specific model
+npx agentic-flow proxy --provider openrouter --model "anthropic/claude-3.5-sonnet"
 
-**Example Monthly Costs (1000 requests/day):**
-- 100% ONNX: **$0** (free local inference)
-- 50% ONNX, 50% cloud: **$30-45** (50% savings)
-- 100% cloud APIs: **$60-90**
+# Help
+npx agentic-flow proxy --help
+```
 
----
+### How MCP Tools Work Through Proxy
 
-## 🔧 MCP Tools (213 Total)
+**Technical Implementation:**
 
-Agentic Flow integrates with **four MCP servers** providing 213 tools total:
+1. **Tool Schema Forwarding**
+   - Anthropic format: `{ name, description, input_schema }`
+   - OpenRouter format: `{ type: 'function', function: {...} }`
+   - Gemini format: `{ functionDeclarations: [{...}] }`
 
-### Direct MCP Access
+2. **Schema Cleaning for Gemini**
+   - Removes unsupported fields: `$schema`, `additionalProperties`
+   - Recursively cleans nested objects
 
-You can now directly manage MCP servers via the CLI:
+3. **Response Conversion**
+   - OpenRouter: `tool_calls` → `tool_use`
+   - Gemini: `functionCall` → `tool_use`
 
+**Example:**
 ```bash
-# Start all MCP servers
-npx agentic-flow mcp start
-
-# List all 213 available tools
-npx agentic-flow mcp list
-
-# Check server status
-npx agentic-flow mcp status
+# MCP tools work automatically through proxy
+export ENABLE_CLAUDE_FLOW_SDK=true
+export ANTHROPIC_BASE_URL=http://localhost:3000
+export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
 
-# Start specific server
-npx agentic-flow mcp start claude-flow
+# memory_store MCP tool works with Gemini (85% cost savings)
+npx agentic-flow --agent coder --task "Store API config in memory_store"
 ```
 
-**How It Works:**
-1. **Automatic** (Recommended): Agents automatically access all 213 tools when you run tasks
-2. **Manual**: Use `npx agentic-flow mcp <command>` for direct server management
-3. **Integrated**: All tools work seamlessly whether accessed automatically or manually
-
-### Tool Breakdown
-
-### Core Orchestration (claude-flow - 101 tools)
-
-| Category | Tools | Capabilities |
-|----------|-------|--------------|
-| **Swarm Management** | 12 | Initialize, spawn, coordinate multi-agent swarms |
-| **Memory & Storage** | 10 | Persistent memory with TTL and namespaces |
-| **Neural Networks** | 12 | Training, inference, WASM-accelerated computation |
-| **GitHub Integration** | 8 | PR management, code review, repository analysis |
-| **Performance** | 11 | Metrics, bottleneck detection, optimization |
-| **Workflow Automation** | 9 | Task orchestration, CI/CD integration |
-| **Dynamic Agents** | 7 | Runtime agent creation and coordination |
-| **System Utilities** | 8 | Health checks, diagnostics, feature detection |
-
-### Cloud Platform (flow-nexus - 96 tools)
-
-| Category | Tools | Capabilities |
-|----------|-------|--------------|
-| **☁️ E2B Sandboxes** | 12 | Isolated execution environments (Node, Python, React) |
-| **☁️ Distributed Swarms** | 8 | Cloud-based multi-agent deployment |
-| **☁️ Neural Training** | 10 | Distributed model training clusters |
-| **☁️ Workflows** | 9 | Event-driven automation with message queues |
-| **☁️ Templates** | 8 | Pre-built project templates and marketplace |
-| **☁️ Challenges** | 6 | Coding challenges with leaderboards |
-| **☁️ User Management** | 7 | Authentication, profiles, credit management |
-| **☁️ Storage** | 5 | Cloud file storage with real-time sync |
-
-### Payment Authorization (agentic-payments - MCP tools)
-
-Multi-agent payment infrastructure for autonomous AI commerce:
-
-| Category | Tools | Capabilities |
-|----------|-------|--------------|
-| **💳 Active Mandates** | MCP | Create spending limits, time windows, merchant restrictions |
-| **🔐 Ed25519 Signatures** | MCP | Cryptographic transaction signing (<1ms verification) |
-| **🤝 Multi-Agent Consensus** | MCP | Byzantine fault-tolerant transaction approval |
-| **📊 Payment Tracking** | MCP | Authorization to settlement lifecycle monitoring |
-| **🛡️ Security** | MCP | Spend caps, revocation, audit trails |
-
-**Use Cases:**
-- E-commerce: AI shopping agents with weekly budgets
-- Finance: Robo-advisors executing trades within portfolios
-- Enterprise: Multi-agent procurement with consensus approval
-- Accounting: Automated AP/AR with policy-based workflows
-
-**Protocols:**
-- **AP2**: Agent Payments Protocol with Ed25519 signatures
-- **ACP**: Agentic Commerce Protocol (Stripe-compatible)
-- **MCP**: Natural language interface for AI assistants
-
-### In-Process Tools (claude-flow-sdk - 6 tools)
-
-Fast, zero-latency tools running in-process:
-- `memory_store`, `memory_retrieve`, `memory_list`
-- `swarm_init`, `agent_spawn`, `coordination_sync`
-
 ---
 
-## ⚡ FastMCP Integration (New)
-
-Agentic Flow now supports **[FastMCP](https://github.com/QuantGeekDev/fastmcp)**, a modern TypeScript framework for building high-performance MCP servers with:
+## 📚 Tutorial: Deployment Options
 
-- **Dual Transport**: stdio (local/subprocess) + HTTP streaming (cloud/network)
-- **Type Safety**: Full TypeScript + Zod schema validation
-- **Progress Reporting**: Real-time execution feedback
-- **Authentication**: JWT, API keys, OAuth 2.0 support
-- **Rate Limiting**: Built-in abuse prevention
+### Local Development (Best for Prototyping)
 
-### POC Server (Phase 0 - Completed ✅)
+**What it does:** Runs agents directly on your machine with full MCP tool access.
 
-Basic stdio server with 2 tools to validate fastmcp integration:
+**When to use:** Development, testing, debugging, low-cost experimentation.
 
 ```bash
-# Test the POC server
-npm run test:fastmcp
-
-# Or run directly
-npm run mcp:fastmcp-poc
-```
-
-### Using with Claude Code
-
-Add to your MCP config (`~/.config/claude/mcp.json`):
+# Install globally
+npm install -g agentic-flow
 
-```json
-{
-  "mcpServers": {
-    "fastmcp-poc": {
-      "command": "node",
-      "args": ["/path/to/agentic-flow/dist/mcp/fastmcp/servers/poc-stdio.js"]
-    }
-  }
-}
+# Run locally
+export ANTHROPIC_API_KEY=sk-ant-...
+npx agentic-flow --agent coder --task "Build REST API"
 ```
 
-### Available FastMCP Tools (POC)
-
-| Tool | Description | Status |
-|------|-------------|--------|
-| `memory_store` | Store value in persistent memory | ✅ Working |
-| `memory_retrieve` | Retrieve value from memory | ✅ Working |
-
-**Coming Soon (Phase 1):**
-- Migration of 6 claude-flow-sdk tools to fastmcp
-- HTTP streaming transport with authentication
-- Direct in-process execution (no execSync)
-- Comprehensive test suite
-
-**Documentation:**
-- [FastMCP Implementation Plan](docs/mcp/fastmcp-implementation-plan.md) - 10-week migration strategy
-- [FastMCP POC Integration](docs/mcp/fastmcp-poc-integration.md) - Usage and testing guide
+**Benefits:**
+- ✅ All 213 MCP tools work
+- ✅ Fast iteration (<500ms warm start)
+- ✅ Free infrastructure (API costs only)
+- ✅ Full filesystem access
+- ✅ Git integration
 
----
-
-## 🔍 Deployment Comparison
-
-| Feature | Local | Docker | Flow Nexus Sandboxes | ONNX Local |
-|---------|-------|--------|----------------------|------------|
-| **MCP Tools Available** | 203 (100%) | 203 (100%) | 203 (100%) | 6 (3%) |
-| **Setup Complexity** | Low | Medium | Medium | Low |
-| **Cold Start Time** | <500ms | <2s | <2s | ~2s (first load) |
-| **Cost (Development)** | Free* | Free* | $1/hour | $0 (100% free) |
-| **Cost (Production)** | Free* | Infra costs | $1/hour | $0 (100% free) |
-| **Privacy** | Local | Local | Cloud | 100% Offline |
-| **Scaling** | Manual | Orchestrator | Automatic | Manual |
-| **Best For** | Dev/Testing | CI/CD/Prod | Cloud-Scale | Privacy/Offline |
-
-*Free infrastructure, Claude API costs only
+**Requirements:**
+- Node.js ≥18.0.0
+- 2GB RAM minimum (4GB for swarms)
+- macOS, Linux, or Windows
 
 ---
 
-## 📦 Advanced Deployment Patterns
-
-### ☁️ Flow Nexus Cloud Sandboxes (Scalable Production)
-
-**Best for cloud-native, auto-scaling workloads:**
-
-```javascript
-// Full-featured agent execution in isolated E2B sandboxes
-import { flowNexus } from 'flow-nexus';
-
-// Setup: One-time authentication
-await flowNexus.login({
-  email: process.env.FLOW_NEXUS_EMAIL,
-  password: process.env.FLOW_NEXUS_PASSWORD
-});
-
-// Deploy: Create sandbox and execute
-async function deployAgent(task) {
-  // 1. Create isolated sandbox
-  const sandbox = await flowNexus.sandboxCreate({
-    template: 'node', // or 'python', 'react', 'nextjs'
-    name: `agent-${Date.now()}`,
-    env_vars: {
-      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY
-    },
-    install_packages: ['@anthropic-ai/claude-agent-sdk'],
-    timeout: 3600 // 1 hour max
-  });
-
-  // 2. Execute agent with ALL 203 MCP tools
-  const result = await flowNexus.sandboxExecute({
-    sandbox_id: sandbox.id,
-    code: `
-      const { query } = require('@anthropic-ai/claude-agent-sdk');
-      const result = await query({
-        prompt: "${task}",
-        options: {
-          permissionMode: 'bypassPermissions',
-          mcpServers: {
-            'claude-flow-sdk': /* 6 tools */,
-            'claude-flow': /* 101 tools */,
-            'flow-nexus': /* 96 tools */
-          }
-        }
-      });
-      console.log(JSON.stringify(result));
-    `,
-    language: 'javascript',
-    capture_output: true
-  });
-
-  // 3. Cleanup (automatic after timeout)
-  await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });
-
-  return result;
-}
-```
+### Docker Containers (Best for Production)
 
-**Why Flow Nexus is Recommended:**
-- ✅ **Full MCP Support**: All 203 tools work (subprocess servers supported)
-- ✅ **Persistent Memory**: Claude Flow memory persists across sandboxes
-- ✅ **Security**: Complete process isolation per sandbox
-- ✅ **Multi-Language**: Node.js, Python, React, Next.js templates
-- ✅ **Real-Time**: Live output streaming and monitoring
-- ✅ **Cost-Effective**: Pay per use (10 credits/hour ≈ $1/hour)
-
-**Flow Nexus Pricing:**
-| Resource | Cost | Notes |
-|----------|------|-------|
-| Sandbox (hourly) | 10 credits | ≈ $1/hour per sandbox |
-| Storage | 1 credit/GB/month | Files and environment data |
-| Credits Package | $10 = 100 credits | 10+ hours of sandbox time |
+**What it does:** Packages agents in containers for Kubernetes, ECS, Cloud Run.
 
----
+**When to use:** CI/CD pipelines, production deployments, reproducible environments.
 
-### 🐳 Container Platforms (Production Orchestration)
+```bash
+# Build image
+docker build -t agentic-flow .
 
-#### Docker (ECS, Cloud Run, Fargate, Kubernetes)
+# Run agent in container
+docker run --rm \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  agentic-flow \
+  --agent researcher \
+  --task "Analyze cloud patterns"
 
-```dockerfile
-FROM node:20-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --production
-COPY . .
-CMD ["npm", "start", "--", "--agent", "${AGENT}", "--task", "${TASK}"]
+# Run with OpenRouter (99% cost savings)
+docker run --rm \
+  -e OPENROUTER_API_KEY=sk-or-v1-... \
+  agentic-flow \
+  --agent coder \
+  --task "Build API" \
+  --model "meta-llama/llama-3.1-8b-instruct"
 ```
 
-**Best Practices:**
-- Use multi-stage builds for smaller images
-- Enable health checks for orchestrators
-- Set resource limits (CPU/memory)
-- All 203 MCP tools available (subprocess servers work)
-- Use secrets managers for API keys
+**Benefits:**
+- ✅ All 213 MCP tools work
+- ✅ Reproducible builds
+- ✅ Works on Kubernetes, ECS, Cloud Run, Fargate
+- ✅ Process isolation
+- ✅ CI/CD integration
 
-#### Kubernetes
+**Orchestration Examples:**
 
+**Kubernetes Job:**
 ```yaml
 apiVersion: batch/v1
 kind: Job
 metadata:
-  name: agentic-flow-job
+  name: code-review
 spec:
   template:
     spec:
       containers:
       - name: agent
         image: agentic-flow:latest
-        args: ["--agent", "researcher", "--task", "$(TASK)"]
+        args: ["--agent", "code-review", "--task", "Review PR #123"]
         env:
         - name: ANTHROPIC_API_KEY
           valueFrom:
             secretKeyRef:
-              name: anthropic-secret
+              name: anthropic
               key: api-key
       restartPolicy: Never
 ```
 
-**Best Practices:**
-- Use Jobs for ephemeral executions
-- Set activeDeadlineSeconds for timeouts
-- Use node selectors for cost optimization
-- Implement PodDisruptionBudgets
-- All 203 MCP tools available
-
-### 💡 ONNX Local Inference - Extended Configuration
-
-**Advanced ONNX setup with router integration:**
-
-```javascript
-// router.config.json - Auto-route privacy tasks to ONNX
-{
-  "routing": {
-    "rules": [
-      {
-        "condition": { "privacy": "high", "localOnly": true },
-        "action": { "provider": "onnx" }
-      },
-      {
-        "condition": { "cost": "free" },
-        "action": { "provider": "onnx" }
-      }
-    ]
-  },
-  "providers": {
-    "onnx": {
-      "modelPath": "./models/phi-4/model.onnx",
-      "maxTokens": 2048,
-      "temperature": 0.7
-    }
-  }
-}
-```
-
-**Performance Benchmarks:**
-| Metric | CPU (Intel i7) | GPU (NVIDIA RTX 3060) |
-|--------|---------------|----------------------|
-| Tokens/sec | ~6 | 60-300 |
-| First Token | ~2s | ~500ms |
-| Model Load | ~3s | ~2s |
-| Memory Usage | ~2GB | ~3GB |
-| Cost | $0 | $0 |
-
-**Use Cases:**
-- ✅ Privacy-sensitive data processing
-- ✅ Offline/air-gapped environments
-- ✅ Cost-conscious development
-- ✅ Compliance requirements (HIPAA, GDPR)
-- ✅ Prototype/testing without API costs
-
-**Documentation:**
-- [ONNX Integration Guide](docs/ONNX_INTEGRATION.md)
-- [ONNX CLI Usage](docs/ONNX_CLI_USAGE.md)
-- [ONNX vs Claude Quality Analysis](docs/ONNX_VS_CLAUDE_QUALITY.md)
-  const sandbox = await flowNexus.sandboxCreate({
-    template: 'node',
-    env_vars: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }
-  });
-
-  const result = await flowNexus.sandboxExecute({
-    sandbox_id: sandbox.id,
-    code: `/* Full agent code with all 203 tools */`
-  });
-
-  await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });
-
-  return { statusCode: 200, body: JSON.stringify(result) };
-};
-```
-
----
-
-## 📊 Architecture
-
-### Ephemeral Agent Lifecycle
-
-```
-1. REQUEST → Agent definition loaded from YAML
-2. SPAWN → Agent initialized with system prompt + tools
-3. EXECUTE → Task processed using Claude SDK + MCP tools
-4. STREAM → Real-time output (optional)
-5. COMPLETE → Result returned to caller
-6. TERMINATE → Agent process exits, memory released
-```
-
-**Key Characteristics:**
-- **Cold Start**: <2s (includes MCP server initialization)
-- **Warm Start**: <500ms (MCP servers cached)
-- **Memory Usage**: 100-200MB per agent
-- **Concurrent Agents**: Limited only by host resources
-
-### Multi-Agent Coordination
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Researcher │────▶│   Memory    │◀────│ Code Review │
-│   Agent     │     │   Storage   │     │   Agent     │
-└─────────────┘     └─────────────┘     └─────────────┘
-                           │
-                           ▼
-                    ┌─────────────┐
-                    │    Data     │
-                    │   Analyst   │
-                    └─────────────┘
+**GitHub Actions:**
+```yaml
+- name: AI Code Review
+  run: |
+    docker run -e ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }} \
+      agentic-flow:latest \
+      --agent code-review \
+      --task "${{ github.event.pull_request.diff }}"
 ```
 
-**Coordination via:**
-- Shared memory (in-process or external)
-- Claude Flow MCP tools
-- File system (for batch jobs)
-- Message queues (for async workflows)
-
----
-
-## 🔍 Advanced Usage
-
-### Custom Agent Definition
-
-Create `.claude/agents/custom/my-agent.md`:
-
-```markdown
----
-name: my-agent
-description: Custom agent for specific tasks
 ---
 
-# System Prompt
+### Cloud Sandboxes (Best for Scale)
 
-You are a specialized agent for [your use case].
+**What it does:** Isolated E2B sandboxes with auto-scaling and cloud-native features.
 
-## Capabilities
-- [List capabilities]
+**When to use:** Production scale, multi-tenant workloads, distributed processing.
 
-## Guidelines
-- [Execution guidelines]
-```
+```javascript
+// Requires Flow Nexus registration (https://flow-nexus.ruv.io)
+const { flowNexus } = require('flow-nexus');
 
-### Programmatic API
+// 1. Login
+await flowNexus.login({ email: 'user@example.com', password: '***' });
 
-```javascript
-import { query } from '@anthropic-ai/claude-agent-sdk';
-import { getAgent } from 'agentic-flow/utils';
+// 2. Create sandbox
+const sandbox = await flowNexus.sandboxCreate({
+  template: 'node',
+  name: 'agent-execution',
+  env_vars: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }
+});
 
-const agent = getAgent('researcher');
-const result = await query({
-  prompt: 'Analyze AI trends',
-  options: {
-    systemPrompt: agent.systemPrompt,
-    permissionMode: 'bypassPermissions'
-  }
+// 3. Execute agent with all 213 MCP tools
+const result = await flowNexus.sandboxExecute({
+  sandbox_id: sandbox.id,
+  code: `
+    const { query } = require('@anthropic-ai/claude-agent-sdk');
+    await query({ prompt: "Analyze API security", options: { mcpServers: {...} } });
+  `
 });
 
-console.log(result.output);
+// 4. Cleanup
+await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });
 ```
 
-### Flow Nexus Integration
-
-Requires registration for cloud features:
-
-```bash
-# Register account
-npx agentic-flow --agent flow-nexus-auth \
-  --task "Register with email: user@example.com"
-
-# Login
-npx agentic-flow --agent flow-nexus-auth \
-  --task "Login with email: user@example.com, password: ***"
-
-# Create cloud sandbox
-npx agentic-flow --agent flow-nexus-sandbox \
-  --task "Create Node.js sandbox and execute: console.log('Hello')"
-```
+**Benefits:**
+- ✅ All 213 MCP tools work
+- ✅ Auto-scaling (1 to 100+ sandboxes)
+- ✅ Multi-language templates (Node, Python, React, Next.js)
+- ✅ Real-time streaming
+- ✅ Pay-per-use (10 credits/hour ≈ $1/hour)
 
 ---
 
-## 📈 Performance & Scaling
-
-### Benchmarks
-
-| Metric | Result |
-|--------|--------|
-| **Cold Start** | <2s (including MCP initialization) |
-| **Warm Start** | <500ms (cached MCP servers) |
-| **Agent Spawn** | 75 agents loaded in <2s |
-| **Tool Discovery** | 203 tools accessible in <1s |
-| **Memory Footprint** | 100-200MB per agent process |
-| **Concurrent Agents** | 10+ on t3.small, 100+ on c6a.xlarge |
-| **Token Efficiency** | 32% reduction via swarm coordination |
+## 📊 Cost Analysis
 
-### Cost Analysis - ONNX vs Cloud APIs
+### Monthly Costs for 100 Daily Code Reviews
 
-| Provider | Model | Tokens/sec | Cost per 1M tokens | Monthly (100K tasks) |
-|----------|-------|------------|-------------------|---------------------|
-| ONNX Local | Phi-4 | 6-300 | $0 | $0 |
-| OpenRouter | Llama 3.1 8B | API | $0.06 | $6 |
-| OpenRouter | DeepSeek | API | $0.14 | $14 |
-| Claude | Sonnet 3.5 | API | $3.00 | $300 |
+| Provider | Model | Cost per Review | Monthly Total | Savings |
+|----------|-------|----------------|---------------|---------|
+| Anthropic | Claude Sonnet 4.5 | $0.08 | **$240** | Baseline |
+| DeepSeek (OpenRouter) | deepseek-chat-v3.1 | $0.012 | **$36** | **85%** |
+| Llama (OpenRouter) | llama-3.1-8b | $0.003 | **$9** | **96%** |
+| Gemini (Proxy) | gemini-2.0-flash | $0.00 (free tier) | **$0** | **100%** |
+| ONNX (Local) | phi-4 | $0.00 | **$0** | **100%** |
 
-**ONNX Savings:** Up to $3,600/year for typical development workloads
+**Real Savings:**
+- **$204/month** switching to DeepSeek
+- **$231/month** switching to Llama 3.1
+- **$240/month** using Gemini free tier or ONNX
 
 ---
 
-## 🛠️ Development
+## 🛠️ Configuration
 
-### Build from Source
+### Environment Variables
 
 ```bash
-# Clone repository
-git clone https://github.com/ruvnet/agentic-flow.git
-cd agentic-flow
+# Required (choose one provider)
+export ANTHROPIC_API_KEY=sk-ant-...        # For Claude models
+export OPENROUTER_API_KEY=sk-or-v1-...     # For OpenRouter models
+export GOOGLE_GEMINI_API_KEY=AIza...        # For Gemini models
 
-# Install dependencies
-npm install
+# MCP Tools (optional)
+export ENABLE_CLAUDE_FLOW_SDK=true          # Enable in-SDK MCP tools
 
-# Build TypeScript
-npm run build
+# Proxy (optional)
+export ANTHROPIC_BASE_URL=http://localhost:3000  # For proxy usage
 
-# Test locally
-node dist/cli.js --help
+# Model Selection (optional)
+export COMPLETION_MODEL=meta-llama/llama-3.1-8b-instruct  # Override default
+
+# Execution (optional)
+export ENABLE_STREAMING=true                # Enable real-time streaming
+export HEALTH_PORT=8080                     # Health check port
 ```
 
-### Testing
+### Configuration File (.env)
 
 ```bash
-# Run all tests
-npm test
-
-# Test specific agent
-node dist/cli.js --agent researcher --task "Test task"
-
-# Validate MCP tools
-npm run validate
+# .env file (auto-loaded)
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-v1-...
+GOOGLE_GEMINI_API_KEY=AIza...
+ENABLE_CLAUDE_FLOW_SDK=true
+COMPLETION_MODEL=deepseek/deepseek-chat-v3.1
 ```
 
-### Adding Custom Agents
-
-1. Create agent definition: `.claude/agents/custom/my-agent.md`
-2. Define system prompt and capabilities
-3. Test: `npx agentic-flow --agent my-agent --task "Test"`
-4. Deploy: `npm run build && docker build -t my-agents .`
-
 ---
 
-## 🔗 Links
-
-- **Documentation**: [docs/](docs/)
-- **GitHub**: [github.com/ruvnet/agentic-flow](https://github.com/ruvnet/agentic-flow)
-- **npm Package**: [npmjs.com/package/agentic-flow](https://www.npmjs.com/package/agentic-flow)
-- **Claude Agent SDK**: [docs.claude.com/en/api/agent-sdk](https://docs.claude.com/en/api/agent-sdk)
-- **Flow Nexus Platform**: [github.com/ruvnet/flow-nexus](https://github.com/ruvnet/flow-nexus)
+## 📚 Complete Agent List
+
+### Core Development (5 agents)
+- `coder` - Implementation specialist
+- `reviewer` - Code review and QA
+- `tester` - Comprehensive testing
+- `planner` - Strategic planning
+- `researcher` - Research and analysis
+
+### Specialized Development (8 agents)
+- `backend-dev` - REST/GraphQL APIs
+- `mobile-dev` - React Native
+- `ml-developer` - Machine learning
+- `system-architect` - Architecture design
+- `cicd-engineer` - CI/CD pipelines
+- `api-docs` - API documentation
+- `production-validator` - Deployment checks
+- `base-template-generator` - Boilerplate generation
+
+### GitHub Integration (10 agents)
+- `pr-manager` - PR lifecycle
+- `code-review-swarm` - Multi-agent review
+- `issue-tracker` - Issue management
+- `release-manager` - Release coordination
+- `workflow-automation` - GitHub Actions
+- `repo-architect` - Repository structure
+- `multi-repo-swarm` - Multi-repo coordination
+- `sync-coordinator` - Cross-repo sync
+- `project-board-sync` - Project boards
+- `swarm-pr`, `swarm-issue` - Issue/PR swarms
+
+### Performance & Analysis (3 agents)
+- `perf-analyzer` - Bottleneck detection
+- `performance-benchmarker` - Benchmarking
+- `code-analyzer` - Code quality
+
+### Swarm Coordinators (5 agents)
+- `hierarchical-coordinator` - Tree structure
+- `mesh-coordinator` - Peer-to-peer
+- `adaptive-coordinator` - Dynamic topology
+- `swarm-memory-manager` - Memory sync
+- `collective-intelligence-coordinator` - Hive mind
+
+### Consensus & Distributed (6 agents)
+- `byzantine-coordinator` - Byzantine fault tolerance
+- `raft-manager` - Raft consensus
+- `gossip-coordinator` - Gossip protocol
+- `crdt-synchronizer` - CRDT sync
+- `quorum-manager` - Quorum management
+- `security-manager` - Security protocols
+
+### SPARC Methodology (6 agents)
+- `sparc-coord` - SPARC orchestration
+- `sparc-coder` - TDD implementation
+- `specification` - Requirements analysis
+- `pseudocode` - Algorithm design
+- `architecture` - System design
+- `refinement` - Iterative improvement
+
+### Testing (2 agents)
+- `tdd-london-swarm` - Mock-driven TDD
+- `production-validator` - Deployment validation
+
+### Planning (4 agents)
+- `goal-planner` - GOAP planning
+- `code-goal-planner` - Code-centric planning
+- `task-orchestrator` - Task coordination
+- `smart-agent` - Intelligent spawning
+
+### Specialized (7+ agents)
+- `migration-planner` - Code migration
+- `swarm-init` - Topology optimization
+- `memory-coordinator` - Cross-session memory
+- And 20+ more...
+
+**Total: 66+ agents** | Use `npx agentic-flow --list` to see all
 
 ---
 
-## 🤝 Contributing
+## 🔗 Links & Resources
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-### Development Setup
-1. Fork the repository
-2. Create feature branch: `git checkout -b feature/amazing-feature`
-3. Make changes and add tests
-4. Ensure tests pass: `npm test`
-5. Commit: `git commit -m "feat: add amazing feature"`
-6. Push: `git push origin feature/amazing-feature`
-7. Open Pull Request
+- **📦 NPM Package**: [npmjs.com/package/agentic-flow](https://www.npmjs.com/package/agentic-flow)
+- **🐙 GitHub**: [github.com/ruvnet/agentic-flow](https://github.com/ruvnet/agentic-flow)
+- **📖 Documentation**: [docs/](docs/)
+- **🤖 Claude Agent SDK**: [docs.claude.com/en/api/agent-sdk](https://docs.claude.com/en/api/agent-sdk)
+- **⚡ Claude Flow**: [github.com/ruvnet/claude-flow](https://github.com/ruvnet/claude-flow)
+- **☁️ Flow Nexus**: [github.com/ruvnet/flow-nexus](https://github.com/ruvnet/flow-nexus)
+- **🔀 OpenRouter**: [openrouter.ai](https://openrouter.ai)
 
 ---
 
@@ -1467,16 +792,8 @@ Built with:
 
 ---
 
-## 💬 Support
-
-- **Documentation**: See [docs/](docs/) folder
-- **Issues**: [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/ruvnet/agentic-flow/discussions)
-
----
-
-**Deploy ephemeral AI agents in seconds. Scale to thousands. Pay only for what you use.** 🚀
+**Deploy AI agents in seconds. Scale to thousands. Pay only for what you use.** 🚀
 
 ```bash
-npx agentic-flow --agent researcher --task "Your task here"
+npx agentic-flow --agent coder --task "Your task here"
 ```