claude-flow 3.0.0-alpha.7 → 3.0.0-alpha.71

package/v3/@claude-flow/cli/README.md

@@ -1,1186 +1,1198 @@
-# @claude-flow/cli
+# Claude-Flow v3: Enterprise AI Orchestration Platform
 
-[![npm version](https://img.shields.io/npm/v/@claude-flow/cli.svg)](https://www.npmjs.com/package/@claude-flow/cli)
-[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/cli.svg)](https://www.npmjs.com/package/@claude-flow/cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
-[![Commands](https://img.shields.io/badge/Commands-14+-orange.svg)](https://github.com/ruvnet/claude-flow)
-[![Subcommands](https://img.shields.io/badge/Subcommands-92+-purple.svg)](https://github.com/ruvnet/claude-flow)
+<div align="center">
 
-> Modern CLI module for Claude Flow V3 - comprehensive command-line interface with 14 commands, 92+ subcommands, interactive prompts, self-learning hooks, background workers, hive-mind coordination, and beautiful output formatting.
+[![Star on GitHub](https://img.shields.io/github/stars/ruvnet/claude-flow?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/claude-flow)
+[![Downloads](https://img.shields.io/npm/dt/claude-flow?style=for-the-badge&logo=npm&color=blue&label=Downloads)](https://www.npmjs.com/package/claude-flow)
+[![Latest Release](https://img.shields.io/npm/v/claude-flow/alpha?style=for-the-badge&logo=npm&color=green&label=v3.0.0-alpha)](https://www.npmjs.com/package/claude-flow)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-SDK%20Integrated-green?style=for-the-badge&logo=anthropic)](https://github.com/ruvnet/claude-flow)
+[![Agentics Foundation](https://img.shields.io/badge/Agentics-Foundation-crimson?style=for-the-badge&logo=openai)](https://discord.com/invite/dfxmpwkG2D)
+[![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/licenses/MIT)
 
-## Features
+**Production-ready multi-agent AI orchestration for Claude Code**
 
-### Core Capabilities
-- **14 Main Commands** - Complete CLI coverage for all Claude Flow operations
-- **92+ Subcommands** - Fine-grained control over every aspect of the system
-- **Advanced Argument Parsing** - Full support for flags, options, subcommands, and positional arguments
-- **Interactive Prompts** - Rich interactive mode with confirmations, selections, and input validation
-- **Beautiful Output** - Colored output, tables, progress bars, spinners, and multiple formats (text, JSON, table)
+*Deploy 54+ specialized agents in coordinated swarms with self-learning capabilities, fault-tolerant consensus, and enterprise-grade security.*
 
-### V3-Specific Features
-- **Self-Learning Hooks** - 17 hook subcommands + 12 background workers with pattern learning and neural integration
-- **Hive-Mind Coordination** - Queen-led Byzantine fault-tolerant multi-agent consensus
-- **15-Agent Swarm** - V3 hierarchical mesh coordination with domain specialization
-- **AgentDB Integration** - 150x-12,500x faster vector search with HNSW indexing
-- **SONA Learning** - Sub-0.05ms adaptation with Mixture of Experts routing
+</div>
 
-### Developer Experience
-- **Type-Safe** - Full TypeScript support with comprehensive type definitions
-- **Global Options** - Built-in `--help`, `--version`, `--verbose`, `--quiet`, `--format`
-- **Auto-Completion** - Shell completion support for commands and options
-- **Migration Tools** - Built-in V2 to V3 migration with rollback support
+## Overview
 
-## Installation
+Claude-Flow is a comprehensive AI agent orchestration framework that transforms Claude Code into a powerful multi-agent development platform. It enables teams to deploy, coordinate, and optimize specialized AI agents working together on complex software engineering tasks.
 
-```bash
-npm install @claude-flow/cli
-```
+### Claude Code: With vs Without Claude-Flow
 
-Or use globally:
+| Capability | Claude Code Alone | Claude Code + Claude-Flow |
+|------------|-------------------|---------------------------|
+| **Agent Collaboration** | Agents work in isolation, no shared context | Agents collaborate via swarms with shared memory and consensus |
+| **Coordination** | Manual orchestration between tasks | Queen-led hierarchy with 5 consensus algorithms (Raft, Byzantine, Gossip) |
+| **Memory** | Session-only, no persistence | HNSW vector memory with 150x-12,500x faster retrieval |
+| **Learning** | Static behavior, no adaptation | SONA self-learning with <0.05ms adaptation, improves over time |
+| **Task Routing** | You decide which agent to use | Intelligent routing based on learned patterns (89% accuracy) |
+| **Complex Tasks** | Manual breakdown required | Automatic decomposition across 5 domains (Security, Core, Integration, Support) |
+| **Background Workers** | Nothing runs automatically | 12 context-triggered workers auto-dispatch on file changes, patterns, sessions |
+| **LLM Provider** | Anthropic only | 6 providers with automatic failover and cost-based routing (85% savings) |
+| **Security** | Standard protections | CVE-hardened with bcrypt, input validation, path traversal prevention |
+| **Performance** | Baseline | 2.8-4.4x faster tasks, 4-32x memory reduction via quantization |
 
-```bash
-npm install -g @claude-flow/cli
-claude-flow --version
-```
+### Key Capabilities
 
-## Quick Start
+- **54+ Specialized Agents** - Ready-to-use AI agents for coding, code review, testing, security audits, documentation, and DevOps tasks. Each agent is optimized for its specific role.
 
-```bash
-# Initialize a new project
-claude-flow init --wizard
+- **Coordinated Agent Teams** - Run unlimited agents simultaneously in organized swarms. Agents can spawn sub-workers, communicate, share context, and divide work automatically using patterns like hierarchical (queen/workers) or mesh (peer-to-peer).
 
-# Start MCP server
-claude-flow mcp start
+- **Learns From Your Workflow** - The system remembers what works. Successful patterns are stored and reused, routing similar tasks to the best-performing agents. Gets smarter over time.
 
-# Spawn an agent
-claude-flow agent spawn -t coder --name my-coder
+- **Works With Any LLM** - Switch between Claude, GPT-4, Gemini, Cohere, or local models like Llama. Automatic failover if one provider is unavailable. Smart routing picks the cheapest option that meets quality requirements.
 
-# Initialize a swarm
-claude-flow swarm init --v3-mode
+- **Plugs Into Claude Code** - Native integration via MCP (Model Context Protocol). Use claude-flow commands directly in your Claude Code sessions with full tool access.
 
-# Search memory
-claude-flow memory search -q "authentication patterns"
+- **Production-Ready Security** - Built-in protection against common vulnerabilities: input validation, path traversal prevention, command injection blocking, and safe credential handling.
 
-# Check system status
-claude-flow status --watch
-```
+### Why Claude-Flow v3?
 
-## Complete Command Reference
+Claude-Flow v3 introduces **self-learning neural capabilities** that no other agent orchestration framework offers. While competitors require manual agent configuration and static routing, Claude-Flow learns from every task execution, prevents catastrophic forgetting of successful patterns, and intelligently routes work to specialized experts.
 
-### Overview
+| Feature | Claude Flow v3 | CrewAI | LangGraph | AutoGen | MetaGPT |
+|---------|----------------|--------|-----------|---------|---------|
+| **Self-Learning** | SONA + EWC++ | - | - | - | - |
+| **Prevents Forgetting** | EWC++ consolidation | - | - | - | - |
+| **Expert Routing** | MoE (8 experts) | Manual roles | Graph edges | - | Fixed roles |
+| **Vector Memory** | HNSW (150x faster) | - | Via plugins | - | - |
+| **Hyperbolic Embeddings** | Poincaré ball model | - | - | - | - |
+| **Pattern Learning** | From trajectories | - | - | - | - |
+| **Work Ownership** | Claims system | - | - | - | - |
+| **Threat Detection** | AIDefence | - | - | - | - |
+| **Attention Optimization** | Flash Attention | - | - | - | - |
+| **Low-Rank Adaptation** | LoRA (128x compression) | - | - | - | - |
+| **Quantization** | Int8 (3.92x savings) | - | - | - | - |
+| **Consensus Protocols** | 5 (Raft, Byzantine, etc.) | - | - | - | - |
+| **Background Workers** | 12 auto-triggered | - | - | - | - |
+| **Multi-Provider LLM** | 6 with failover | 2 | 3 | 2 | 1 |
+| **MCP Integration** | Native | - | - | - | - |
+| **Swarm Topologies** | 4 (mesh, hierarchical, etc.) | 1 | 1 | 1 | 1 |
 
-| Command | Subcommands | Description |
-|---------|-------------|-------------|
-| `init` | 4 | Project initialization with wizard, presets, and configuration |
-| `agent` | 8 | Agent lifecycle management (spawn, list, status, stop, metrics, pool, health, logs) |
-| `swarm` | 6 | Multi-agent swarm coordination and orchestration |
-| `memory` | 11 | AgentDB memory operations with vector search |
-| `mcp` | 9 | MCP server management and tool execution |
-| `task` | 6 | Task creation, assignment, and lifecycle management |
-| `session` | 7 | Session state management and persistence |
-| `config` | 7 | Configuration management and provider setup |
-| `status` | 3 | System status monitoring with watch mode |
-| `start` | 3 | Service startup and quick launch |
-| `workflow` | 6 | Workflow execution and template management |
-| `hooks` | 17 | Self-learning hooks with neural pattern recognition + 12 background workers |
-| `hive-mind` | 6 | Queen-led consensus-based multi-agent coordination |
-| `migrate` | 5 | V2 to V3 migration with rollback support |
+**Key differentiators:**
+- **SONA (Self-Optimizing Neural Architecture)** - Learns optimal agent routing from trajectory outcomes with <0.05ms adaptation
+- **EWC++ (Elastic Weight Consolidation)** - Prevents catastrophic forgetting when learning new patterns
+- **MoE (Mixture of Experts)** - 8 specialized experts with dynamic gating network for intelligent task routing
+- **Flash Attention** - 2.49x-7.47x speedup for attention computations
+- **Hyperbolic Embeddings** - Poincaré ball model for hierarchical data representation (better for code structure)
+- **LoRA (Low-Rank Adaptation)** - 128x memory compression for efficient fine-tuning
+- **Int8 Quantization** - 3.92x memory reduction with minimal accuracy loss
+- **Claims System** - Human-agent work ownership with handoff protocols
+- **Byzantine Consensus** - Fault-tolerant coordination even with malicious agents
 
----
+### Intelligent 3-Tier Model Routing (ADR-026)
 
-### `init` - Project Initialization
+Automatically routes tasks to the optimal handler for **75% cost reduction** and **2.5x quota extension** for Claude Max users:
 
-Initialize Claude Flow V3 with interactive wizard or presets.
+| Tier | Handler | Latency | Cost | Use Cases |
+|------|---------|---------|------|-----------|
+| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms: var→const, add-types, remove-console |
+| **2** | Haiku/Sonnet | 500ms-2s | $0.0002-$0.003 | Bug fixes, refactoring, feature implementation |
+| **3** | Opus | 2-5s | $0.015 | Architecture, security design, distributed systems |
 
-```bash
-claude-flow init [subcommand] [options]
-```
-
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `wizard` | Interactive setup wizard with step-by-step configuration |
-| `check` | Validate current configuration and environment |
-| `skills` | List and manage available skills |
-| `hooks` | Configure and validate hooks integration |
-
-#### Options
-
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--preset` | `-p` | Configuration preset (minimal, default, full, custom) | `default` |
-| `--force` | `-f` | Overwrite existing configuration | `false` |
-| `--skip-deps` | | Skip dependency installation | `false` |
-| `--topology` | `-t` | Swarm topology (hierarchical, mesh, hybrid) | `hierarchical` |
-| `--max-agents` | `-m` | Maximum concurrent agents | `15` |
-| `--memory-backend` | | Memory backend (agentdb, sqlite, hybrid) | `hybrid` |
-| `--enable-hnsw` | | Enable HNSW indexing (150x faster) | `true` |
-| `--enable-neural` | | Enable SONA neural learning | `true` |
-
-#### Examples
+**Benchmark Results:** 100% accuracy, 0.57ms avg routing latency
 
 ```bash
-# Interactive wizard
-claude-flow init --wizard
-
-# Quick setup with defaults
-claude-flow init --preset default
+# Example: Task automatically routed to appropriate tier
+npx claude-flow@v3alpha hooks pre-task --description "Add type annotations to server.ts"
+# → [AGENT_BOOSTER_AVAILABLE] Skip LLM - use Agent Booster for "add-types"
 
-# Full V3 setup with all features
-claude-flow init --preset full --enable-hnsw --enable-neural
-
-# Validate configuration
-claude-flow init check
+npx claude-flow@v3alpha hooks pre-task --description "Design OAuth2 with PKCE"
+# → [TASK_MODEL_RECOMMENDATION] Use model="opus" for this task
 ```
 
 ---
 
-### `agent` - Agent Management
+## Quick Start
 
-Spawn, manage, and monitor AI agents with various specializations.
+### Prerequisites
 
-```bash
-claude-flow agent <subcommand> [options]
-```
+- **Node.js 18+** or **Bun 1.0+** (Bun is faster)
+- **npm 9+** / **pnpm** / **bun** package manager
 
-#### Subcommands
-
-| Subcommand | Aliases | Description |
-|------------|---------|-------------|
-| `spawn` | | Spawn a new agent with specified type and configuration |
-| `list` | `ls` | List all active agents with filtering options |
-| `status` | | Show detailed status and metrics for an agent |
-| `stop` | `kill` | Stop a running agent (graceful or forced) |
-| `metrics` | | Show agent performance metrics over time |
-| `pool` | | Manage agent pool for auto-scaling |
-| `health` | | Show agent health and resource metrics |
-| `logs` | | View agent activity logs with filtering |
-
-#### Agent Types
-
-| Type | Description | Capabilities |
-|------|-------------|--------------|
-| `coder` | Code development with neural patterns | code-generation, refactoring, debugging, testing |
-| `researcher` | Research with web access and data analysis | web-search, data-analysis, summarization, citation |
-| `tester` | Comprehensive testing with automation | unit-testing, integration-testing, coverage-analysis |
-| `reviewer` | Code review with security and quality checks | code-review, security-audit, quality-check |
-| `architect` | System design with enterprise patterns | system-design, pattern-analysis, scalability |
-| `coordinator` | Multi-agent orchestration and workflow | task-orchestration, agent-management, workflow-control |
-| `security-architect` | Security architecture and threat modeling | threat-modeling, security-patterns, compliance |
-| `security-auditor` | CVE remediation and security testing | vulnerability-scan, penetration-testing |
-| `memory-specialist` | AgentDB unification (150x-12,500x faster) | vector-search, agentdb, caching, optimization |
-| `performance-engineer` | 2.49x-7.47x optimization targets | benchmarking, profiling, optimization |
-
-#### Spawn Options
-
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--type` | `-t` | Agent type to spawn | required |
-| `--name` | `-n` | Agent name/identifier | auto-generated |
-| `--provider` | `-p` | LLM provider (anthropic, openrouter, ollama) | `anthropic` |
-| `--model` | `-m` | Model to use | provider default |
-| `--task` | | Initial task for the agent | none |
-| `--timeout` | | Agent timeout in seconds | `300` |
-| `--auto-tools` | | Enable automatic tool usage | `true` |
-
-#### Examples
+**IMPORTANT**: Claude Code must be installed first:
 
 ```bash
-# Spawn a coder agent
-claude-flow agent spawn -t coder --name my-coder
-
-# Spawn researcher with initial task
-claude-flow agent spawn -t researcher --task "Research React 19 features"
-
-# List all active agents
-claude-flow agent list
+# 1. Install Claude Code globally
+npm install -g @anthropic-ai/claude-code
 
-# List agents by type
-claude-flow agent list -t coder
-
-# Get detailed agent status
-claude-flow agent status agent-001
+# 2. (Optional) Skip permissions check for faster setup
+claude --dangerously-skip-permissions
+```
 
-# Show agent metrics for 24 hours
-claude-flow agent metrics -p 24h
+### Installation
 
-# View agent logs
-claude-flow agent logs -i agent-001 -f
+```bash
+# With npm/npx (Node.js)
+npm install claude-flow@v3alpha
+npx claude-flow@v3alpha init
 
-# Configure agent pool
-claude-flow agent pool --size 5 --min 2 --max 15 --auto-scale
+# With Bun (faster)
+bun add claude-flow@v3alpha
+bunx claude-flow@v3alpha init
 
-# Health check with detailed metrics
-claude-flow agent health -d
+# Start MCP server for Claude Code integration
+npx claude-flow@v3alpha mcp start
 
-# Stop agent gracefully
-claude-flow agent stop agent-001
+# Run a task with agents
+npx claude-flow@v3alpha --agent coder --task "Implement user authentication"
 
-# Force stop
-claude-flow agent stop agent-001 -f
+# List available agents
+npx claude-flow@v3alpha --list
 ```
 
 ---
 
-### `swarm` - Swarm Coordination
-
-Multi-agent swarm initialization, coordination, and management.
+## Features
 
+### Core Platform Capabilities
+
+| Capability | Description | Metrics |
+|------------|-------------|---------|
+| **54+ Specialized Agents** | Purpose-built AI agents for development, testing, security, and operations | 10 categories, unlimited concurrent |
+| **Multi-Topology Swarms** | Hierarchical, mesh, ring, star, and adaptive coordination patterns | 2.8-4.4x speed improvement |
+| **Self-Learning Hooks** | ReasoningBank pattern learning with HNSW vector search | 150x faster retrieval |
+| **MCP Integration** | Native Claude Code support via Model Context Protocol | 27+ tools available |
+| **Security-First Design** | Input validation, path traversal prevention, command sandboxing | CVE-1, CVE-2, CVE-3 addressed |
+| **Cross-Platform** | Full support for Windows, macOS, and Linux environments | Node.js 18+ |
+
+### Agent Ecosystem
+
+| Category | Agent Count | Key Agents | Purpose |
+|----------|-------------|------------|---------|
+| **Core Development** | 5 | coder, reviewer, tester, planner, researcher | Daily development tasks |
+| **V3 Specialized** | 10 | queen-coordinator, security-architect, memory-specialist | Enterprise orchestration |
+| **Swarm Coordination** | 5 | hierarchical-coordinator, mesh-coordinator, adaptive-coordinator | Multi-agent patterns |
+| **Consensus & Distributed** | 7 | byzantine-coordinator, raft-manager, gossip-coordinator | Fault-tolerant coordination |
+| **Performance** | 5 | perf-analyzer, performance-benchmarker, task-orchestrator | Optimization & monitoring |
+| **GitHub & Repository** | 9 | pr-manager, code-review-swarm, issue-tracker, release-manager | Repository automation |
+| **SPARC Methodology** | 6 | sparc-coord, specification, pseudocode, architecture | Structured development |
+| **Specialized Dev** | 8 | backend-dev, mobile-dev, ml-developer, cicd-engineer | Domain expertise |
+
+### Swarm Topologies
+
+| Topology | Recommended Agents | Best For | Execution Time | Memory/Agent |
+|----------|-------------------|----------|----------------|--------------|
+| **Hierarchical** | 6+ | Structured tasks, clear authority chains | 0.20s | 256 MB |
+| **Mesh** | 4+ | Collaborative work, high redundancy | 0.15s | 192 MB |
+| **Ring** | 3+ | Sequential processing pipelines | 0.12s | 128 MB |
+| **Star** | 5+ | Centralized control, spoke workers | 0.14s | 180 MB |
+| **Hybrid (Hierarchical-Mesh)** | 7+ | Complex multi-domain tasks | 0.18s | 320 MB |
+| **Adaptive** | 2+ | Dynamic workloads, auto-scaling | Variable | Dynamic |
+
+### Self-Learning & Intelligence
+
+| Feature | Technology | Performance | Description |
+|---------|------------|-------------|-------------|
+| **ReasoningBank** | HNSW Vector Search | 150x faster | Pattern storage with similarity-based retrieval |
+| **SONA Neural** | LoRA Fine-tuning | <0.05ms adaptation | Self-optimizing neural architecture |
+| **Pattern Learning** | EWC++ Memory | Zero forgetting | Continuous learning without catastrophic forgetting |
+| **Intent Routing** | MoE (Mixture of Experts) | 95%+ accuracy | Intelligent task-to-agent routing |
+| **Domain Detection** | Vector Clustering | Real-time | Automatic categorization (security, testing, performance) |
+| **Quality Tracking** | Success/Failure Metrics | Per-pattern | Historical performance tracking |
+
+### Memory & Storage
+
+| Backend | Technology | Performance | Use Case |
+|---------|------------|-------------|----------|
+| **AgentDB** | HNSW Indexing | 150x-12,500x faster | Primary vector storage |
+| **SQLite** | Relational DB | Standard | Metadata and structured data |
+| **Hybrid** | AgentDB + SQLite | Best of both | Recommended default |
+| **In-Memory** | RAM-based | Fastest | Temporary/session data |
+
+### MCP Tools & Integration
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Coordination** | `swarm_init`, `agent_spawn`, `task_orchestrate` | Swarm and agent lifecycle management |
+| **Monitoring** | `swarm_status`, `agent_list`, `agent_metrics`, `task_status` | Real-time status and metrics |
+| **Memory & Neural** | `memory_usage`, `neural_status`, `neural_train`, `neural_patterns` | Memory operations and learning |
+| **GitHub** | `github_swarm`, `repo_analyze`, `pr_enhance`, `issue_triage`, `code_review` | Repository integration |
+| **Workers** | `worker/run`, `worker/status`, `worker/alerts`, `worker/history` | Background task management |
+| **Hooks** | `hooks/pre-*`, `hooks/post-*`, `hooks/route`, `hooks/session-*`, `hooks/intelligence/*`, `hooks/worker/*` | 31 lifecycle hooks |
+| **Progress** | `progress/check`, `progress/sync`, `progress/summary`, `progress/watch` | V3 implementation tracking |
+
+### Security Features
+
+| Feature | Protection | Implementation |
+|---------|------------|----------------|
+| **Input Validation** | Injection attacks | Boundary validation on all inputs |
+| **Path Traversal Prevention** | Directory escape | Blocked patterns (`../`, `~/.`, `/etc/`) |
+| **Command Sandboxing** | Shell injection | Allowlisted commands, metacharacter blocking |
+| **Prototype Pollution** | Object manipulation | Safe JSON parsing with validation |
+| **TOCTOU Protection** | Race conditions | Symlink skipping and atomic operations |
+| **Information Disclosure** | Data leakage | Error message sanitization |
+| **CVE Monitoring** | Known vulnerabilities | Active scanning and patching |
+
+### Advanced Capabilities
+
+| Feature | Description | Benefit |
+|---------|-------------|---------|
+| **Automatic Topology Selection** | AI-driven topology choice based on task complexity | Optimal resource utilization |
+| **Parallel Execution** | Concurrent agent operation with load balancing | 2.8-4.4x speed improvement |
+| **Neural Training** | 27+ model support with continuous learning | Adaptive intelligence |
+| **Bottleneck Analysis** | Real-time performance monitoring and optimization | Proactive issue detection |
+| **Smart Auto-Spawning** | Dynamic agent creation based on workload | Elastic scaling |
+| **Self-Healing Workflows** | Automatic error recovery and task retry | High availability |
+| **Cross-Session Memory** | Persistent pattern storage across sessions | Continuous learning |
+| **Event Sourcing** | Complete audit trail with replay capability | Debugging and compliance |
+| **Background Workers** | 12 auto-triggered workers for analysis and optimization | Automated maintenance |
+| **GitHub Integration** | PR management, issue triage, code review automation | Repository workflow |
+
+### Plugin System (`@claude-flow/plugins`)
+
+| Component | Description | Key Features |
+|-----------|-------------|--------------|
+| **PluginBuilder** | Fluent builder for creating plugins | MCP tools, hooks, workers, providers |
+| **MCPToolBuilder** | Build MCP tools with typed parameters | String, number, boolean, enum params |
+| **HookBuilder** | Build hooks with conditions and transformers | Priorities, conditional execution, data transformation |
+| **WorkerPool** | Managed worker pool with auto-scaling | Min/max workers, task queuing, graceful shutdown |
+| **ProviderRegistry** | LLM provider management with fallback | Cost optimization, automatic failover |
+| **AgenticFlowBridge** | agentic-flow@alpha integration | Swarm coordination, agent spawning |
+| **AgentDBBridge** | Vector storage with HNSW indexing | 150x faster search, batch operations |
+| **Security Utilities** | Input validation and protection | Path traversal, injection, rate limiting |
+
+### Plugin Hook Events
+
+| Category | Events | Description |
+|----------|--------|-------------|
+| **Session** | `session:start`, `session:end` | Session lifecycle management |
+| **Agent** | `agent:pre-spawn`, `agent:post-spawn`, `agent:pre-terminate`, `agent:post-terminate` | Agent lifecycle hooks |
+| **Task** | `task:pre-execute`, `task:post-complete`, `task:error` | Task execution hooks |
+| **Tool** | `tool:pre-call`, `tool:post-call` | MCP tool invocation hooks |
+| **Memory** | `memory:pre-store`, `memory:post-store`, `memory:pre-retrieve`, `memory:post-retrieve` | Memory operation hooks |
+| **Swarm** | `swarm:initialized`, `swarm:shutdown`, `swarm:consensus-reached` | Swarm coordination hooks |
+| **File** | `file:pre-read`, `file:post-read`, `file:pre-write`, `file:post-write` | File operation hooks |
+| **Command** | `command:pre-execute`, `command:post-execute` | Shell command hooks |
+| **Learning** | `learning:pattern-learned`, `learning:pattern-applied` | Pattern learning hooks |
+
+### Plugin Worker Types
+
+| Worker Type | Purpose | Capabilities |
+|-------------|---------|--------------|
+| `coder` | Code implementation | Code generation, refactoring |
+| `reviewer` | Code review | Quality analysis, suggestions |
+| `tester` | Test generation/execution | Unit tests, integration tests |
+| `researcher` | Information gathering | Web search, documentation |
+| `planner` | Task planning | Decomposition, scheduling |
+| `coordinator` | Multi-agent coordination | Orchestration, consensus |
+| `security` | Security analysis | Vulnerability scanning, audit |
+| `performance` | Performance optimization | Profiling, benchmarking |
+| `specialized` | Custom capabilities | Domain-specific tasks |
+| `long-running` | Background tasks | Async processing, polling |
+
+### Plugin Performance
+
+| Metric | Target | Achieved |
+|--------|--------|----------|
+| Plugin load time | <50ms | ~20ms |
+| Hook execution | <1ms | ~0.5ms |
+| Worker spawn | <100ms | ~50ms |
+| Vector search (10K) | <10ms | ~5ms |
+
+### RuVector WASM Plugins
+
+| Plugin | Description | Performance |
+|--------|-------------|-------------|
+| **SemanticCodeSearchPlugin** | Semantic code search with vector embeddings | Real-time indexing |
+| **IntentRouterPlugin** | Routes user intents to optimal handlers | 95%+ accuracy |
+| **HookPatternLibraryPlugin** | Pre-built patterns for common tasks | Security, testing, performance |
+| **MCPToolOptimizerPlugin** | Optimizes MCP tool selection | Context-aware suggestions |
+| **ReasoningBankPlugin** | Vector-backed pattern storage with HNSW | 150x faster search |
+| **AgentConfigGeneratorPlugin** | Generates optimized agent configurations | From pretrain data |
+
+### Background Workers (12 Auto-Triggered)
+
+Workers run automatically in the background based on context, or can be dispatched manually via MCP tools.
+
+| Worker | Trigger | Purpose | Auto-Triggers On |
+|--------|---------|---------|------------------|
+| **UltraLearn** | `ultralearn` | Deep knowledge acquisition from codebase | New project, major refactors |
+| **Optimize** | `optimize` | Performance optimization suggestions | Slow operations detected |
+| **Consolidate** | `consolidate` | Memory pattern consolidation | Session end, memory threshold |
+| **Predict** | `predict` | Predictive resource preloading | Usage patterns detected |
+| **Audit** | `audit` | Security vulnerability analysis | Security-related file changes |
+| **Map** | `map` | Codebase structure mapping | New directories, large changes |
+| **Preload** | `preload` | Resource and dependency preloading | Project initialization |
+| **DeepDive** | `deepdive` | Deep code analysis and understanding | Complex file edits |
+| **Document** | `document` | Auto-documentation generation | New functions/classes created |
+| **Refactor** | `refactor` | Refactoring opportunity detection | Code smell patterns |
+| **Benchmark** | `benchmark` | Performance benchmarking | Performance-critical changes |
+| **TestGaps** | `testgaps` | Test coverage gap analysis | Code changes without tests |
+
+**Worker Commands:**
 ```bash
-claude-flow swarm <subcommand> [options]
-```
+# Dispatch a worker manually
+npx claude-flow@v3alpha worker dispatch --trigger audit --context "./src"
 
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `init` | Initialize a new swarm with specified topology |
-| `start` | Start swarm execution with objective and strategy |
-| `status` | Show swarm status, progress, and metrics |
-| `stop` | Stop swarm execution (with state save option) |
-| `scale` | Scale swarm agent count up or down |
-| `coordinate` | Execute V3 15-agent hierarchical mesh coordination |
-
-#### Topologies
-
-| Topology | Description | Best For |
-|----------|-------------|----------|
-| `hierarchical` | Queen-led coordination with worker agents | Structured tasks, clear authority |
-| `mesh` | Fully connected peer-to-peer network | Collaborative work, redundancy |
-| `ring` | Circular communication pattern | Sequential processing |
-| `star` | Central coordinator with spoke agents | Centralized control |
-| `hybrid` | Hierarchical mesh for maximum flexibility | Complex multi-domain tasks |
-
-#### Strategies
+# Check worker status
+npx claude-flow@v3alpha worker status
 
-| Strategy | Description | Agent Distribution |
-|----------|-------------|-------------------|
-| `research` | Distributed research and analysis | 1 coordinator, 4 researchers, 2 analysts |
-| `development` | Collaborative code development | 1 coordinator, 1 architect, 3 coders, 2 testers, 1 reviewer |
-| `testing` | Comprehensive test coverage | 1 test lead, 2 unit testers, 2 integration testers, 1 QA |
-| `optimization` | Performance optimization | 1 performance lead, 2 profilers, 2 optimizers |
-| `maintenance` | Codebase maintenance and refactoring | 1 coordinator, 2 refactorers, 1 documenter |
-| `analysis` | Code analysis and documentation | 1 analyst lead, 2 code analysts, 1 security analyst |
+# View completed results
+npx claude-flow@v3alpha worker results --limit 10
+```
 
-#### Examples
+### LLM Providers (`@claude-flow/providers`)
 
-```bash
-# Initialize V3 swarm (recommended)
-claude-flow swarm init --v3-mode
+| Provider | Models | Features | Cost |
+|----------|--------|----------|------|
+| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku | Native, streaming, tool calling | $3-15/1M tokens |
+| **OpenAI** | GPT-4o, GPT-4 Turbo, GPT-3.5, o1-preview, o3-mini | Function calling, vision | $0.50-60/1M tokens |
+| **Google** | Gemini 2.0 Flash, Gemini 1.5 Pro/Flash | Multimodal, long context | $0.075-7/1M tokens |
+| **Cohere** | Command R+, Command R, Command Light | RAG optimized | $0.50-15/1M tokens |
+| **Ollama** | Llama 3.2, Mistral, CodeLlama, DeepSeek | Local, free, offline | Free |
+| **RuVector** | Custom models via @ruvector/ruvllm | WASM optimized | Custom |
 
-# Initialize with specific topology
-claude-flow swarm init -t mesh --max-agents 10
+### Provider Load Balancing
 
-# Start development swarm
-claude-flow swarm start -o "Build REST API with authentication" -s development
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| `round-robin` | Rotate through providers sequentially | Even distribution |
+| `least-loaded` | Use provider with lowest current load | High throughput |
+| `latency-based` | Use fastest responding provider | Low latency |
+| `cost-based` | Use cheapest provider that meets requirements | Cost optimization (85%+ savings) |
 
-# Parallel analysis swarm
-claude-flow swarm start -o "Analyze codebase for performance issues" --parallel
+### Embedding Providers (`@claude-flow/embeddings`)
 
-# Check swarm status
-claude-flow swarm status swarm-123
+| Provider | Models | Dimensions | Latency | Cost |
+|----------|--------|------------|---------|------|
+| **Agentic-Flow** | ONNX SIMD optimized | 384 | ~3ms | Free (local) |
+| **OpenAI** | text-embedding-3-small/large, ada-002 | 1536-3072 | ~50-100ms | $0.02-0.13/1M tokens |
+| **Transformers.js** | all-MiniLM-L6-v2, all-mpnet-base-v2, bge-small | 384-768 | ~230ms | Free (local) |
+| **Mock** | Deterministic hash-based | Configurable | <1ms | Free |
 
-# Scale swarm
-claude-flow swarm scale swarm-123 --agents 20
+### Embedding Features
 
-# V3 15-agent coordination
-claude-flow swarm coordinate --agents 15
+| Feature | Description | Performance |
+|---------|-------------|-------------|
+| **Auto-Install** | `provider: 'auto'` installs agentic-flow automatically | Zero config |
+| **Smart Fallback** | agentic-flow → transformers → mock chain | Always works |
+| **75x Faster** | Agentic-flow ONNX vs Transformers.js | 3ms vs 230ms |
+| **LRU Caching** | Intelligent cache with hit rate tracking | <1ms cache hits |
+| **Batch Processing** | Efficient batch embedding with partial cache | 10 items <100ms |
+| **Similarity Functions** | Cosine, Euclidean, Dot product | Optimized math |
 
-# Stop with state save
-claude-flow swarm stop swarm-123 --save-state
-```
+### Consensus Strategies (`@claude-flow/swarm`)
 
----
+| Strategy | Algorithm | Fault Tolerance | Latency | Best For |
+|----------|-----------|-----------------|---------|----------|
+| **Byzantine (PBFT)** | Practical Byzantine Fault Tolerance | f < n/3 faulty nodes | ~100ms | Adversarial environments |
+| **Raft** | Leader-based log replication | f < n/2 failures | ~50ms | Strong consistency |
+| **Gossip** | Epidemic protocol dissemination | High partition tolerance | ~200ms | Eventually consistent |
+| **CRDT** | Conflict-free Replicated Data Types | Strong eventual consistency | ~10ms | Concurrent updates |
+| **Quorum** | Configurable read/write quorums | Flexible | ~75ms | Tunable consistency |
 
-### `memory` - Memory Management
+### CLI Commands (`@claude-flow/cli`)
 
-AgentDB memory operations with vector search, caching, and optimization.
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| `init` | 4 | Project initialization (wizard, check, skills, hooks) |
+| `agent` | 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
+| `swarm` | 6 | Swarm coordination (init, start, status, stop, scale, coordinate) |
+| `memory` | 11 | Memory operations (store, retrieve, search, list, delete, stats, configure, cleanup, compress, export, import) |
+| `mcp` | 9 | MCP server (start, stop, status, health, restart, tools, toggle, exec, logs) |
+| `task` | 6 | Task management (create, list, status, cancel, assign, retry) |
+| `session` | 7 | Session management (list, save, restore, delete, export, import, current) |
+| `config` | 7 | Configuration (init, get, set, providers, reset, export, import) |
+| `status` | 3 | System status with watch mode (agents, tasks, memory) |
+| `workflow` | 6 | Workflow execution (run, validate, list, status, stop, template) |
+| `hooks` | 32 | Self-learning hooks (pre/post-edit, pre/post-command, route, explain, pretrain, session-*, intelligence/*, worker/*, progress) |
+| `hive-mind` | 6 | Queen-led coordination (init, spawn, status, task, optimize-memory, shutdown) |
+| `migrate` | 5 | V2→V3 migration (status, run, verify, rollback, breaking) |
+| `neural` | 5 | Neural pattern training (train, status, patterns, predict, optimize) |
+| `security` | 6 | Security scanning (scan, audit, cve, threats, validate, report) |
+| `performance` | 5 | Performance profiling (benchmark, profile, metrics, optimize, report) |
+| `providers` | 5 | AI providers (list, add, remove, test, configure) |
+| `plugins` | 5 | Plugin management (list, install, uninstall, enable, disable) |
+| `deployment` | 5 | Deployment management (deploy, rollback, status, environments, release) |
+| `embeddings` | 13 | Vector embeddings with ONNX, hyperbolic space, neural substrate |
+| `daemon` | 5 | Background workers (start, stop, status, trigger, enable) |
+| `progress` | 4 | V3 implementation progress (check, sync, summary, watch) |
+| `claims` | 4 | Authorization (check, grant, revoke, list) |
+
+### Testing Framework (`@claude-flow/testing`)
+
+| Component | Description | Features |
+|-----------|-------------|----------|
+| **London School TDD** | Behavior verification with mocks | Mock-first, interaction testing |
+| **Vitest Integration** | ADR-008 compliant test runner | 10x faster than Jest |
+| **Fixture Library** | Pre-defined test data | Agents, memory, swarm, MCP |
+| **Mock Factory** | Application and service mocks | Auto-reset, state tracking |
+| **Async Utilities** | waitFor, retry, withTimeout | Reliable async testing |
+| **Performance Assertions** | V3 target validation | Speedup, memory, latency checks |
+
+### Testing Fixtures
+
+| Fixture Type | Contents | Use Case |
+|--------------|----------|----------|
+| `agentConfigs` | 15 V3 agent configurations | Agent testing |
+| `memoryEntries` | Patterns, rules, embeddings | Memory testing |
+| `swarmConfigs` | V3 default, minimal, mesh, hierarchical | Swarm testing |
+| `mcpTools` | 27+ tool definitions | MCP testing |
+
+### Deployment & CI/CD (`@claude-flow/deployment`)
+
+| Feature | Description | Automation |
+|---------|-------------|------------|
+| **Version Bumping** | major, minor, patch, prerelease | Automatic semver |
+| **Changelog Generation** | Conventional commits parsing | Auto-generated |
+| **Git Integration** | Tagging, committing | Automatic |
+| **NPM Publishing** | alpha, beta, rc, latest tags | Tag-based |
+| **Validation** | Lint, test, build, dependency checks | Pre-release |
+| **Dry Run Mode** | Test releases without changes | Safe testing |
+
+### Release Channels
+
+| Channel | Version Format | Purpose |
+|---------|---------------|---------|
+| `alpha` | 1.0.0-alpha.1 | Early development |
+| `beta` | 1.0.0-beta.1 | Feature complete, testing |
+| `rc` | 1.0.0-rc.1 | Release candidate |
+| `latest` | 1.0.0 | Stable production |
+
+### Integration (`@claude-flow/integration`)
+
+| Component | Description | Performance |
+|-----------|-------------|-------------|
+| **AgenticFlowBridge** | agentic-flow@alpha integration | ADR-001 compliant |
+| **SONA Adapter** | Learning system integration | <0.05ms adaptation |
+| **Flash Attention** | Attention mechanism coordinator | 2.49x-7.47x speedup |
+| **SDK Bridge** | Version negotiation, API compatibility | Auto-detection |
+| **Feature Flags** | Dynamic feature management | 9 configurable flags |
+| **Runtime Detection** | NAPI, WASM, JS auto-selection | Optimal performance |
+
+### Integration Runtimes
+
+| Runtime | Performance | Requirements |
+|---------|-------------|--------------|
+| **NAPI** | Optimal | Native bindings, x64 |
+| **WASM** | Good | WebAssembly support |
+| **JS** | Fallback | Always available |
+
+### Performance Benchmarking (`@claude-flow/performance`)
+
+| Capability | Description | Output |
+|------------|-------------|--------|
+| **Statistical Analysis** | Mean, median, P95, P99, stddev | Comprehensive metrics |
+| **Memory Tracking** | Heap, RSS, external, array buffers | Resource monitoring |
+| **Auto-Calibration** | Automatic iteration adjustment | Statistical significance |
+| **Regression Detection** | Baseline comparison | Change detection |
+| **V3 Target Validation** | Built-in performance targets | Pass/fail checking |
+
+### V3 Benchmark Targets
+
+| Category | Benchmark | Target |
+|----------|-----------|--------|
+| **Startup** | CLI cold start | <500ms |
+| **Startup** | MCP server init | <400ms |
+| **Startup** | Agent spawn | <200ms |
+| **Memory** | Vector search | <1ms |
+| **Memory** | HNSW indexing | <10ms |
+| **Memory** | Memory write | <5ms |
+| **Swarm** | Agent coordination | <50ms |
+| **Swarm** | Consensus latency | <100ms |
+| **Neural** | SONA adaptation | <0.05ms |
+
+### Neural & SONA (`@claude-flow/neural`)
+
+| Feature | Description | Performance |
+|---------|-------------|-------------|
+| **SONA Learning** | Self-Optimizing Neural Architecture | <0.05ms adaptation |
+| **5 Learning Modes** | real-time, balanced, research, edge, batch | Mode-specific optimization |
+| **9 RL Algorithms** | PPO, A2C, DQN, Q-Learning, SARSA, Decision Transformer, etc. | Comprehensive RL |
+| **LoRA Integration** | Low-Rank Adaptation for efficient fine-tuning | Minimal memory overhead |
+| **MicroLoRA** | Ultra-lightweight LoRA for edge/real-time modes | <5MB memory footprint |
+| **EWC++ Memory** | Elastic Weight Consolidation prevents catastrophic forgetting | Zero knowledge loss |
+| **Trajectory Tracking** | Execution path recording for pattern extraction | Continuous learning |
 
-```bash
-claude-flow memory <subcommand> [options]
-```
+### Memory & Vector Optimization
 
-#### Subcommands
-
-| Subcommand | Aliases | Description |
-|------------|---------|-------------|
-| `store` | | Store data in memory with optional vector embedding |
-| `retrieve` | `get` | Retrieve data from memory by key |
-| `search` | | Semantic/vector search with HNSW indexing |
-| `list` | `ls` | List memory entries with filtering |
-| `delete` | `rm` | Delete memory entry |
-| `stats` | | Show memory statistics and performance |
-| `configure` | `config` | Configure memory backend and HNSW parameters |
-| `cleanup` | | Clean up stale and expired entries |
-| `compress` | | Compress and optimize memory storage |
-| `export` | | Export memory to file (JSON, CSV, binary) |
-| `import` | | Import memory from file |
-
-#### Memory Backends
-
-| Backend | Description | Performance |
+| Feature | Description | Improvement |
 |---------|-------------|-------------|
-| `agentdb` | Vector database with HNSW indexing | 150x-12,500x faster search |
-| `sqlite` | Lightweight local storage | Good for small datasets |
-| `hybrid` | SQLite + AgentDB (recommended) | Best of both worlds |
-| `memory` | In-memory (non-persistent) | Fastest, no persistence |
+| **Scalar Quantization** | Reduce vector precision for memory savings | 4x memory reduction |
+| **Product Quantization** | Compress vectors into codebooks | 8-32x memory reduction |
+| **HNSW Indexing** | Hierarchical Navigable Small World graphs | 150x-12,500x faster search |
+| **LRU Caching** | Intelligent embedding cache with TTL | <1ms cache hits |
+| **Batch Processing** | Process multiple embeddings in single call | 10x throughput |
+| **Memory Compression** | Pattern distillation and pruning | 50-75% reduction |
 
-#### Search Options
+### Embedding System (`@claude-flow/embeddings`)
 
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--query` | `-q` | Search query | required |
-| `--namespace` | `-n` | Memory namespace | all |
-| `--limit` | `-l` | Maximum results | `10` |
-| `--threshold` | | Similarity threshold (0-1) | `0.7` |
-| `--type` | `-t` | Search type (semantic, keyword, hybrid) | `semantic` |
-
-#### Examples
+| Feature | Description | Performance |
+|---------|-------------|-------------|
+| **Multi-Provider** | Agentic-Flow (ONNX), OpenAI, Transformers.js, Mock | 4 providers |
+| **Auto-Install** | `claude-flow embeddings init` or `createEmbeddingServiceAsync()` | Zero config |
+| **75x Faster** | Agentic-flow ONNX SIMD vs Transformers.js | 3ms vs 230ms |
+| **Hyperbolic Space** | Poincaré ball model for hierarchical data | Exponential capacity |
+| **Dimensions** | 384 to 3072 configurable | Quality vs speed tradeoff |
+| **Similarity Metrics** | Cosine, Euclidean, Dot product, Hyperbolic distance | Task-specific matching |
+| **Neural Substrate** | Drift detection, memory physics, swarm coordination | agentic-flow integration |
+| **LRU + SQLite Cache** | Persistent cross-session caching | <1ms cache hits |
 
 ```bash
-# Store text data
-claude-flow memory store -k "api/auth" -v "JWT implementation with refresh tokens"
+# Initialize ONNX embeddings with hyperbolic config
+claude-flow embeddings init
 
-# Store as vector embedding
-claude-flow memory store -k "pattern/singleton" -v "Singleton pattern description" --vector
+# Use larger model for higher quality
+claude-flow embeddings init --model all-mpnet-base-v2
 
 # Semantic search
-claude-flow memory search -q "authentication patterns"
-
-# Keyword search
-claude-flow memory search -q "JWT" -t keyword
-
-# Hybrid search with threshold
-claude-flow memory search -q "security best practices" -t hybrid --threshold 0.8
-
-# List entries by namespace
-claude-flow memory list -n patterns
-
-# Show memory statistics
-claude-flow memory stats
-
-# Configure HNSW parameters
-claude-flow memory configure -b hybrid --hnsw-m 16 --hnsw-ef 200
-
-# Cleanup old entries
-claude-flow memory cleanup --older-than 30d
-
-# Cleanup expired TTL entries
-claude-flow memory cleanup --expired-only
-
-# Compress with quantization (32x memory reduction)
-claude-flow memory compress --quantize --bits 4
-
-# Export memory
-claude-flow memory export -o ./backup.json -f json
+claude-flow embeddings search -q "authentication patterns"
+```
 
-# Import memory
-claude-flow memory import -i ./backup.json --merge
+### SONA Learning Modes
+
+| Mode | Adaptation | Quality | Memory | Use Case |
+|------|------------|---------|--------|----------|
+| `real-time` | <0.5ms | 70%+ | 25MB | Production, low-latency |
+| `balanced` | <18ms | 75%+ | 50MB | General purpose |
+| `research` | <100ms | 95%+ | 100MB | Deep exploration |
+| `edge` | <1ms | 80%+ | 5MB | Resource-constrained |
+| `batch` | <50ms | 85%+ | 75MB | High-throughput |
+
+### RL Algorithms
+
+| Algorithm | Type | Best For |
+|-----------|------|----------|
+| **PPO** | Policy Gradient | Stable continuous learning |
+| **A2C** | Actor-Critic | Balanced exploration/exploitation |
+| **DQN** | Value-based | Discrete action spaces |
+| **Q-Learning** | Tabular | Simple state spaces |
+| **SARSA** | On-policy | Online learning |
+| **Decision Transformer** | Sequence modeling | Long-horizon planning |
+
+### Hive-Mind Coordination
+
+| Feature | Description | Capability |
+|---------|-------------|------------|
+| **Queen-Led Topology** | Hierarchical command structure | Unlimited agents + sub-workers |
+| **Byzantine Consensus** | Fault-tolerant agreement | f < n/3 tolerance |
+| **Collective Memory** | Shared pattern storage | Distillation, compression |
+| **Specialist Spawning** | Domain-specific agents | Security, performance, etc. |
+| **Adaptive Topology** | Dynamic structure changes | Load-based optimization |
+
+### agentic-flow@alpha Integration
+
+| Feature | Description | Benefit |
+|---------|-------------|---------|
+| **ADR-001 Compliance** | Build on agentic-flow, don't duplicate | Eliminates 10,000+ duplicate lines |
+| **Core Foundation** | Use agentic-flow as the base layer | Unified architecture |
+| **SONA Integration** | Seamless learning system connection | <0.05ms adaptation |
+| **Flash Attention** | Optimized attention mechanisms | 2.49x-7.47x speedup |
+| **AgentDB Bridge** | Vector storage integration | 150x-12,500x faster search |
+| **Feature Flags** | Dynamic capability management | 9 configurable features |
+| **Runtime Detection** | NAPI/WASM/JS auto-selection | Optimal performance per platform |
+| **Graceful Fallback** | Works with or without agentic-flow | Always functional |
+
+### MCP Server (`@claude-flow/mcp`)
+
+| Feature | Description | Spec |
+|---------|-------------|------|
+| **MCP 2025-11-25** | Full specification compliance | Latest MCP standard |
+| **Multiple Transports** | stdio, HTTP, WebSocket, in-process | Flexible connectivity |
+| **Resources** | list, read, subscribe with caching | Dynamic content |
+| **Prompts** | Templates with arguments and embedding | Reusable prompts |
+| **Tasks** | Async operations with progress/cancel | Long-running ops |
+| **Tool Registry** | O(1) lookup, <10ms registration | Fast tool access |
+| **Connection Pooling** | Max 10 connections, configurable | Resource management |
+| **Session Management** | Timeout handling, authentication | Secure sessions |
+
+### MCP Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize` | Initialize connection |
+| `tools/list` | List available tools |
+| `tools/call` | Execute a tool |
+| `resources/list` | List resources with pagination |
+| `resources/read` | Read resource content |
+| `resources/subscribe` | Subscribe to updates |
+| `prompts/list` | List prompts with pagination |
+| `prompts/get` | Get prompt with arguments |
+| `tasks/status` | Get task status |
+| `tasks/cancel` | Cancel running task |
+| `completion/complete` | Auto-complete arguments |
+
+### Security Module (`@claude-flow/security`)
+
+| Feature | CVE/Issue | Description |
+|---------|-----------|-------------|
+| **Password Hashing** | CVE-2 | Secure bcrypt with 12+ rounds |
+| **Credential Generation** | CVE-3 | Cryptographically secure API keys |
+| **Safe Command Execution** | HIGH-1 | Allowlist-based command execution |
+| **Path Validation** | HIGH-2 | Path traversal and symlink protection |
+| **Input Validation** | General | Zod-based schema validation |
+| **Token Generation** | General | HMAC-signed secure tokens |
+| **HTML Sanitization** | XSS | Script and injection prevention |
+
+### Security Validation Schemas
+
+| Schema | Purpose |
+|--------|---------|
+| `SafeStringSchema` | Basic safe string with length limits |
+| `IdentifierSchema` | Alphanumeric identifiers |
+| `FilenameSchema` | Safe filenames |
+| `EmailSchema` | Email addresses |
+| `PasswordSchema` | Secure passwords (8-72 chars) |
+| `UUIDSchema` | UUID v4 format |
+| `HttpsUrlSchema` | HTTPS URLs only |
+| `SpawnAgentSchema` | Agent spawn requests |
+| `TaskInputSchema` | Task definitions |
+
+### Hooks System (`@claude-flow/hooks`)
+
+| Component | Description | Performance |
+|-----------|-------------|-------------|
+| **ReasoningBank** | Pattern storage with HNSW indexing | 150x faster retrieval |
+| **GuidanceProvider** | Context-aware development guidance | Real-time suggestions |
+| **PatternLearning** | Automatic strategy extraction | Continuous improvement |
+| **QualityTracking** | Success/failure rate per pattern | Performance metrics |
+| **DomainDetection** | Auto-categorization of patterns | Security, testing, etc. |
+| **AgentRouting** | Task-to-agent optimization | Historical performance |
+| **Consolidation** | Prune low-quality, promote high-quality | Memory optimization |
+
+### Hook Lifecycle Events
+
+| Phase | Hooks | Purpose |
+|-------|-------|---------|
+| **Pre-Edit** | `pre-edit` | Context gathering, security checks |
+| **Post-Edit** | `post-edit` | Outcome recording, pattern learning |
+| **Pre-Command** | `pre-command` | Risk assessment, validation |
+| **Post-Command** | `post-command` | Success/failure tracking |
+| **Pre-Task** | `pre-task` | Setup, resource allocation |
+| **Post-Task** | `post-task` | Cleanup, learning |
+| **Session** | `session-end`, `session-restore` | State management |
+
+### V3 Statusline (`@claude-flow/hooks`)
+
+Real-time development status display for Claude Code integration showing DDD progress, swarm activity, security status, and system metrics.
+
+**Output Format:**
+```
+▊ Claude Flow V3 ● ruvnet  │  ⎇ v3  │  Opus 4.5
+─────────────────────────────────────────────────────
+🏗️  DDD Domains    [●●●●●]  5/5    ⚡ 1.0x → 2.49x-7.47x
+🤖 Swarm  ◉ [58/15]  👥 0    🟢 CVE 3/3    💾 22282MB    📂  47%    🧠  10%
+🔧 Architecture    DDD ● 98%  │  Security ●CLEAN  │  Memory ●AgentDB  │  Integration ●
 ```
 
----
+| Indicator | Description | Values |
+|-----------|-------------|--------|
+| `▊ Claude Flow V3` | Project header | Always shown |
+| `● ruvnet` | GitHub user (via `gh` CLI) | Dynamic |
+| `⎇ v3` | Current git branch | Dynamic |
+| `Opus 4.5` | Claude model name | From Claude Code |
+| `[●●●●●]` | DDD domain progress bar | 0-5 domains |
+| `⚡ 1.0x → 2.49x-7.47x` | Performance speedup target | Current → Target |
+| `◉/○` | Swarm coordination status | Active/Inactive |
+| `[58/15]` | Active agents / max agents | Process count |
+| `👥 0` | Sub-agents spawned | Task tool agents |
+| `🟢 CVE 3/3` | Security CVE remediation | Fixed/Total |
+| `💾 22282MB` | Memory usage (Node.js processes) | Real-time |
+| `📂 47%` | Context window usage | From Claude Code |
+| `🧠 10%` | Intelligence score (patterns learned) | 0-100% |
+| `DDD ● 98%` | Domain-Driven Design progress | Percentage |
+| `Security ●CLEAN` | Security audit status | CLEAN/PENDING/FAILED |
+| `Memory ●AgentDB` | Memory backend in use | AgentDB/SQLite/Hybrid |
+| `Integration ●` | agentic-flow integration status | Active/Inactive |
+
+**Usage:**
+```bash
+# V3 statusline (Node.js)
+node v3/@claude-flow/hooks/bin/statusline.js
 
-### `mcp` - MCP Server Management
+# JSON output for scripting
+node v3/@claude-flow/hooks/bin/statusline.js --json
 
-Model Context Protocol server control and tool execution.
+# Compact JSON (single line)
+node v3/@claude-flow/hooks/bin/statusline.js --compact
 
-```bash
-claude-flow mcp <subcommand> [options]
+# Help
+node v3/@claude-flow/hooks/bin/statusline.js --help
 ```
 
-#### Subcommands
+**Claude Code Integration:**
 
-| Subcommand | Description |
-|------------|-------------|
-| `start` | Start MCP server with specified transport |
-| `stop` | Stop MCP server (graceful or forced) |
-| `status` | Show MCP server status and metrics |
-| `health` | Check MCP server health |
-| `restart` | Restart MCP server |
-| `tools` | List available MCP tools by category |
-| `toggle` | Enable or disable specific tools |
-| `exec` | Execute an MCP tool directly |
-| `logs` | Show MCP server logs |
+Add to `.claude/settings.json`:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node v3/@claude-flow/hooks/bin/statusline.js"
+  }
+}
+```
 
-#### Transport Types
+**Data Sources:**
+- `.claude-flow/metrics/v3-progress.json` - DDD domain progress
+- `.claude-flow/metrics/swarm-activity.json` - Active agent counts
+- `.claude-flow/security/audit-status.json` - CVE remediation status
+- `.claude-flow/learning/patterns.db` - Intelligence score (pattern count)
+- Process detection via `ps aux` - Real-time memory and agent counts
+- Git branch via `git branch --show-current`
+- GitHub user via `gh api user`
 
-| Transport | Description | Use Case |
-|-----------|-------------|----------|
-| `stdio` | Standard I/O (default) | Claude Code integration |
-| `http` | HTTP REST API | Web integrations, remote access |
-| `websocket` | WebSocket connection | Real-time bidirectional |
+### Background Daemons
 
-#### Tool Categories
+#### V3 Node.js Worker Daemon (Recommended)
 
-| Category | Description | Tool Count |
-|----------|-------------|------------|
-| `agent` | Agent lifecycle management | 4 |
-| `swarm` | Swarm coordination | 3 |
-| `memory` | Memory operations | 3 |
-| `config` | Configuration | 3 |
-| `hooks` | Hook execution | 9 |
-| `system` | System operations | 3 |
+Cross-platform TypeScript-based daemon service with auto-scheduling:
 
-#### Examples
+| Worker | Interval | Priority | Description |
+|--------|----------|----------|-------------|
+| `map` | 5min | normal | Codebase structure mapping |
+| `audit` | 10min | critical | Security vulnerability scanning |
+| `optimize` | 15min | high | Performance optimization |
+| `consolidate` | 30min | low | Memory consolidation |
+| `testgaps` | 20min | normal | Test coverage analysis |
 
+**Commands:**
 ```bash
-# Start with stdio (default)
-claude-flow mcp start
-
-# Start HTTP server on port 8080
-claude-flow mcp start -t http -p 8080
-
-# Start as background daemon
-claude-flow mcp start -d
-
-# Check server status
-claude-flow mcp status
-
-# Health check
-claude-flow mcp health
+# Start daemon (auto-runs on SessionStart hooks)
+npx claude-flow@v3alpha daemon start
 
-# List all tools
-claude-flow mcp tools
+# Check status with worker history
+npx claude-flow@v3alpha daemon status
 
-# List tools by category
-claude-flow mcp tools -c memory
+# Manually trigger a worker
+npx claude-flow@v3alpha daemon trigger map
 
-# Execute a tool
-claude-flow mcp exec -t swarm/init -p '{"topology":"mesh"}'
+# Enable/disable workers
+npx claude-flow@v3alpha daemon enable map audit optimize
 
-# View logs
-claude-flow mcp logs -n 50 -f
-
-# Restart server
-claude-flow mcp restart
-
-# Stop server
-claude-flow mcp stop
+# Stop daemon
+npx claude-flow@v3alpha daemon stop
 ```
 
----
-
-### `task` - Task Management
-
-Create, assign, and manage tasks across agents.
-
-```bash
-claude-flow task <subcommand> [options]
+**Daemon Status Output:**
+```
++-- Worker Daemon ---+
+| Status: ● RUNNING  |
+| PID: 12345         |
+| Workers Enabled: 5 |
+| Max Concurrent: 3  |
++--------------------+
+
+Worker Status
++-------------+----+----------+------+---------+----------+----------+
+| Worker      | On | Status   | Runs | Success | Last Run | Next Run |
++-------------+----+----------+------+---------+----------+----------+
+| map         | ✓  | idle     | 12   | 100%    | 2m ago   | in 3m    |
+| audit       | ✓  | idle     | 6    | 100%    | 5m ago   | in 5m    |
+| optimize    | ✓  | running  | 4    | 100%    | now      | -        |
+| consolidate | ✓  | idle     | 2    | 100%    | 15m ago  | in 15m   |
+| testgaps    | ✓  | idle     | 3    | 100%    | 8m ago   | in 12m   |
++-------------+----+----------+------+---------+----------+----------+
 ```
 
-#### Subcommands
+#### Legacy Shell Daemons (V2)
 
-| Subcommand | Description |
-|------------|-------------|
-| `create` | Create a new task with priority and dependencies |
-| `list` | List tasks with status filtering |
-| `status` | Show detailed task status |
-| `cancel` | Cancel a pending or running task |
-| `assign` | Assign task to specific agent |
-| `retry` | Retry a failed task |
+Shell-based daemons for monitoring (Linux/macOS only):
 
-#### Examples
+| Daemon | Interval | Purpose | Output |
+|--------|----------|---------|--------|
+| **Swarm Monitor** | 3s | Process detection, agent counting | `swarm-activity.json` |
+| **Metrics Daemon** | 30s | V3 progress sync, SQLite metrics | `metrics.db` |
 
+**Commands:**
 ```bash
-# Create a task
-claude-flow task create "Implement user authentication" -p high
+# Start all daemons
+.claude/helpers/daemon-manager.sh start 3 5
 
-# Create task with dependencies
-claude-flow task create "Write tests" --depends-on task-001
+# Check daemon status
+.claude/helpers/daemon-manager.sh status
 
-# List all tasks
-claude-flow task list
+# Stop all daemons
+.claude/helpers/daemon-manager.sh stop
+```
 
-# List pending tasks
-claude-flow task list -s pending
+### Worker Manager (7 Scheduled Workers)
 
-# Get task status
-claude-flow task status task-001
+| Worker | Interval | Purpose |
+|--------|----------|---------|
+| `perf` | 5 min | Performance benchmarks |
+| `health` | 5 min | Disk, memory, CPU monitoring |
+| `patterns` | 15 min | Pattern dedup & pruning |
+| `ddd` | 10 min | DDD progress tracking |
+| `adr` | 15 min | ADR compliance checking |
+| `security` | 30 min | Security vulnerability scans |
+| `learning` | 30 min | Learning pattern optimization |
 
-# Assign to agent
-claude-flow task assign task-001 --agent coder-001
+**Commands:**
+```bash
+# Start worker manager
+.claude/helpers/worker-manager.sh start 60
 
-# Cancel task
-claude-flow task cancel task-001
+# Force run all workers immediately
+.claude/helpers/worker-manager.sh force
 
-# Retry failed task
-claude-flow task retry task-001
+# Check worker status
+.claude/helpers/worker-manager.sh status
 ```
 
 ---
 
-### `session` - Session Management
-
-Manage session state, persistence, and restoration.
+## Use Cases
 
-```bash
-claude-flow session <subcommand> [options]
-```
-
-#### Subcommands
+| Use Case | Command |
+|----------|---------|
+| Code review | `npx claude-flow@v3alpha --agent reviewer --task "Review PR #123"` |
+| Test generation | `npx claude-flow@v3alpha --agent tester --task "Write tests for auth module"` |
+| Security audit | `npx claude-flow@v3alpha --agent security-architect --task "Audit for vulnerabilities"` |
+| Multi-agent swarm | `npx claude-flow@v3alpha swarm init --topology hierarchical` |
+| Route task | `npx claude-flow@v3alpha hooks route "Optimize database queries"` |
+| Performance analysis | `npx claude-flow@v3alpha --agent perf-analyzer --task "Profile API endpoints"` |
+| GitHub PR management | `npx claude-flow@v3alpha --agent pr-manager --task "Review open PRs"` |
+| Check V3 progress | `npx claude-flow@v3alpha progress --detailed` |
+| Sync progress metrics | `npx claude-flow@v3alpha progress sync` |
 
-| Subcommand | Description |
-|------------|-------------|
-| `list` | List all sessions |
-| `save` | Save current session state |
-| `restore` | Restore a previous session |
-| `delete` | Delete a session |
-| `export` | Export session to file |
-| `import` | Import session from file |
-| `current` | Show current session info |
+---
 
-#### Examples
+## Self-Learning Hooks Commands (27 Hooks)
 
+### Core Tool Lifecycle Hooks
 ```bash
-# List all sessions
-claude-flow session list
+# Before/after file editing
+npx claude-flow@v3alpha hooks pre-edit <filePath>
+npx claude-flow@v3alpha hooks post-edit <filePath> --success true --train-patterns
 
-# Save current session
-claude-flow session save --name "feature-auth"
+# Before/after commands
+npx claude-flow@v3alpha hooks pre-command "<command>"
+npx claude-flow@v3alpha hooks post-command "<command>" --success true
 
-# Restore session
-claude-flow session restore session-123
+# Before/after tasks
+npx claude-flow@v3alpha hooks pre-task --description "<task>"
+npx claude-flow@v3alpha hooks post-task --task-id "<id>" --success true
+```
 
-# Export session
-claude-flow session export -o ./session-backup.json
+### Intelligence & Routing Hooks
+```bash
+# Route task to optimal agent using learned patterns
+npx claude-flow@v3alpha hooks route "<task description>" --include-explanation
 
-# Import session
-claude-flow session import -i ./session-backup.json
+# Explain routing decision with transparency
+npx claude-flow@v3alpha hooks explain "<topic>" --depth comprehensive
 
-# Show current session
-claude-flow session current
+# Bootstrap intelligence from repository
+npx claude-flow@v3alpha hooks pretrain --model-type moe --epochs 10
 
-# Delete old session
-claude-flow session delete session-123
-```
+# Generate optimized agent configs from pretrain data
+npx claude-flow@v3alpha hooks build-agents --agent-types coder,tester --config-format yaml
 
----
+# Transfer patterns from another project
+npx claude-flow@v3alpha hooks transfer <sourceProject>
 
-### `config` - Configuration Management
+# Initialize hooks system
+npx claude-flow@v3alpha hooks init
 
-Manage configuration, providers, and settings.
+# View learning metrics dashboard
+npx claude-flow@v3alpha hooks metrics
 
-```bash
-claude-flow config <subcommand> [options]
+# List all registered hooks
+npx claude-flow@v3alpha hooks list
 ```
 
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `init` | Initialize configuration file |
-| `get` | Get configuration value |
-| `set` | Set configuration value |
-| `providers` | Manage LLM provider configurations |
-| `reset` | Reset configuration to defaults |
-| `export` | Export configuration |
-| `import` | Import configuration |
-
-#### Examples
-
+### Session Management Hooks
 ```bash
-# Initialize config
-claude-flow config init
-
-# Get a value
-claude-flow config get memory.backend
-
-# Set a value
-claude-flow config set swarm.topology mesh
+# Start session with context loading
+npx claude-flow@v3alpha hooks session-start --session-id "<id>" --load-context
 
-# Configure providers
-claude-flow config providers --add anthropic --api-key $ANTHROPIC_API_KEY
+# End session with persistence
+npx claude-flow@v3alpha hooks session-end --export-metrics true --persist-patterns
 
-# Reset to defaults
-claude-flow config reset --confirm
+# Restore previous session context
+npx claude-flow@v3alpha hooks session-restore --session-id "<id>"
 
-# Export config
-claude-flow config export -o ./config-backup.json
-
-# Import config
-claude-flow config import -i ./config.json
+# Send notifications to swarm
+npx claude-flow@v3alpha hooks notify --message "<message>" --swarm-status
 ```
 
----
-
-### `status` - System Status
-
-Monitor system status with real-time updates.
-
+### RuVector Intelligence Hooks (Reinforcement Learning)
 ```bash
-claude-flow status [subcommand] [options]
-```
+# Trajectory-based learning (4-step pipeline: RETRIEVE, JUDGE, DISTILL, CONSOLIDATE)
+npx claude-flow@v3alpha hooks intelligence trajectory-start --session "<session>"
+npx claude-flow@v3alpha hooks intelligence trajectory-step --action "<action>" --reward 0.9
+npx claude-flow@v3alpha hooks intelligence trajectory-end --verdict success
 
-#### Subcommands
+# Pattern storage with HNSW indexing (150x faster search)
+npx claude-flow@v3alpha hooks intelligence pattern-store --pattern "<pattern>" --embedding "[...]"
+npx claude-flow@v3alpha hooks intelligence pattern-search --query "<query>" --limit 10
 
-| Subcommand | Description |
-|------------|-------------|
-| `agents` | Show status of all agents |
-| `tasks` | Show status of all tasks |
-| `memory` | Show memory system status |
+# Learning stats and attention focus
+npx claude-flow@v3alpha hooks intelligence stats
+npx claude-flow@v3alpha hooks intelligence learn --experience '{"type":"success"}'
+npx claude-flow@v3alpha hooks intelligence attention --focus "<task>"
 
-#### Options
+# Full intelligence system (SONA, MoE, HNSW, EWC++, Flash Attention)
+npx claude-flow@v3alpha hooks intelligence
+npx claude-flow@v3alpha hooks intelligence reset --confirm
 
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--watch` | `-w` | Watch mode with auto-refresh | `false` |
-| `--interval` | `-i` | Refresh interval in seconds | `5` |
+# ═══════════════════════════════════════════════════════════════
+# Background Worker Commands (12 workers for analysis/optimization)
+# ═══════════════════════════════════════════════════════════════
 
-#### Examples
+# List all available workers
+npx claude-flow@v3alpha hooks worker list
 
-```bash
-# Show all status
-claude-flow status
+# Detect triggers from prompt text
+npx claude-flow@v3alpha hooks worker detect --prompt "optimize performance"
 
-# Watch mode with 2s refresh
-claude-flow status --watch -i 2
+# Auto-dispatch workers when triggers match (confidence ≥0.6)
+npx claude-flow@v3alpha hooks worker detect --prompt "deep dive into auth" --auto-dispatch --min-confidence 0.6
 
-# Agent status only
-claude-flow status agents
+# Manually dispatch a worker (ultralearn, optimize, audit, map, deepdive, document, refactor, benchmark, testgaps, etc.)
+npx claude-flow@v3alpha hooks worker dispatch --trigger refactor --context "auth module"
 
-# Task status
-claude-flow status tasks
+# Check worker status
+npx claude-flow@v3alpha hooks worker status
 
-# Memory status
-claude-flow status memory
+# Cancel a running worker
+npx claude-flow@v3alpha hooks worker cancel --id worker_refactor_1_abc123
 ```
 
----
-
-### `workflow` - Workflow Management
-
-Execute and manage automated workflows.
-
+### Progress Tracking Hooks
 ```bash
-claude-flow workflow <subcommand> [options]
-```
-
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `run` | Execute a workflow |
-| `validate` | Validate workflow definition |
-| `list` | List available workflows |
-| `status` | Show workflow execution status |
-| `stop` | Stop running workflow |
-| `template` | Manage workflow templates (list, show, create) |
+# Check V3 implementation progress
+npx claude-flow@v3alpha hooks progress
 
-#### Examples
+# Detailed breakdown by category (CLI, MCP, Hooks, Packages, DDD)
+npx claude-flow@v3alpha hooks progress --detailed
 
-```bash
-# Run a workflow
-claude-flow workflow run ./workflows/deploy.yaml
+# Sync progress and persist to file
+npx claude-flow@v3alpha hooks progress --sync
 
-# Validate workflow
-claude-flow workflow validate ./workflows/deploy.yaml
+# Get human-readable summary
+npx claude-flow@v3alpha hooks progress --summary
 
-# List workflows
-claude-flow workflow list
+# JSON output for scripting
+npx claude-flow@v3alpha progress --json
+```
 
-# Check workflow status
-claude-flow workflow status workflow-123
+---
 
-# Stop workflow
-claude-flow workflow stop workflow-123
+## Architecture
 
-# List templates
-claude-flow workflow template list
+### V3 Module Structure
 
-# Create from template
-claude-flow workflow template create --from deploy-standard
 ```
+v3/
+├── @claude-flow/hooks      # Event-driven lifecycle hooks + ReasoningBank
+├── @claude-flow/memory     # AgentDB unification module
+├── @claude-flow/security   # CVE remediation & patterns
+├── @claude-flow/swarm      # 15-agent coordination
+├── @claude-flow/plugins    # RuVector WASM plugins
+├── @claude-flow/cli        # CLI modernization
+├── @claude-flow/neural     # SONA learning integration
+├── @claude-flow/testing    # TDD London School framework
+├── @claude-flow/deployment # Release & CI/CD
+└── @claude-flow/shared     # Shared utilities & types
+```
+ 
+### Performance Metrics
+
+| Metric | Measured |
+|--------|----------|
+| Swarm task execution | 100% success rate (7/7 strategies) |
+| Average task duration | 0.15-0.30 seconds |
+| Memory usage per agent | 128-320 MB |
+| CPU utilization | 15-30% per agent |
+| Parallel agent capacity | Unlimited (resource-dependent) |
+
+### Topology Performance
+
+| Topology | Agents | Execution Time | Memory |
+|----------|--------|----------------|--------|
+| Centralized | 2-3 | 0.14-0.20s | 180-256 MB |
+| Distributed | 4-5 | 0.10-0.12s | 128-160 MB |
+| Hierarchical | 6 | 0.20s | 256 MB |
+| Mesh | 4 | 0.15s | 192 MB |
+| Hybrid | 7 | 0.18s | 320 MB |
 
 ---
 
-### `hooks` - Self-Learning Hooks
+## Cross-Platform Support
 
-Advanced self-learning hooks with 17 subcommands for neural pattern recognition and background worker management.
+### Windows (PowerShell)
 
-```bash
-claude-flow hooks <subcommand> [options]
+```powershell
+npx @claude-flow/security@latest audit --platform windows
+$env:CLAUDE_FLOW_MODE = "integration"
 ```
 
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `pre-edit` | Execute before file edit (get context, agent suggestions) |
-| `post-edit` | Execute after file edit (record outcome for learning) |
-| `pre-command` | Execute before command (risk assessment) |
-| `post-command` | Execute after command (record outcome) |
-| `pre-task` | Execute before task (setup, validation) |
-| `post-task` | Execute after task (cleanup, learning) |
-| `session-end` | Execute on session end (save state) |
-| `session-restore` | Execute on session restore (load state) |
-| `route` | Route task to optimal agent using learned patterns |
-| `explain` | Explain routing decision with transparency |
-| `pretrain` | Bootstrap intelligence from repository |
-| `build-agents` | Generate optimized agent configs from pretrain data |
-| `metrics` | View learning metrics dashboard |
-| `transfer` | Transfer patterns from another project |
-| `list` | List all registered hooks |
-| `intelligence` | RuVector intelligence (SONA, MoE, HNSW) |
-| `worker` | Background worker management (12 workers) |
-
-#### Learning Pipeline
-
-The hooks system implements a 4-step learning pipeline:
-
-1. **RETRIEVE** - Top-k memory injection with MMR diversity
-2. **JUDGE** - LLM-as-judge trajectory evaluation
-3. **DISTILL** - Extract strategy memories from trajectories
-4. **CONSOLIDATE** - Dedup, detect contradictions, prune old patterns
-
-#### Examples
+### macOS (Bash/Zsh)
 
 ```bash
-# Pre-edit hook (get context and suggestions)
-claude-flow hooks pre-edit ./src/auth/login.ts
-
-# Post-edit hook (record success for learning)
-claude-flow hooks post-edit ./src/auth/login.ts --success true
-
-# Pre-command risk assessment
-claude-flow hooks pre-command "rm -rf ./node_modules"
-
-# Route task to optimal agent
-claude-flow hooks route "Implement OAuth2 authentication"
-
-# Explain routing decision
-claude-flow hooks explain "Implement OAuth2 authentication"
-
-# Bootstrap from repository
-claude-flow hooks pretrain
-
-# Build optimized agent configs
-claude-flow hooks build-agents --focus "security"
-
-# View learning metrics
-claude-flow hooks metrics
-
-# Transfer patterns from another project
-claude-flow hooks transfer ../other-project
-
-# View intelligence status (SONA, MoE, HNSW)
-claude-flow hooks intelligence
+npx @claude-flow/security@latest audit --platform darwin
+export CLAUDE_FLOW_SECURITY_MODE="strict"
 ```
 
-#### Worker Subcommands
-
-The `hooks worker` command manages 12 background workers for analysis and optimization tasks.
-
-| Worker | Priority | Est. Time | Description |
-|--------|----------|-----------|-------------|
-| `ultralearn` | normal | 60s | Deep knowledge acquisition and learning |
-| `optimize` | high | 30s | Performance optimization and tuning |
-| `consolidate` | low | 20s | Memory consolidation and cleanup |
-| `predict` | normal | 15s | Predictive preloading and anticipation |
-| `audit` | critical | 45s | Security analysis and vulnerability scanning |
-| `map` | normal | 30s | Codebase mapping and architecture analysis |
-| `preload` | low | 10s | Resource preloading and cache warming |
-| `deepdive` | normal | 60s | Deep code analysis and examination |
-| `document` | normal | 45s | Auto-documentation generation |
-| `refactor` | normal | 30s | Code refactoring suggestions |
-| `benchmark` | normal | 60s | Performance benchmarking |
-| `testgaps` | normal | 30s | Test coverage analysis |
-
-##### Worker Commands
+### Linux (Bash)
 
 ```bash
-# List all available workers
-claude-flow hooks worker list
-
-# Detect triggers from prompt text
-claude-flow hooks worker detect --prompt "optimize performance"
-
-# Auto-dispatch workers when triggers match (min confidence 0.6)
-claude-flow hooks worker detect --prompt "deep dive into auth" --auto-dispatch --min-confidence 0.6
-
-# Manually dispatch a worker
-claude-flow hooks worker dispatch --trigger refactor --context "auth module"
-
-# Check worker status
-claude-flow hooks worker status
-
-# Cancel a running worker
-claude-flow hooks worker cancel --id worker_refactor_1_abc123
+npx @claude-flow/security@latest audit --platform linux
+export CLAUDE_FLOW_MEMORY_PATH="./data"
 ```
 
-##### Performance Targets
-
-| Metric | Target |
-|--------|--------|
-| Trigger detection | <5ms |
-| Worker spawn | <50ms |
-| Max concurrent | 10 |
+---
 
-##### UserPromptSubmit Integration
+## Environment Variables
 
-Workers are automatically triggered via the `UserPromptSubmit` hook when prompt patterns match worker triggers with confidence ≥0.6.
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_FLOW_MODE` | Operation mode (`development`, `production`, `integration`) | `development` |
+| `CLAUDE_FLOW_MEMORY_PATH` | Directory for persistent memory storage | `./data` |
+| `CLAUDE_FLOW_SECURITY_MODE` | Security level (`strict`, `standard`, `permissive`) | `standard` |
+| `CLAUDE_FLOW_LOG_LEVEL` | Logging verbosity (`debug`, `info`, `warn`, `error`) | `info` |
+| `CLAUDE_FLOW_MAX_AGENTS` | Default concurrent agent limit (increase for more parallelism) | `15` |
+| `CLAUDE_FLOW_TOPOLOGY` | Default swarm topology | `hierarchical` |
+| `CLAUDE_FLOW_HNSW_M` | HNSW index M parameter (connectivity) | `16` |
+| `CLAUDE_FLOW_HNSW_EF` | HNSW search ef parameter (accuracy) | `200` |
+| `CLAUDE_FLOW_EMBEDDING_DIM` | Vector embedding dimensions | `384` |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude integration | - |
 
 ---
 
-### `hive-mind` - Consensus Coordination
+## Troubleshooting
 
-Queen-led Byzantine fault-tolerant multi-agent coordination.
+### Common Issues
 
+**MCP server won't start**
 ```bash
-claude-flow hive-mind <subcommand> [options]
+# Check if port is in use
+lsof -i :3000
+# Kill existing process
+kill -9 <PID>
+# Restart MCP server
+npx claude-flow@v3alpha mcp start
 ```
 
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `init` | Initialize hive-mind with topology and consensus strategy |
-| `spawn` | Spawn agents in the hive (queen, worker, specialist) |
-| `status` | Show hive-mind status with consensus health |
-| `task` | Submit task to hive-mind for collaborative execution |
-| `optimize-memory` | Optimize collective memory (distill, compress) |
-| `shutdown` | Gracefully shutdown hive-mind |
-
-#### Topologies
-
-| Topology | Description |
-|----------|-------------|
-| `hierarchical` | Queen controls workers directly |
-| `mesh` | Fully connected peer network |
-| `hierarchical-mesh` | Hybrid: Queen + mesh workers |
-| `adaptive` | Dynamic topology based on load |
-
-#### Consensus Strategies
-
-| Strategy | Description | Fault Tolerance |
-|----------|-------------|-----------------|
-| `byzantine` | Byzantine fault-tolerant (BFT) | Tolerates f < n/3 faulty nodes |
-| `raft` | Leader-based consensus | Tolerates f < n/2 failures |
-| `gossip` | Epidemic protocol for eventual consistency | High partition tolerance |
-| `crdt` | Conflict-free replicated data types | Strong eventual consistency |
-| `quorum` | Configurable quorum-based | Flexible fault tolerance |
-
-#### Examples
-
+**Agent spawn failures**
 ```bash
-# Initialize with defaults
-claude-flow hive-mind init
-
-# Initialize with Byzantine consensus
-claude-flow hive-mind init -t hierarchical-mesh -c byzantine --agents 15
-
-# Spawn queen
-claude-flow hive-mind spawn --role queen --name hive-queen
-
-# Spawn workers
-claude-flow hive-mind spawn --role worker --count 5
-
-# Spawn specialist
-claude-flow hive-mind spawn --role specialist --specialty security
-
-# Submit task for collaborative execution
-claude-flow hive-mind task "Implement secure API endpoints" --consensus-required
-
-# Check hive status
-claude-flow hive-mind status --detailed
-
-# Optimize collective memory
-claude-flow hive-mind optimize-memory --distill --compress
-
-# Graceful shutdown
-claude-flow hive-mind shutdown --save-state
+# Check available memory
+free -m
+# Reduce max agents if memory constrained
+export CLAUDE_FLOW_MAX_AGENTS=5
 ```
 
----
-
-### `migrate` - V2 to V3 Migration
-
-Migration tools for transitioning from V2 to V3.
-
+**Pattern search returning no results**
 ```bash
-claude-flow migrate <subcommand> [options]
+# Verify patterns are stored
+npx claude-flow@v3alpha hooks metrics
+# Re-run pretraining if empty
+npx claude-flow@v3alpha hooks pretrain
 ```
 
-#### Subcommands
-
-| Subcommand | Description |
-|------------|-------------|
-| `status` | Check migration status and pending items |
-| `run` | Execute migration (with dry-run option) |
-| `verify` | Verify migration integrity |
-| `rollback` | Rollback to previous version |
-| `breaking` | Show V3 breaking changes |
-
-#### Migration Targets
-
-| Target | Description |
-|--------|-------------|
-| `config` | Migrate configuration files |
-| `memory` | Migrate memory/database content |
-| `agents` | Migrate agent configurations |
-| `hooks` | Migrate hook definitions |
-| `workflows` | Migrate workflow definitions |
-| `all` | Full migration |
-
-#### Examples
+**Windows path issues**
+```powershell
+# Use forward slashes or escape backslashes
+$env:CLAUDE_FLOW_MEMORY_PATH = "./data"
+# Or use absolute path
+$env:CLAUDE_FLOW_MEMORY_PATH = "C:/Users/name/claude-flow/data"
+```
 
+**Permission denied errors**
 ```bash
-# Check migration status
-claude-flow migrate status
-
-# Preview migration (dry run)
-claude-flow migrate run --dry-run
-
-# Run full migration with backup
-claude-flow migrate run -t all --backup
-
-# Migrate specific component
-claude-flow migrate run -t memory
-
-# Verify migration
-claude-flow migrate verify
-
-# Auto-fix issues
-claude-flow migrate verify --fix
-
-# Show breaking changes
-claude-flow migrate breaking
+# Fix npm permissions (Linux/macOS)
+sudo chown -R $(whoami) ~/.npm
+# Or use nvm to manage Node.js
+```
 
-# Rollback
-claude-flow migrate rollback --backup-id backup-1704369600
+**High memory usage**
+```bash
+# Enable garbage collection
+node --expose-gc node_modules/.bin/claude-flow
+# Reduce HNSW parameters for lower memory
+export CLAUDE_FLOW_HNSW_M=8
+export CLAUDE_FLOW_HNSW_EF=100
 ```
 
 ---
 
-## Global Options
-
-All commands support these global options:
-
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--help` | `-h` | Show help information | |
-| `--version` | `-V` | Show version number | |
-| `--verbose` | `-v` | Enable verbose output | `false` |
-| `--quiet` | `-q` | Suppress non-essential output | `false` |
-| `--config` | `-c` | Path to configuration file | `./claude-flow.config.json` |
-| `--format` | `-f` | Output format (text, json, table) | `text` |
-| `--no-color` | | Disable colored output | `false` |
-| `--interactive` | `-i` | Enable interactive mode | `true` (if TTY) |
-
-## Programmatic API
-
-### CommandParser
-
-```typescript
-import { CommandParser, OutputFormatter } from '@claude-flow/cli';
-
-// Create a parser instance
-const parser = new CommandParser();
-
-// Register a command
-parser.registerCommand({
-  name: 'mycommand',
-  description: 'My custom command',
-  options: [
-    {
-      name: 'type',
-      short: 't',
-      description: 'Operation type',
-      type: 'string',
-      choices: ['a', 'b', 'c'],
-      default: 'a'
-    }
-  ],
-  subcommands: [
-    { name: 'sub1', description: 'First subcommand' },
-    { name: 'sub2', description: 'Second subcommand' }
-  ],
-  action: async (ctx) => {
-    // Command implementation
-    return { success: true };
-  }
-});
+## Migration Guide (V2 → V3)
 
-// Parse arguments
-const result = parser.parse(process.argv.slice(2));
+### Breaking Changes
 
-// Validate flags
-const errors = parser.validateFlags(result.flags, result.command);
+1. **Module Structure**: V3 uses scoped packages (`@claude-flow/*`)
+2. **Memory Backend**: Default changed from JSON to AgentDB with HNSW
+3. **Hooks System**: New ReasoningBank replaces basic pattern storage
+4. **Security**: Stricter input validation enabled by default
 
-// Get all registered commands
-const commands = parser.getAllCommands();
-```
+### Upgrade Steps
 
-### Output Formatting
-
-```typescript
-import { OutputFormatter, output, Progress, Spinner } from '@claude-flow/cli';
-
-// Use the singleton instance
-output.printSuccess('Operation completed');
-output.printError('Something went wrong');
-output.printWarning('Proceed with caution');
-output.printInfo('FYI: This is informational');
-
-// Or create a custom formatter
-const formatter = new OutputFormatter({ color: true });
-
-// Color methods
-formatter.success('Green text');
-formatter.error('Red text');
-formatter.warning('Yellow text');
-formatter.bold('Bold text');
-formatter.dim('Dimmed text');
-formatter.highlight('Highlighted text');
-
-// Structured output
-output.printTable({
-  columns: [
-    { key: 'name', header: 'Name', width: 20 },
-    { key: 'status', header: 'Status', width: 10, align: 'right' }
-  ],
-  data: [
-    { name: 'Agent 1', status: 'active' },
-    { name: 'Agent 2', status: 'idle' }
-  ]
-});
-
-output.printJson({ key: 'value' });
-output.printList(['Item 1', 'Item 2', 'Item 3']);
-output.printBox('Content here', 'Title');
-output.progressBar(50, 100, 40); // 50% of 100, width 40
-
-// Progress indication
-const spinner = new Spinner('Loading...');
-spinner.start();
-// ... do work
-spinner.succeed('Completed');
-
-const progress = new Progress({ total: 100 });
-progress.update(50); // 50%
-progress.finish();
-```
+```bash
+# 1. Backup existing data
+cp -r ./data ./data-backup-v2
 
-### Interactive Prompts
-
-```typescript
-import { text, select, confirm, input, multiSelect } from '@claude-flow/cli';
-
-// Text input
-const name = await text('Enter your name:');
-
-// Selection
-const choice = await select({
-  message: 'Choose option:',
-  options: [
-    { label: 'Option A', value: 'A', hint: 'First option' },
-    { label: 'Option B', value: 'B', hint: 'Second option' },
-  ],
-  default: 'A'
-});
-
-// Confirmation
-const confirmed = await confirm({
-  message: 'Continue?',
-  default: false
-});
-
-// Input with validation
-const email = await input({
-  message: 'Enter email:',
-  validate: (v) => v.includes('@') || 'Invalid email'
-});
-
-// Multi-select
-const features = await multiSelect({
-  message: 'Select features:',
-  options: [
-    { label: 'Feature A', value: 'a' },
-    { label: 'Feature B', value: 'b' },
-    { label: 'Feature C', value: 'c' },
-  ]
-});
-```
+# 2. Update to V3
+npm install claude-flow@latest
 
-## TypeScript Types
-
-```typescript
-import type {
-  // Command types
-  Command,
-  CommandOption,
-  CommandContext,
-  CommandResult,
-
-  // Parser types
-  ParseResult,
-  ParsedFlags,
-  ParserOptions,
-
-  // Config types
-  V3Config,
-  ProviderConfig,
-  SwarmConfig,
-  MemoryConfig,
-
-  // Output types
-  TableColumn,
-  TableOptions,
-  SpinnerOptions,
-  ProgressOptions,
-
-  // Prompt types
-  SelectOption,
-  InputOptions,
-  ConfirmOptions,
-} from '@claude-flow/cli';
+# 3. Run migration
+npx claude-flow@v3alpha migrate --from v2
+
+# 4. Verify installation
+npx claude-flow@v3alpha --version
+npx claude-flow@v3alpha hooks metrics
 ```
 
-## Environment Variables
+### Configuration Changes
 
 ```bash
-# Configuration
-CLAUDE_FLOW_CONFIG=./claude-flow.config.json
-CLAUDE_FLOW_LOG_LEVEL=info
-
-# Provider API Keys
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-GOOGLE_API_KEY=...
-
-# MCP Server
-CLAUDE_FLOW_MCP_PORT=3000
-CLAUDE_FLOW_MCP_HOST=localhost
-CLAUDE_FLOW_MCP_TRANSPORT=stdio
-
-# Memory
-CLAUDE_FLOW_MEMORY_BACKEND=hybrid
-CLAUDE_FLOW_MEMORY_PATH=./data/memory
-```
+# V2 (deprecated)
+npx claude-flow init --mode basic
 
-## Performance Targets
+# V3 (new)
+npx claude-flow@v3alpha init
+npx claude-flow@v3alpha hooks pretrain  # Bootstrap learning
+```
 
-The CLI is optimized for V3 performance targets:
+### API Changes
 
-| Metric | Target | Description |
-|--------|--------|-------------|
-| Startup | <500ms | CLI initialization time |
-| Command parsing | <5ms | Argument parsing time |
-| MCP tool execution | <100ms | Tool call overhead |
-| Memory search | 150x-12,500x faster | With HNSW indexing |
-| SONA adaptation | <0.05ms | Neural learning overhead |
+| V2 API | V3 API |
+|--------|--------|
+| `claude-flow start` | `claude-flow mcp start` |
+| `--pattern-store` | `--memory-backend agentdb` |
+| `hooks record` | `hooks post-edit --success` |
+| `swarm create` | `swarm init --topology` |
 
-## Related Packages
+---
 
-- [@claude-flow/shared](../shared) - Shared types and utilities
-- [@claude-flow/swarm](../swarm) - Swarm coordination module
-- [@claude-flow/memory](../memory) - AgentDB memory system
-- [@claude-flow/mcp](../mcp) - MCP server implementation
-- [@claude-flow/hooks](../hooks) - Self-learning hooks system
-- [@claude-flow/neural](../neural) - SONA neural learning
+## Documentation
+
+### V3 Module Documentation
+
+| Module | Description | Docs |
+|--------|-------------|------|
+| `@claude-flow/plugins` | Plugin SDK with workers, hooks, providers, security | [README](./v3/@claude-flow/plugins/README.md) |
+| `@claude-flow/hooks` | Event-driven lifecycle hooks + ReasoningBank | [Source](./v3/@claude-flow/hooks/) |
+| `@claude-flow/memory` | AgentDB unification with HNSW indexing | [Source](./v3/@claude-flow/memory/) |
+| `@claude-flow/security` | CVE remediation & security patterns | [Source](./v3/@claude-flow/security/) |
+| `@claude-flow/swarm` | 15-agent coordination engine | [Source](./v3/@claude-flow/swarm/) |
+| `@claude-flow/cli` | CLI modernization | [Source](./v3/@claude-flow/cli/) |
+| `@claude-flow/neural` | SONA learning integration | [Source](./v3/@claude-flow/neural/) |
+| `@claude-flow/testing` | TDD London School framework | [Source](./v3/@claude-flow/testing/) |
+| `@claude-flow/mcp` | MCP server & tools | [Source](./v3/@claude-flow/mcp/) |
+| `@claude-flow/embeddings` | Vector embedding providers | [Source](./v3/@claude-flow/embeddings/) |
+| `@claude-flow/providers` | LLM provider integrations | [Source](./v3/@claude-flow/providers/) |
+| `@claude-flow/integration` | agentic-flow@alpha integration | [Source](./v3/@claude-flow/integration/) |
+| `@claude-flow/performance` | Benchmarking & optimization | [Source](./v3/@claude-flow/performance/) |
+| `@claude-flow/deployment` | Release & CI/CD | [Source](./v3/@claude-flow/deployment/) |
+| `@claude-flow/shared` | Shared utilities, types & V3ProgressService | [Source](./v3/@claude-flow/shared/) |
+
+### Additional Resources
+
+- [V2 Documentation](./v2/README.md)
+- [Architecture Decisions (ADRs)](./v3/docs/adr/)
+- [API Reference](./v2/docs/technical/)
+- [Examples](./v2/examples/)
+
+## Support
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues
+- Discord: [Agentics Foundation](https://discord.com/invite/dfxmpwkG2D)
 
 ## License
 
-MIT
+MIT - [RuvNet](https://github.com/ruvnet)