diff --git a/README.md b/README.md
index b8d7d695..58a44f62 100644
--- a/README.md
+++ b/README.md
@@ -534,14 +534,119 @@ Z.AI API (SSE)
 
 **Eviction policy:** When memory exceeds 500 entries, old single-access discoveries are evicted first. Lessons and gotchas are never evicted unless all else fails.
 
+## 🐝 zCode Swarm — Multi-Agent Orchestration
+
+Distributed multi-agent coordination system inspired by [Ruflo](https://github.com/ruvnet/ruflo). Spawns specialized agent swarms that work in parallel — code reviews, security audits, performance analysis, architecture validation, test orchestration, and git operations.
+
+### Architecture
+
+```
+        ┌─────────────────────┐
+        │  SwarmOrchestrator  │
+        │  (main entry point) │
+        └─────────┬───────────┘
+                  │
+    ┌─────────────┼─────────────┐
+    ▼             ▼             ▼
+┌────────┐  ┌──────────┐  ┌──────────┐
+│Neural  │  │Federated │  │Agent     │
+│Network │  │Memory    │  │Market-   │
+│(ML)    │  │(6 NS)    │  │place     │
+└────────┘  └──────────┘  └──────────┘
+                  │
+    ┌─────────────┼─────────────┐
+    ▼             ▼             ▼
+┌──────────┐ ┌──────────┐ ┌──────────┐
+│Hiera-    │ │ Mesh +   │ │ Gossip + │
+│rchical   │ │ CRDT     │ │ Consensus│
+│Queen     │ │ P2P      │ │ BFT      │
+└──────────┘ └──────────┘ └──────────┘
+                  │
+    ┌─────┬─────┬─┴────┬──────┬──────┐
+    ▼     ▼     ▼      ▼      ▼      ▼
+  Code  Perf  Sec   Arch   Test   Git
+ Review Opt   Audit Analy  Orch   Swarm
+```
+
+### 6 Agent Skills
+
+| Skill | ID | What It Does |
+|---|---|---|
+| 🔍 Code Review | `code-review-swarm` | Multi-agent review: security, performance, style, architecture |
+| ⚡ Performance | `performance-optimizer` | Bottleneck detection, N+1 queries, memory leaks, score calculation |
+| 🔒 Security | `security-auditor` | Injection, XSS, auth, data leakage — severity classification |
+| 🏗️ Architecture | `architecture-analyzer` | Coupling/cohesion analysis, SOLID compliance scoring |
+| 🧪 Testing | `test-orchestrator` | Test generation, coverage analysis, execution tracking |
+| 🔄 Git | `git-swarm` | Multi-repo PR analysis, review, branch management |
+
+### 4 Coordination Modes
+
+| Mode | Pattern | Best For |
+|---|---|---|
+| **Hierarchical** | Queen-led | Default — single decision-maker routes tasks |
+| **Mesh** | P2P + CRDT | Decentralized teams, conflict-free replication |
+| **Gossip** | Random propagation | Large networks, eventual consistency |
+| **Consensus** | Byzantine fault-tolerant | Critical decisions, 10% fault tolerance |
+
+### Advanced Features
+
+- **🧠 Neural Network Integration** — ML-based agent recommendation with confidence scoring and real-time learning
+- **📦 Agent Marketplace** — Plugin discovery, install/uninstall, capability-based search
+- **📊 Real-Time Dashboard** — Terminal monitoring with 5s refresh, performance scores, memory stats
+- **📈 Performance Metrics** — CPU/memory tracking, trend analysis, automated recommendations
+- **🧩 Federated Memory** — 6 namespaces (coordination, project-context, patterns, knowledge, session, metrics)
+
+### Quick Start
+
+```bash
+# Verify installation (22 files)
+node verify-swarm.cjs
+
+# Run demo
+node quick-start.cjs
+
+# Configure
+vim .zcode/config/coordinator.yaml
+```
+
+### Configuration (`.zcode/config/coordinator.yaml`)
+
+```yaml
+coordination:
+  mode: hierarchical  # hierarchical | mesh | gossip | consensus
+
+agents:
+  enabled:
+    - code-review-swarm
+    - performance-optimizer
+    - security-auditor
+    - architecture-analyzer
+    - test-orchestrator
+    - git-swarm
+
+neural:
+  enabled: true
+  architecture: multi-layer-perceptron
+  layers: [64, 32, 16, 8]
+
+dashboard:
+  enabled: false  # true for live terminal dashboard
+
+marketplace:
+  enabled: true
+```
+
 ## 📊 Feature Comparison
 
 | Feature | zCode CLI X | Hermes Agent | better-clawd |
 |---|---|---|---|
 | **Agentic** | | | |
 | Autonomous execution | ✅ Full autonomous mode | ✅ Full autonomous mode | ⚠️ Manual step-by-step |
-| Sub-agents | ✅ Multi-agent (swarm) | ✅ delegate_task + batch | ❌ Single agent only |
-| Agent roles | ✅ Code Reviewer, Architect, DevOps | ✅ Agent Registry (10+ roles) | ❌ Fixed single role |
+| Sub-agents | ✅ zCode Swarm (6 skills, 4 modes, ML) | ✅ delegate_task + batch | ❌ Single agent only |
+| Agent roles | ✅ Reviewer, Architect, DevOps, Security, Tester, Git | ✅ Agent Registry (10+ roles) | ❌ Fixed single role |
+| Neural coordination | ✅ ML agent recommendation | ❌ Rule-based only | ❌ None |
+| Agent marketplace | ✅ Plugin discovery + install | ❌ Manual skills | ❌ None |
+| Federated memory | ✅ 6-namespace CRDT-backed | ✅ Cross-session memory | ❌ None |
 | Self-correction loops | ✅ 2 retries + backoff + auto-simplification | ✅ Agent self-correction skill | ❌ None |
 | **Intelligence** | | | |
 | Persistent memory | ✅ JSON-backed, 5 categories, auto-learn | ✅ Cross-session memory | ❌ None |
@@ -583,7 +688,7 @@ Z.AI API (SSE)
 
 ### Summary
 
-- **zCode CLI X** — Lightweight agentic coder focused on Telegram + Z.AI. **Intelligence Routing** — a unified agentic loop that handles streaming and non-streaming through one execution path with tool call accumulation from SSE deltas. Real-time SSE streaming, self-correction loops, persistent self-learning memory with curiosity engine, RTK optimization, and beautiful HTML formatting. Gets smarter with every conversation. Ideal for quick coding tasks via Telegram.
+- **zCode CLI X** — Lightweight agentic coder focused on Telegram + Z.AI. **Intelligence Routing** — a unified agentic loop that handles streaming and non-streaming through one execution path with tool call accumulation from SSE deltas. Real-time SSE streaming, self-correction loops, persistent self-learning memory with curiosity engine, RTK optimization, and beautiful HTML formatting. **zCode Swarm** — distributed multi-agent orchestration with 6 specialized skills (code review, security, performance, architecture, testing, git), 4 coordination modes (hierarchical, mesh, gossip, consensus), neural network-based agent recommendation, federated memory, agent marketplace, and real-time dashboard. Gets smarter with every conversation. Ideal for quick coding tasks via Telegram.
 - **Hermes Agent** — Full-stack AI assistant platform. Best for complex multi-agent workflows, scheduled automation, and cross-platform deployment. 500+ skills, MCP ecosystem, deepest toolset.
 - **better-clawd** — Minimal Claude Code clone. Useful as a lightweight reference but lacks agentic depth.
 
@@ -598,6 +703,7 @@ Z.AI API (SSE)
 - **RTK**: Rust Token Killer (token optimization)
 - **Vosk**: Offline speech recognition (STT, 68MB model, no API key)
 - **ffmpeg**: Audio conversion (OGG → WAV for Vosk)
+- **zCode Swarm**: Multi-agent orchestration (`.zcode/` directory)
 
 ## 🤝 Contributing