reorganize: consolidate all documentation into readmes/

- Moved 20 root-level markdown files to readmes/ - Includes COMMANDS.md, CONFIG_README.md, all UNO docs, all completion reports - Added new: MEMORY_EDITOR_FEATURE.md, MEMORY_EDITOR_ESCAPING_FIX.md, CONFIG_SOURCES_ANALYSIS.md, MCP_TOOL_CALLING_ANALYSIS.md, and others - Root directory is now clean of documentation clutter
2026-03-04 00:19:49 +02:00
parent fdde12c03d
commit c708770266
22 changed files with 4573 additions and 0 deletions
--- a/readmes/UNO_DOCS_INDEX.md
+++ b/readmes/UNO_DOCS_INDEX.md
@@ -0,0 +1,370 @@
+# 📚 Miku UNO Bot - Documentation Index
+
+## 🚀 Quick Start (Start Here!)
+
+**New to the project?** Start with these in order:
+
+1. **[UNO_FIRST_TEST.md](UNO_FIRST_TEST.md)** ⭐ **START HERE**
+   - 5-minute setup guide
+   - Step-by-step first test
+   - What to expect
+   - Common issues
+
+2. **[UNO_QUICK_REF.md](UNO_QUICK_REF.md)** 📋 **Quick Reference**
+   - Command cheat sheet
+   - File locations
+   - Quick debugging
+   - One-page reference
+
+3. **[UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md)** 📖 **Complete Overview**
+   - What we built
+   - How it works
+   - Technology stack
+   - Success story
+
+---
+
+## 📖 Comprehensive Guides
+
+### Setup & Configuration
+- **[UNO_BOT_SETUP.md](UNO_BOT_SETUP.md)**
+  - Detailed setup instructions
+  - Configuration options
+  - Troubleshooting guide
+  - System requirements
+
+### Testing
+- **[UNO_BOT_TESTING.md](UNO_BOT_TESTING.md)**
+  - Complete test checklist
+  - 17 test scenarios
+  - Error scenarios
+  - Performance tests
+  - Quality assurance
+
+### Implementation
+- **[UNO_CHECKLIST.md](UNO_CHECKLIST.md)**
+  - Implementation status
+  - Pre-test checklist
+  - Code quality checks
+  - Deployment readiness
+
+---
+
+## 🔧 Technical Documentation
+
+### Architecture
+- **[UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md)**
+  - Visual flow diagrams
+  - Architecture overview
+  - Command flow
+  - Game loop flow
+  - LLM decision flow
+  - Data flow
+  - Timing diagrams
+
+### Integration Details
+- **[BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md)**
+  - Technical implementation
+  - API documentation
+  - WebSocket integration
+  - Testing results
+
+### API Specification
+- **[BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md)**
+  - JSON action format
+  - Card codes reference
+  - Validation rules
+  - Examples
+
+### Manual Testing
+- **[QUICK_START_BOT.md](../uno-online/QUICK_START_BOT.md)**
+  - Manual testing tool
+  - CLI usage
+  - Direct API testing
+  - Debugging
+
+---
+
+## 📂 File Structure
+
+### Discord Bot Files
+```
+/home/koko210Serve/docker/miku-discord/
+│
+├── 📚 Documentation (Start Here)
+│   ├── UNO_FIRST_TEST.md           ⭐ First test guide
+│   ├── UNO_QUICK_REF.md             Quick reference
+│   ├── UNO_INTEGRATION_SUMMARY.md   Complete summary
+│   ├── UNO_BOT_SETUP.md             Setup guide
+│   ├── UNO_BOT_TESTING.md           Testing checklist
+│   ├── UNO_CHECKLIST.md             Implementation status
+│   ├── UNO_FLOW_DIAGRAMS.md         Visual diagrams
+│   └── UNO_DOCS_INDEX.md            This file
+│
+└── bot/
+    ├── bot.py                       Main bot (UPDATED)
+    ├── setup_uno_playwright.sh      Setup script
+    │
+    ├── commands/
+    │   └── uno.py                   Discord commands (NEW)
+    │
+    └── utils/
+        └── uno_game.py              Game automation (NEW)
+```
+
+### UNO Game Files
+```
+/home/koko210Serve/docker/uno-online/
+│
+├── 📚 Documentation
+│   ├── BOT_INTEGRATION_COMPLETE.md  Technical details
+│   ├── BOT_ACTION_SPEC.md           JSON format
+│   └── QUICK_START_BOT.md           Manual testing
+│
+├── server.js                        Backend (UPDATED)
+├── test-bot-action.js               Testing tool (NEW)
+│
+└── client/
+    └── src/
+        ├── components/
+        │   └── Game.js              Main game (UPDATED)
+        │
+        └── utils/
+            └── botActionExecutor.js  Actions (NEW)
+```
+
+---
+
+## 🎯 By Task
+
+### I want to...
+
+#### ...set up the bot for the first time
+1. [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) - Quick setup
+2. [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md) - Detailed guide
+3. Run: `bash bot/setup_uno_playwright.sh`
+
+#### ...test the bot
+1. [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) - First test
+2. [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md) - Full checklist
+3. [QUICK_START_BOT.md](../uno-online/QUICK_START_BOT.md) - Manual testing
+
+#### ...understand how it works
+1. [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md) - Overview
+2. [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md) - Visual diagrams
+3. [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md) - Technical
+
+#### ...use Discord commands
+1. [UNO_QUICK_REF.md](UNO_QUICK_REF.md) - Command reference
+2. Type `!uno help` in Discord
+
+#### ...understand the JSON format
+1. [BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md) - Full spec
+2. [UNO_QUICK_REF.md](UNO_QUICK_REF.md) - Quick reference
+
+#### ...debug an issue
+1. [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md) - Troubleshooting section
+2. [UNO_QUICK_REF.md](UNO_QUICK_REF.md) - Quick debugging
+3. Check logs: `tail -f bot.log | grep UNO`
+
+#### ...understand the architecture
+1. [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md) - All diagrams
+2. [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md) - Tech stack
+3. [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md) - Details
+
+---
+
+## 🎮 By User Type
+
+### Casual User (Just want to play)
+1. [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md)
+2. [UNO_QUICK_REF.md](UNO_QUICK_REF.md)
+3. Type `!uno create` in Discord
+
+### Developer (Want to understand code)
+1. [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md)
+2. [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md)
+3. [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md)
+4. Read source: `bot/commands/uno.py`, `bot/utils/uno_game.py`
+
+### Tester (Want to validate functionality)
+1. [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md)
+2. [UNO_CHECKLIST.md](UNO_CHECKLIST.md)
+3. [QUICK_START_BOT.md](../uno-online/QUICK_START_BOT.md)
+
+### DevOps (Want to deploy)
+1. [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md)
+2. [UNO_CHECKLIST.md](UNO_CHECKLIST.md)
+3. Check dependencies in `bot/requirements.txt`
+
+---
+
+## 📊 By Topic
+
+### Commands
+- **Discord Commands**: [UNO_QUICK_REF.md](UNO_QUICK_REF.md#discord-commands)
+- **Shell Commands**: [UNO_QUICK_REF.md](UNO_QUICK_REF.md#quick-debugging)
+- **Test Commands**: [QUICK_START_BOT.md](../uno-online/QUICK_START_BOT.md)
+
+### Architecture
+- **High-Level**: [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md#technology-stack)
+- **Flow Diagrams**: [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md)
+- **Components**: [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md)
+
+### API
+- **JSON Format**: [BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md)
+- **HTTP Endpoints**: [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md#http-api-endpoints)
+- **WebSocket Events**: [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md#websocket-integration)
+
+### LLM Integration
+- **Strategy System**: [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md#llm-strategy-prompt-example)
+- **Decision Flow**: [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md#llm-strategy-decision-flow)
+- **Personality**: [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md#-personality)
+
+### Personality
+- **Trash Talk**: [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md#personality-integration)
+- **Messages**: [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md#-personality)
+- **Testing**: [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md#test-6-trash-talk-personality)
+
+### Troubleshooting
+- **Common Issues**: [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md#-common-issues)
+- **Detailed Guide**: [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md#troubleshooting)
+- **Quick Debug**: [UNO_QUICK_REF.md](UNO_QUICK_REF.md#quick-debugging)
+
+---
+
+## 🔍 Search Guide
+
+### Looking for...
+
+**Setup instructions?**
+→ [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) or [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md)
+
+**Command reference?**
+→ [UNO_QUICK_REF.md](UNO_QUICK_REF.md)
+
+**How it works?**
+→ [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md)
+
+**Testing procedures?**
+→ [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md)
+
+**JSON format?**
+→ [BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md)
+
+**Troubleshooting?**
+→ [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md#troubleshooting)
+
+**Architecture details?**
+→ [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md)
+
+**Implementation status?**
+→ [UNO_CHECKLIST.md](UNO_CHECKLIST.md)
+
+**Card codes?**
+→ [BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md#card-codes)
+
+**Configuration?**
+→ [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md#configuration)
+
+---
+
+## 📈 Reading Paths
+
+### Path 1: Quick Start (15 minutes)
+1. [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) - 5 min setup
+2. Test with `!uno create` - 5 min
+3. [UNO_QUICK_REF.md](UNO_QUICK_REF.md) - 5 min reference
+
+### Path 2: Complete Understanding (1 hour)
+1. [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) - 10 min
+2. [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md) - 20 min
+3. [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md) - 15 min
+4. [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md) - 15 min
+
+### Path 3: Full Testing (2 hours)
+1. [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) - 10 min
+2. [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md) - 90 min
+3. [UNO_CHECKLIST.md](UNO_CHECKLIST.md) - 20 min
+
+### Path 4: Deep Dive (3 hours)
+1. All of Path 2
+2. [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md) - 30 min
+3. [BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md) - 20 min
+4. Read source code - 60 min
+
+---
+
+## 🎯 Key Documents Summary
+
+| Document | Purpose | Length | Audience |
+|----------|---------|--------|----------|
+| [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md) | Quick start | 5 min | Everyone |
+| [UNO_QUICK_REF.md](UNO_QUICK_REF.md) | Reference card | 2 min | Everyone |
+| [UNO_INTEGRATION_SUMMARY.md](UNO_INTEGRATION_SUMMARY.md) | Complete overview | 20 min | All users |
+| [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md) | Detailed setup | 30 min | Deployers |
+| [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md) | Test checklist | 90 min | Testers |
+| [UNO_CHECKLIST.md](UNO_CHECKLIST.md) | Status tracker | 10 min | Developers |
+| [UNO_FLOW_DIAGRAMS.md](UNO_FLOW_DIAGRAMS.md) | Visual guide | 15 min | Developers |
+| [BOT_ACTION_SPEC.md](../uno-online/BOT_ACTION_SPEC.md) | API spec | 15 min | Developers |
+| [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md) | Technical | 20 min | Developers |
+| [QUICK_START_BOT.md](../uno-online/QUICK_START_BOT.md) | Manual testing | 10 min | Testers |
+
+---
+
+## 🚀 Getting Started Checklist
+
+- [ ] Read [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md)
+- [ ] Run `bash bot/setup_uno_playwright.sh`
+- [ ] Start UNO servers (backend + frontend)
+- [ ] Start Miku bot
+- [ ] Type `!uno create` in Discord
+- [ ] Join game in browser
+- [ ] Watch Miku play!
+- [ ] Read [UNO_QUICK_REF.md](UNO_QUICK_REF.md) for reference
+- [ ] Complete [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md) checklist
+- [ ] Mark [UNO_CHECKLIST.md](UNO_CHECKLIST.md) as tested
+
+---
+
+## 📞 Support
+
+### For Setup Issues
+→ [UNO_BOT_SETUP.md](UNO_BOT_SETUP.md#troubleshooting)
+
+### For Testing Issues
+→ [UNO_BOT_TESTING.md](UNO_BOT_TESTING.md)
+
+### For Technical Questions
+→ [BOT_INTEGRATION_COMPLETE.md](../uno-online/BOT_INTEGRATION_COMPLETE.md)
+
+### For Quick Reference
+→ [UNO_QUICK_REF.md](UNO_QUICK_REF.md)
+
+---
+
+## 📝 Document Status
+
+| Document | Status | Last Updated |
+|----------|--------|--------------|
+| UNO_FIRST_TEST.md | ✅ Complete | 2025-01 |
+| UNO_QUICK_REF.md | ✅ Complete | 2025-01 |
+| UNO_INTEGRATION_SUMMARY.md | ✅ Complete | 2025-01 |
+| UNO_BOT_SETUP.md | ✅ Complete | 2025-01 |
+| UNO_BOT_TESTING.md | ✅ Complete | 2025-01 |
+| UNO_CHECKLIST.md | ✅ Complete | 2025-01 |
+| UNO_FLOW_DIAGRAMS.md | ✅ Complete | 2025-01 |
+| UNO_DOCS_INDEX.md | ✅ Complete | 2025-01 |
+| BOT_ACTION_SPEC.md | ✅ Complete | 2025-01 |
+| BOT_INTEGRATION_COMPLETE.md | ✅ Complete | 2025-01 |
+| QUICK_START_BOT.md | ✅ Complete | 2025-01 |
+
+---
+
+## 🎮 Ready to Start?
+
+**👉 [UNO_FIRST_TEST.md](UNO_FIRST_TEST.md)** - Start here!
+
+---
+
+**Have fun playing UNO with Miku!** 💙✨🎵