# 📚 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!** 💙✨🎵