Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs: Reorganize documentation structure for better navigation

rUv27e1bc1c9970
diff --git a/README.md b/README.md
index 6fa3cf432f..db30e9afd2 100644
--- a/README.md
+++ b/README.md
@@ -353,29 +353,42 @@ npx claude-flow@alpha memory query "microservices patterns" --reasoningbank
## πŸ“š **Documentation**
-### **Core Documentation**
-- **[Skills Tutorial](./docs/skills-tutorial.md)** - Complete guide to 25 Claude Flow skills with natural language invocation
+### **πŸ“– Core Documentation**
+- **[Documentation Hub](./docs/)** - Complete documentation index with organized structure
+- **[Skills Tutorial](./docs/guides/skills-tutorial.md)** - Complete guide to 25 Claude Flow skills with natural language invocation
- **[Installation Guide](./docs/INSTALLATION.md)** - Setup instructions
-- **[AgentDB Integration](./docs/agentdb/)** - πŸ†• 96x-164x faster vector search (PR #830)
- - [Production Readiness Guide](./docs/agentdb/PRODUCTION_READINESS.md)
- - [Implementation Summary](./docs/agentdb/SWARM_IMPLEMENTATION_COMPLETE.md)
- - [Integration Plan](./docs/AGENTDB_INTEGRATION_PLAN.md)
- **[Memory System Guide](./docs/MEMORY-SYSTEM.md)** - ReasoningBank + AgentDB hybrid
- **[MCP Tools Reference](./docs/MCP-TOOLS.md)** - Complete tool catalog
- **[Agent System](./docs/AGENT-SYSTEM.md)** - All 64 agents
-### **Release Notes**
-- **[v2.7.0-alpha.10](./docs/RELEASE-NOTES-v2.7.0-alpha.10.md)** - Semantic search fix
-- **[v2.7.0-alpha.9](./docs/RELEASE-NOTES-v2.7.0-alpha.9.md)** - Process cleanup
+### **πŸš€ Release Notes & Changelogs**
+- **[v2.7.1](./docs/releases/v2.7.1/)** - Current stable release with critical fixes
+- **[v2.7.0-alpha.10](./docs/releases/v2.7.0-alpha.10/)** - Semantic search fix
+- **[v2.7.0-alpha.9](./docs/releases/v2.7.0-alpha.9/)** - Process cleanup
- **[Changelog](./CHANGELOG.md)** - Full version history
-### **Advanced Topics**
+### **🧠 AgentDB Integration (96x-164x Performance Boost)**
+- **[AgentDB Documentation](./docs/agentdb/)** - πŸ†• Complete AgentDB v1.3.9 integration docs
+ - [Production Readiness Guide](./docs/agentdb/PRODUCTION_READINESS.md) - Deployment guide
+ - [Implementation Complete](./docs/agentdb/SWARM_IMPLEMENTATION_COMPLETE.md) - 3-agent swarm details (180 tests)
+ - [Backward Compatibility](./docs/agentdb/BACKWARD_COMPATIBILITY_GUARANTEE.md) - 100% compatibility guarantee
+ - [Integration Plan](./docs/agentdb/AGENTDB_INTEGRATION_PLAN.md) - Planning and design
+ - [Optimization Report](./docs/agentdb/OPTIMIZATION_REPORT.md) - Performance analysis
+
+### **⚑ Performance & Quality**
+- **[Performance Documentation](./docs/performance/)** - Optimization guides and benchmarks
+ - [JSON Improvements](./docs/performance/PERFORMANCE-JSON-IMPROVEMENTS.md) - JSON optimization results
+ - [Metrics Guide](./docs/performance/PERFORMANCE-METRICS-GUIDE.md) - Performance tracking
+- **[Bug Fixes](./docs/fixes/)** - Bug fix documentation and patches
+- **[Validation Reports](./docs/validation/)** - Test reports and verification results
+
+### **πŸ› οΈ Advanced Topics**
- **[Neural Module](./docs/NEURAL-MODULE.md)** - SAFLA self-learning
- **[Goal Module](./docs/GOAL-MODULE.md)** - GOAP intelligent planning
- **[Hive-Mind Intelligence](./docs/HIVE-MIND.md)** - Queen-led coordination
- **[GitHub Integration](./docs/GITHUB-INTEGRATION.md)** - Repository automation
-### **Configuration**
+### **βš™οΈ Configuration & Setup**
- **[CLAUDE.md Templates](./docs/CLAUDE-MD-TEMPLATES.md)** - Project configs
- **[SPARC Methodology](./docs/SPARC.md)** - TDD patterns
- **[Windows Installation](./docs/windows-installation.md)** - Windows setup
diff --git a/docs/INDEX.md b/docs/INDEX.md
index bb48e136d0..5d14f053fa 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -256,27 +256,55 @@ npx claude-flow@alpha --agents 3 swarm "task description"
docs/
β”œβ”€β”€ πŸ“„ README.md & INDEX.md # Core entry points
β”‚
+β”œβ”€β”€ πŸš€ releases/ # Release Notes & Changelogs
+β”‚ β”œβ”€β”€ v2.7.1/ # Current stable release
+β”‚ β”‚ β”œβ”€β”€ RELEASE_v2.7.1.md # Release notes
+β”‚ β”‚ └── RELEASE_SUMMARY_v2.7.1.md # Release summary
+β”‚ β”œβ”€β”€ v2.7.0-alpha.10/ # Alpha release
+β”‚ β”‚ └── RELEASE-NOTES-v2.7.0-alpha.10.md # Release notes
+β”‚ β”œβ”€β”€ v2.7.0-alpha.9/ # Previous alpha
+β”‚ β”‚ └── RELEASE-NOTES-v2.7.0-alpha.9.md # Release notes
+β”‚ └── ALPHA_TAG_UPDATE.md # Alpha versioning guide
+β”‚
+β”œβ”€β”€ 🧠 agentdb/ # AgentDB v1.3.9 Integration
+β”‚ β”œβ”€β”€ SWARM_IMPLEMENTATION_COMPLETE.md # 3-agent swarm (180 tests)
+β”‚ β”œβ”€β”€ AGENTDB_INTEGRATION_PLAN.md # Integration planning
+β”‚ β”œβ”€β”€ BACKWARD_COMPATIBILITY_GUARANTEE.md # 100% compatibility
+β”‚ β”œβ”€β”€ PUBLISHING_CHECKLIST.md # Pre-release verification
+β”‚ β”œβ”€β”€ agentdb-integration-summary.md # Quick overview
+β”‚ β”œβ”€β”€ PRODUCTION_READINESS.md # Deployment guide
+β”‚ └── OPTIMIZATION_REPORT.md # Performance analysis
+β”‚
+β”œβ”€β”€ ⚑ performance/ # Performance Optimization
+β”‚ β”œβ”€β”€ PERFORMANCE-JSON-IMPROVEMENTS.md # JSON optimization
+β”‚ └── PERFORMANCE-METRICS-GUIDE.md # Metrics tracking
+β”‚
+β”œβ”€β”€ πŸ”§ fixes/ # Bug Fixes & Patches
+β”‚ β”œβ”€β”€ PATTERN_PERSISTENCE_FIX.md # v2.7.1 critical fix
+β”‚ β”œβ”€β”€ PATTERN_FIX_CONFIRMATION.md # Verification results
+β”‚ └── CLI-MEMORY-COMMANDS-WORKING.md # Memory command fixes
+β”‚
+β”œβ”€β”€ πŸ› οΈ development/ # Development Reports
+β”‚ β”œβ”€β”€ AGENT1_COMPLETION_REPORT.md # AgentDB integration agent
+β”‚ β”œβ”€β”€ FINAL_INIT_STRUCTURE.md # Initialization architecture
+β”‚ └── COMMANDS_TO_SKILLS_MIGRATION.md # Migration guide
+β”‚
+β”œβ”€β”€ βœ… validation/ # Testing & Validation
+β”‚ └── DOCKER_VERIFICATION_REPORT.md # Docker testing results
+β”‚
+β”œβ”€β”€ πŸ“š guides/ # User Guides & Tutorials
+β”‚ └── skills-tutorial.md # 25 Claude Flow skills
+β”‚
β”œβ”€β”€ πŸ”Œ integrations/ # Platform Integrations
β”‚ β”œβ”€β”€ reasoningbank/ # ReasoningBank AI integration (16 docs)
β”‚ β”œβ”€β”€ agentic-flow/ # Agentic Flow system (5 docs)
β”‚ β”œβ”€β”€ agent-booster/ # Agent performance optimization
β”‚ └── epic-sdk/ # Epic SDK integration
β”‚
-β”œβ”€β”€ πŸ“Š reports/ # Analysis & Reports
-β”‚ β”œβ”€β”€ validation/ # Validation & testing reports (7 docs)
-β”‚ β”œβ”€β”€ releases/ # Release notes & summaries (4 docs)
-β”‚ └── analysis/ # Deep analysis & reviews (2 docs)
-β”‚
-β”œβ”€β”€ πŸ”§ technical/ # Technical Details
-β”‚ β”œβ”€β”€ fixes/ # Technical fix summaries (2 docs)
-β”‚ └── performance/ # Performance reports & metrics
-β”‚
β”œβ”€β”€ πŸ—οΈ architecture/ # Architecture documentation
-β”œβ”€β”€ πŸ“š guides/ # User guides & tutorials
β”œβ”€β”€ πŸ”¬ experimental/ # Experimental features
β”œβ”€β”€ πŸ“˜ reference/ # API & command reference
-β”œβ”€β”€ βš™οΈ setup/ # Setup & configuration (+ ENV-SETUP-GUIDE)
-β”œβ”€β”€ βœ… validation/ # Validation frameworks
+β”œβ”€β”€ βš™οΈ setup/ # Setup & configuration
β”œβ”€β”€ πŸ”„ ci-cd/ # CI/CD workflows
β”œβ”€β”€ πŸ“¦ sdk/ # SDK documentation
└── πŸ“– wiki/ # Additional wiki content
diff --git a/docs/README.md b/docs/README.md
index 6c4309146e..63d3c4d2d5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,12 +1,12 @@
# πŸ“š Claude-Flow Documentation
-Welcome to the Claude-Flow documentation! This directory contains comprehensive guides and references for using Claude-Flow v2.0.0-alpha.88.
+Welcome to the Claude-Flow documentation! This directory contains comprehensive guides and references for using Claude-Flow v2.7.0.
-## πŸ“– Documentation Structure
+## πŸ“– Core Documentation
| Document | Description |
|----------|-------------|
-| [INDEX.md](INDEX.md) | Main documentation hub with quick start and navigation |
+| [INDEX.md](INDEX.md) | Complete documentation hub with navigation and quick start |
| [USER_GUIDE.md](USER_GUIDE.md) | Comprehensive user guide with tutorials and examples |
| [API_DOCUMENTATION.md](API_DOCUMENTATION.md) | Complete API reference with all 112 MCP tools |
| [AGENTS.md](AGENTS.md) | All 65+ agent types with capabilities and usage |
@@ -17,12 +17,100 @@ Welcome to the Claude-Flow documentation! This directory contains comprehensive
| [DEPLOYMENT.md](DEPLOYMENT.md) | Production deployment guides for Docker, K8s, Cloud |
| [DEVELOPMENT_WORKFLOW.md](DEVELOPMENT_WORKFLOW.md) | Development setup and contribution guide |
+## πŸ“ Documentation Categories
+
+### πŸš€ [Releases](./releases/)
+Release notes, changelogs, and version documentation
+- [v2.7.1](./releases/v2.7.1/) - Current stable release
+- [v2.7.0-alpha.10](./releases/v2.7.0-alpha.10/) - Alpha release notes
+- [v2.7.0-alpha.9](./releases/v2.7.0-alpha.9/) - Previous alpha release
+- [Alpha Tag Updates](./releases/ALPHA_TAG_UPDATE.md) - Alpha versioning guide
+
+### 🧠 [AgentDB Integration](./agentdb/)
+AgentDB v1.3.9 integration documentation (96x-164x performance boost)
+- [Implementation Complete](./agentdb/SWARM_IMPLEMENTATION_COMPLETE.md) - 3-agent swarm details
+- [Integration Plan](./agentdb/AGENTDB_INTEGRATION_PLAN.md) - Planning and design
+- [Backward Compatibility](./agentdb/BACKWARD_COMPATIBILITY_GUARANTEE.md) - 100% compatibility guarantee
+- [Publishing Checklist](./agentdb/PUBLISHING_CHECKLIST.md) - Pre-release verification
+- [Integration Summary](./agentdb/agentdb-integration-summary.md) - Quick overview
+- [Production Readiness](./agentdb/PRODUCTION_READINESS.md) - Deployment guide
+- [Optimization Report](./agentdb/OPTIMIZATION_REPORT.md) - Performance analysis
+
+### ⚑ [Performance](./performance/)
+Performance optimization guides, metrics, and benchmarks
+- [JSON Improvements](./performance/PERFORMANCE-JSON-IMPROVEMENTS.md) - JSON optimization results
+- [Metrics Guide](./performance/PERFORMANCE-METRICS-GUIDE.md) - Performance tracking and analysis
+
+### πŸ”§ [Bug Fixes](./fixes/)
+Bug fix documentation and patch reports
+- [Pattern Persistence Fix](./fixes/PATTERN_PERSISTENCE_FIX.md) - v2.7.1 critical fix
+- [Pattern Fix Confirmation](./fixes/PATTERN_FIX_CONFIRMATION.md) - Verification and testing
+- [CLI Memory Commands](./fixes/CLI-MEMORY-COMMANDS-WORKING.md) - Memory command fixes
+
+### πŸ› οΈ [Development](./development/)
+Internal development reports and implementation details
+- [Agent 1 Completion Report](./development/AGENT1_COMPLETION_REPORT.md) - AgentDB integration agent
+- [Final Init Structure](./development/FINAL_INIT_STRUCTURE.md) - Initialization architecture
+- [Commands to Skills Migration](./development/COMMANDS_TO_SKILLS_MIGRATION.md) - Migration guide
+
+### βœ… [Validation](./validation/)
+Test reports and validation results
+- [Docker Verification Report](./validation/DOCKER_VERIFICATION_REPORT.md) - Docker testing results
+
+### πŸ“š [User Guides](./guides/)
+Tutorials and learning resources
+- [Skills Tutorial](./guides/skills-tutorial.md) - Complete guide to 25 Claude Flow skills
+
+### πŸ”Œ [Integrations](./integrations/)
+Third-party platform integrations
+- **ReasoningBank** (16 docs) - AI reasoning integration
+- **Agentic Flow** (5 docs) - Agent flow system
+- **Agent Booster** - Performance optimization
+- **Epic SDK** - SDK integration
+
+### πŸ—οΈ Additional Resources
+- [Architecture](./architecture/) - System architecture documentation
+- [Experimental](./experimental/) - Experimental features
+- [Reference](./reference/) - API and command reference
+- [Setup](./setup/) - Setup and configuration guides
+- [CI/CD](./ci-cd/) - Continuous integration workflows
+- [SDK](./sdk/) - SDK documentation
+- [Wiki](./wiki/) - Additional documentation
+
## πŸš€ Quick Links
- **Getting Started**: See [USER_GUIDE.md](USER_GUIDE.md#getting-started)
- **API Reference**: See [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
- **Agent Catalog**: See [AGENTS.md](AGENTS.md)
- **Deployment**: See [DEPLOYMENT.md](DEPLOYMENT.md)
+- **Skills Tutorial**: See [Skills Tutorial](./guides/skills-tutorial.md)
+- **AgentDB Integration**: See [AgentDB](./agentdb/)
+
+## 🎯 By User Type
+
+### πŸ‘¨β€πŸ’» **Developers**
+1. [Quick Start Guide](../README.md#-quick-start) - Get up and running
+2. [Skills Tutorial](./guides/skills-tutorial.md) - Natural language skill activation
+3. [SPARC Development](SPARC.md) - Structured development methodology
+4. [API Reference](API_DOCUMENTATION.md) - Complete endpoint documentation
+
+### 🏒 **DevOps/Operations**
+1. [Deployment Guide](DEPLOYMENT.md) - Production deployment
+2. [Architecture Overview](ARCHITECTURE.md) - System design
+3. [Docker Verification](./validation/DOCKER_VERIFICATION_REPORT.md) - Testing reports
+
+### πŸ‘‘ **Technical Leaders**
+1. [System Architecture](ARCHITECTURE.md#system-overview) - High-level design
+2. [Performance Metrics](./performance/) - Benchmarks and optimization
+3. [AgentDB Integration](./agentdb/) - 96x-164x performance improvements
+
+## πŸ“Š Performance Highlights
+
+- **96x-164x faster search** - AgentDB vector search improvements
+- **4-32x memory reduction** - Quantization benefits
+- **84.8% SWE-Bench solve rate** - Industry-leading performance
+- **32.3% token reduction** - Efficient context management
+- **2.8-4.4x speed improvement** - Parallel coordination
## πŸ“ž Support
@@ -32,4 +120,4 @@ Welcome to the Claude-Flow documentation! This directory contains comprehensive
---
-*Last Updated: January 2025 | Version: 2.0.0-alpha.88*
\ No newline at end of file
+*Last Updated: January 2025 | Version: v2.7.1*
diff --git a/docs/AGENTDB_INTEGRATION_PLAN.md b/docs/agentdb/AGENTDB_INTEGRATION_PLAN.md
similarity index 100%
rename from docs/AGENTDB_INTEGRATION_PLAN.md
rename to docs/agentdb/AGENTDB_INTEGRATION_PLAN.md
diff --git a/docs/BACKWARD_COMPATIBILITY_GUARANTEE.md b/docs/agentdb/BACKWARD_COMPATIBILITY_GUARANTEE.md
similarity index 100%
rename from docs/BACKWARD_COMPATIBILITY_GUARANTEE.md
rename to docs/agentdb/BACKWARD_COMPATIBILITY_GUARANTEE.md
diff --git a/docs/PUBLISHING_CHECKLIST.md b/docs/agentdb/PUBLISHING_CHECKLIST.md
similarity index 100%
rename from docs/PUBLISHING_CHECKLIST.md
rename to docs/agentdb/PUBLISHING_CHECKLIST.md
diff --git a/docs/agentdb/README.md b/docs/agentdb/README.md
new file mode 100644
index 0000000000..a83a44097a
--- /dev/null
+++ b/docs/agentdb/README.md
@@ -0,0 +1,58 @@
+# πŸš€ AgentDB v1.3.9 Integration Documentation
+
+Complete documentation for AgentDB vector database integration (PR #830).
+
+## Overview
+
+AgentDB v1.3.9 integration provides 96x-164x performance improvements with semantic vector search, 9 RL algorithms, and comprehensive learning capabilities.
+
+## Key Documents
+
+### Implementation & Planning
+- **[Integration Plan](./AGENTDB_INTEGRATION_PLAN.md)** - Complete v1.3.9 integration specification
+- **[Implementation Summary](./SWARM_IMPLEMENTATION_COMPLETE.md)** - 3-agent swarm implementation report
+- **[Integration Summary](./agentdb-integration-summary.md)** - Quick overview
+
+### Compatibility & Deployment
+- **[Backward Compatibility Guarantee](./BACKWARD_COMPATIBILITY_GUARANTEE.md)** - 100% compatibility confirmation
+- **[Production Readiness](./PRODUCTION_READINESS.md)** - Deployment guide and best practices
+- **[Publishing Checklist](./PUBLISHING_CHECKLIST.md)** - Pre-publishing verification
+
+### Performance & Optimization
+- **[Optimization Report](./OPTIMIZATION_REPORT.md)** - Performance analysis and tuning
+- **[Swarm Coordination](./SWARM_COORDINATION.md)** - Multi-agent implementation details
+
+## Quick Links
+
+- **GitHub PR**: #830
+- **GitHub Issue**: #829
+- **Branch**: `feature/agentdb-integration`
+- **Package**: [[email protected]](https://www.npmjs.com/package/agentdb)
+
+## Performance Improvements
+
+- **Vector Search**: 96x faster (9.6ms β†’ <0.1ms)
+- **Batch Operations**: 125x faster
+- **Large Queries**: 164x faster
+- **Memory Usage**: 4-32x reduction (quantization)
+
+## Installation
+
+```bash
+# Optional - AgentDB is peer dependency
+npm install [email protected]
+```
+
+## Features
+
+- βœ… Semantic vector search (HNSW indexing)
+- βœ… 9 RL algorithms (Q-Learning, PPO, MCTS, etc.)
+- βœ… Reflexion memory (learn from experience)
+- βœ… Skill library (auto-consolidate patterns)
+- βœ… Causal reasoning (cause-effect understanding)
+- βœ… Quantization (binary 32x, scalar 4x, product 8-16x)
+- βœ… 100% backward compatible
+
+---
+
+[← Back to Documentation Index](../README.md)
diff --git a/docs/agentdb-integration-summary.md b/docs/agentdb/agentdb-integration-summary.md
similarity index 100%
rename from docs/agentdb-integration-summary.md
rename to docs/agentdb/agentdb-integration-summary.md
diff --git a/docs/AGENT1_COMPLETION_REPORT.md b/docs/development/AGENT1_COMPLETION_REPORT.md
similarity index 100%
rename from docs/AGENT1_COMPLETION_REPORT.md
rename to docs/development/AGENT1_COMPLETION_REPORT.md
diff --git a/docs/COMMANDS_TO_SKILLS_MIGRATION.md b/docs/development/COMMANDS_TO_SKILLS_MIGRATION.md
similarity index 100%
rename from docs/COMMANDS_TO_SKILLS_MIGRATION.md
rename to docs/development/COMMANDS_TO_SKILLS_MIGRATION.md
diff --git a/docs/FINAL_INIT_STRUCTURE.md b/docs/development/FINAL_INIT_STRUCTURE.md
similarity index 100%
rename from docs/FINAL_INIT_STRUCTURE.md
rename to docs/development/FINAL_INIT_STRUCTURE.md
diff --git a/docs/development/README.md b/docs/development/README.md
new file mode 100644
index 0000000000..f1a3022646
--- /dev/null
+++ b/docs/development/README.md
@@ -0,0 +1,22 @@
+# πŸ› οΈ Development Documentation
+
+Internal development reports, implementation details, and architectural decisions.
+
+## Development Reports
+
+### Agent Implementation
+- **[Agent 1 Completion Report](./AGENT1_COMPLETION_REPORT.md)** - AgentDB integration agent deliverables
+
+### Architecture & Structure
+- **[Final Init Structure](./FINAL_INIT_STRUCTURE.md)** - Initialization system architecture
+- **[Commands to Skills Migration](./COMMANDS_TO_SKILLS_MIGRATION.md)** - Migration guide for slash commands to skills
+
+## Related Documentation
+
+- [Architecture Docs](../architecture/) - System architecture documentation
+- [Technical Docs](../technical/) - Technical implementation details
+- [AgentDB Implementation](../agentdb/SWARM_IMPLEMENTATION_COMPLETE.md) - 3-agent swarm details
+
+---
+
+[← Back to Documentation Index](../README.md)
diff --git a/docs/CLI-MEMORY-COMMANDS-WORKING.md b/docs/fixes/CLI-MEMORY-COMMANDS-WORKING.md
similarity index 100%
rename from docs/CLI-MEMORY-COMMANDS-WORKING.md
rename to docs/fixes/CLI-MEMORY-COMMANDS-WORKING.md
diff --git a/docs/PATTERN_FIX_CONFIRMATION.md b/docs/fixes/PATTERN_FIX_CONFIRMATION.md
similarity index 100%
rename from docs/PATTERN_FIX_CONFIRMATION.md
rename to docs/fixes/PATTERN_FIX_CONFIRMATION.md
diff --git a/docs/PATTERN_PERSISTENCE_FIX.md b/docs/fixes/PATTERN_PERSISTENCE_FIX.md
similarity index 100%
rename from docs/PATTERN_PERSISTENCE_FIX.md
rename to docs/fixes/PATTERN_PERSISTENCE_FIX.md
diff --git a/docs/fixes/README.md b/docs/fixes/README.md
new file mode 100644
index 0000000000..f4f6d4c0a4
--- /dev/null
+++ b/docs/fixes/README.md
@@ -0,0 +1,33 @@
+# πŸ”§ Bug Fixes & Patches
+
+Documentation for bug fixes, patches, and issue resolutions.
+
+## Recent Fixes
+
+### Pattern Persistence Issues
+- **[Pattern Persistence Fix](./PATTERN_PERSISTENCE_FIX.md)** - v2.7.1 critical fix for MCP pattern persistence
+- **[Pattern Fix Confirmation](./PATTERN_FIX_CONFIRMATION.md)** - Verification and testing results
+
+### CLI Improvements
+- **[CLI Memory Commands Working](./CLI-MEMORY-COMMANDS-WORKING.md)** - Memory command functionality restoration
+
+## Fixed Issues by Category
+
+### Critical Fixes
+- MCP pattern persistence (v2.7.1)
+- Memory command functionality
+- Semantic search results
+
+### Performance Fixes
+- JSON optimization
+- Query latency improvements
+- Token reduction
+
+## Related Documentation
+
+- [Release Notes](../releases/) - Complete changelog for all versions
+- [Validation Reports](../validation/) - Test reports and verification
+
+---
+
+[← Back to Documentation Index](../README.md)
diff --git a/docs/guides/README.md b/docs/guides/README.md
new file mode 100644
index 0000000000..10eda79f44
--- /dev/null
+++ b/docs/guides/README.md
@@ -0,0 +1,29 @@
+# πŸ“š User Guides & Tutorials
+
+Comprehensive guides and tutorials for using claude-flow.
+
+## Featured Guides
+
+### Skills System
+- **[Skills Tutorial](./skills-tutorial.md)** - Complete guide to 25 Claude Flow skills with natural language invocation
+
+## Skill Categories
+
+From the skills tutorial:
+- **Development & Methodology** (3 skills) - SPARC, pair programming, skill builder
+- **Intelligence & Memory** (6 skills) - AgentDB integration with 150x-12,500x performance
+- **Swarm Coordination** (3 skills) - Multi-agent orchestration and hive-mind
+- **GitHub Integration** (5 skills) - PR review, workflows, releases, multi-repo
+- **Automation & Quality** (4 skills) - Hooks, verification, performance analysis
+- **Flow Nexus Platform** (3 skills) - Cloud sandboxes and neural training
+
+## Additional Guides
+
+Browse other guides in this directory or see:
+- [Setup Guides](../setup/) - Installation and configuration
+- [Integration Guides](../integrations/) - Third-party integrations
+- [API Reference](../api/) - API documentation
+
+---
+
+[← Back to Documentation Index](../README.md)
diff --git a/docs/skills-tutorial.md b/docs/guides/skills-tutorial.md
similarity index 100%
rename from docs/skills-tutorial.md
rename to docs/guides/skills-tutorial.md
diff --git a/docs/PERFORMANCE-JSON-IMPROVEMENTS.md b/docs/performance/PERFORMANCE-JSON-IMPROVEMENTS.md
similarity index 100%
rename from docs/PERFORMANCE-JSON-IMPROVEMENTS.md
rename to docs/performance/PERFORMANCE-JSON-IMPROVEMENTS.md
diff --git a/docs/PERFORMANCE-METRICS-GUIDE.md b/docs/performance/PERFORMANCE-METRICS-GUIDE.md
similarity index 100%
rename from docs/PERFORMANCE-METRICS-GUIDE.md
rename to docs/performance/PERFORMANCE-METRICS-GUIDE.md
diff --git a/docs/performance/README.md b/docs/performance/README.md
new file mode 100644
index 0000000000..926595ff0c
--- /dev/null
+++ b/docs/performance/README.md
@@ -0,0 +1,31 @@
+# ⚑ Performance Documentation
+
+Performance optimization guides, metrics, and analysis for claude-flow.
+
+## Documents
+
+### Performance Improvements
+- **[JSON Improvements](./PERFORMANCE-JSON-IMPROVEMENTS.md)** - JSON optimization techniques and results
+- **[Metrics Guide](./PERFORMANCE-METRICS-GUIDE.md)** - Performance metrics collection and analysis
+
+## Key Metrics
+
+### Current Performance
+- **84.8% SWE-Bench solve rate** - Industry-leading problem-solving
+- **32.3% token reduction** - Efficient context management
+- **2.8-4.4x speed improvement** - Parallel coordination
+- **2-3ms query latency** - ReasoningBank semantic search
+
+### With AgentDB v1.3.9
+- **96x-164x faster search** - Vector search improvements
+- **4-32x memory reduction** - Quantization benefits
+- **Sub-millisecond search** - HNSW indexing (<0.1ms)
+
+## Related Documentation
+
+- [AgentDB Integration](../agentdb/) - 96x-164x performance boost
+- [AgentDB Optimization Report](../agentdb/OPTIMIZATION_REPORT.md) - Detailed performance analysis
+
+---
+
+[← Back to Documentation Index](../README.md)
diff --git a/docs/ALPHA_TAG_UPDATE.md b/docs/releases/ALPHA_TAG_UPDATE.md
similarity index 100%
rename from docs/ALPHA_TAG_UPDATE.md
rename to docs/releases/ALPHA_TAG_UPDATE.md
diff --git a/docs/releases/README.md b/docs/releases/README.md
new file mode 100644
index 0000000000..0b55e3f025
--- /dev/null
+++ b/docs/releases/README.md
@@ -0,0 +1,25 @@
+# πŸ“‹ Release Notes & Changelogs
+
+Release documentation for claude-flow versions.
+
+## Latest Releases
+
+### v2.7.1 (Current)
+- **[Release Notes](./v2.7.1/RELEASE_v2.7.1.md)** - Complete v2.7.1 release notes
+- **[Release Summary](./v2.7.1/RELEASE_SUMMARY_v2.7.1.md)** - Quick summary of v2.7.1 changes
+
+### v2.7.0-alpha.10
+- **[Release Notes](./v2.7.0-alpha.10/RELEASE-NOTES-v2.7.0-alpha.10.md)** - Semantic search fix
+
+### v2.7.0-alpha.9
+- **[Release Notes](./v2.7.0-alpha.9/RELEASE-NOTES-v2.7.0-alpha.9.md)** - Process cleanup
+
+## Alpha Tag Updates
+- **[Alpha Tag Update](./ALPHA_TAG_UPDATE.md)** - Alpha versioning documentation
+
+## Full Changelog
+See [CHANGELOG.md](../../CHANGELOG.md) in the root directory for complete version history.
+
+---
+
+[← Back to Documentation Index](../README.md)
diff --git a/docs/RELEASE-NOTES-v2.7.0-alpha.10.md b/docs/releases/v2.7.0-alpha.10/RELEASE-NOTES-v2.7.0-alpha.10.md
similarity index 99%
rename from docs/RELEASE-NOTES-v2.7.0-alpha.10.md
rename to docs/releases/v2.7.0-alpha.10/RELEASE-NOTES-v2.7.0-alpha.10.md
index 6e52a9a988..c56bdc95fe 100644
--- a/docs/RELEASE-NOTES-v2.7.0-alpha.10.md
+++ b/docs/releases/v2.7.0-alpha.10/RELEASE-NOTES-v2.7.0-alpha.10.md
@@ -263,7 +263,7 @@ All core functionality now working:
### With OpenAI API Key (Optional)
- Enhanced embeddings (text-embedding-3-small, 1536 dimensions)
- Better semantic accuracy
-- Set via: `export OPENAI_API_KEY=$YOUR_API_KEY`
+- Set via environment variable: `OPENAI_API_KEY` (see ReasoningBank docs)
---
diff --git a/docs/RELEASE-NOTES-v2.7.0-alpha.9.md b/docs/releases/v2.7.0-alpha.9/RELEASE-NOTES-v2.7.0-alpha.9.md
similarity index 100%
rename from docs/RELEASE-NOTES-v2.7.0-alpha.9.md
rename to docs/releases/v2.7.0-alpha.9/RELEASE-NOTES-v2.7.0-alpha.9.md
diff --git a/docs/RELEASE_SUMMARY_v2.7.1.md b/docs/releases/v2.7.1/RELEASE_SUMMARY_v2.7.1.md
similarity index 100%
rename from docs/RELEASE_SUMMARY_v2.7.1.md
rename to docs/releases/v2.7.1/RELEASE_SUMMARY_v2.7.1.md
diff --git a/docs/RELEASE_v2.7.1.md b/docs/releases/v2.7.1/RELEASE_v2.7.1.md
similarity index 100%
rename from docs/RELEASE_v2.7.1.md
rename to docs/releases/v2.7.1/RELEASE_v2.7.1.md
diff --git a/docs/DOCKER_VERIFICATION_REPORT.md b/docs/validation/DOCKER_VERIFICATION_REPORT.md
similarity index 100%
rename from docs/DOCKER_VERIFICATION_REPORT.md
rename to docs/validation/DOCKER_VERIFICATION_REPORT.md
diff --git a/docs/validation/README.md b/docs/validation/README.md
new file mode 100644
index 0000000000..7357d9c536
--- /dev/null
+++ b/docs/validation/README.md
@@ -0,0 +1,25 @@
+# βœ… Validation & Testing
+
+Test reports, validation results, and quality assurance documentation.
+
+## Test Reports
+
+### Docker & Integration Testing
+- **[Docker Verification Report](./DOCKER_VERIFICATION_REPORT.md)** - Docker deployment validation and testing
+
+## Related Testing Documentation
+
+- [AgentDB Tests](../agentdb/SWARM_IMPLEMENTATION_COMPLETE.md) - 180 comprehensive tests
+- [Performance Tests](../performance/) - Performance benchmarks and validation
+- [Fix Confirmations](../fixes/) - Bug fix verification reports
+
+## Quality Metrics
+
+- **Test Coverage**: >90%
+- **Backward Compatibility**: 100%
+- **Integration Tests**: 39 regression tests
+- **AgentDB Tests**: 180 comprehensive tests
+
+---
+
+[← Back to Documentation Index](../README.md)