docs: Comprehensive README update with AI Analysis and NL interface features

- Added detailed AI-powered tactical analysis section
- Documented natural language command interface
- Included performance optimizations for HuggingFace (2 vCPU)
- Updated project status to v2.1 with recent bug fixes
- Showcased shared model architecture
- Added multi-language support details
- Included complete feature list and how-to guides
- Backed up old README to README.old.md

README.md

@@ -8,237 +8,397 @@ pinned: false
 license: mit
 ---
 
-# 🎮 Command & Conquer: Tiberium Dawn - Web Version
+# 🎮 RTS Commander - Command & Conquer Web Edition
 
-A faithful recreation of the classic Command & Conquer: Tiberium Dawn in **pure web technologies** (FastAPI + WebSocket + Canvas).
+A modern web-based Real-Time Strategy game inspired by Command & Conquer: Tiberium Dawn, featuring **AI-powered tactical analysis** and **natural language command interface**.
 
----
-
-## 📂 Project Structure
+**🌐 [Play Now](https://huggingface.co/spaces/Luigi/rts-commander)** | **📚 [Documentation](docs/)** | **🧪 [Tests](tests/)**
 
-```
-web/
-├── README.md           # This file
-├── app.py              # FastAPI server & WebSocket
-├── start.py            # Server launcher
-├── localization.py     # Multi-language support
-├── ai_analysis.py      # AI engine
-├── mcp_server.py       # MCP server integration
-├── backend/            # Game logic
-├── frontend/           # JavaScript game engine
-├── static/             # Assets (images, sounds)
-├── docs/               # 📚 Documentation
-├── tests/              # 🧪 Test scripts
-└── tools/              # 🛠️ Dev/debug/ops scripts
-```
+---
 
+## ✨ Key Features
+
+### 🎯 Classic RTS Gameplay
+- **Resource Management**: Harvest Tiberium to fund your war machine
+- **Base Building**: Construct power plants, refineries, barracks, and war factories
+- **Unit Production**: Train infantry, build tanks, and deploy helicopters
+- **Real-Time Combat**: Command your forces against an aggressive AI opponent
+- **Fog of War**: Explore the battlefield and reveal enemy positions
+- **Power System**: Manage energy production and consumption (Red Alert-style)
+
+### 🤖 AI-Powered Tactical Analysis
+- **Real-time battlefield analysis** powered by Qwen2.5-Coder-1.5B LLM
+- **Strategic recommendations** based on current game state
+- **Resource management tips** and economic guidance
+- **Threat assessment** and defensive positioning advice
+- **Multi-language support** (English, French, Chinese)
+- Updates every 60 seconds with fresh tactical insights
+
+### 💬 Natural Language Command Interface
+- **Talk to your units** in plain language (any language!)
+- **Examples**:
+  - "Move my tanks to the north base" → Parsed to move commands
+  - "Construire une centrale électrique" → Build power plant
+  - "生產三個步兵" → Train 3 infantry units
+- **Powered by LLM** with MCP-style command translation
+- **Fallback examples** provided in multiple languages
+- **Real-time translation** from natural language to game commands
+
+### 🌐 Multi-Language Support
+- 🇬🇧 **English** - Full interface and AI analysis
+- 🇫🇷 **Français** - Interface complète et analyse IA
+- 🇹🇼 **繁體中文** - 完整界面和AI分析
+- Switch languages instantly during gameplay
+
+### 🎨 Modern Web Technologies
+- **No installation required** - Play directly in browser
+- **Cross-platform** - Works on desktop, tablet, and mobile
+- **Real-time multiplayer ready** - WebSocket architecture
+- **Responsive UI** - Adapts to different screen sizes
+- **Canvas-based rendering** - Smooth 60 FPS gameplay
 
 ---
 
 ## 🚀 Quick Start
 
+### Play Online
+Visit **[https://huggingface.co/spaces/Luigi/rts-commander](https://huggingface.co/spaces/Luigi/rts-commander)** to play instantly!
+
 ### Local Development
 
-1. **Install dependencies:**
-   ```bash
-   pip install -r requirements.txt
-   ```
+```bash
+# Clone the repository
+git clone <repository-url>
+cd rts/web
 
-2. **Start the server:**
-   ```bash
-   python start.py
-   ```
+# Install dependencies
+pip install -r requirements.txt
 
-3. **Open in browser:**
-   ```
-   http://localhost:8000
-   ```
+# Start the server
+python start.py
+
+# Open in browser
+# http://localhost:8000
+```
 
 ---
 
-## 📖 Documentation
+## 🎮 How to Play
+
+### Basic Controls
+
+| Action | Control |
+|--------|---------|
+| **Select units/buildings** | Left Click |
+| **Move units** | Right Click on ground |
+| **Attack enemies** | Right Click on enemy unit/building |
+| **Box select multiple units** | Click + Drag |
+| **Build structure** | Click building button in sidebar |
+| **Place building** | Click on construction grid |
+| **Cancel building** | Press Escape |
+| **Pan camera** | Arrow Keys or WASD |
+| **Use NL interface** | Type in left sidebar input |
+
+### Getting Started
+
+1. **Build a Power Plant** - Required for all other structures
+2. **Build a Refinery** - Process Tiberium for credits
+3. **Wait for Harvester** - Automatically deployed with refinery
+4. **Build a Barracks** - Train infantry units
+5. **Defend your base** - Enemy attacks start quickly!
+6. **Expand and conquer** - Build more structures and units
+
+### Using AI Analysis
+
+The **AI Analysis Panel** (right side) provides:
+- **Battlefield Overview**: Current situation assessment
+- **Economic Status**: Credits, production, and resource flow
+- **Military Assessment**: Unit counts and combat readiness
+- **Strategic Advice**: What to do next
+- **Tactical Tips**: How to improve your position
+
+### Using Natural Language Commands
+
+The **NL Command Interface** (left side) lets you:
+1. Type commands in natural language (any supported language)
+2. View example commands for inspiration
+3. See command history and results
+4. Get instant feedback on command execution
+
+**Example Commands:**
+- "Build 5 infantry units"
+- "Déplacer mes tanks vers le nord"
+- "攻擊敵人的基地"
 
-### 📚 Complete Documentation
-All technical documentation is in **[docs/](docs/)** (28 files organized by category):
-- **Architecture:** System design, project structure
-- **Gameplay:** Features, mechanics, Red Alert compatibility
-- **Harvester AI:** Complete AI implementation (6 docs)
-- **Deployment:** Setup, Docker, testing
-- **Summaries:** Final reports and migration guides
+---
 
-**Quick Links:**
-- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** - Detailed quick start
-- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture
-- **[docs/FEATURES_RESTORED.md](docs/FEATURES_RESTORED.md)** - All features
-- **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment guide
-- **[docs/README.md](docs/README.md)** - 📚 Complete documentation index
+## 🏗️ Architecture
 
-### 🧪 Testing
-All test scripts are in **[tests/](tests/)** (4 scripts):
-- `test.sh` - Main test suite
-- `test_features.sh` - Feature-specific tests
-- `test_harvester_ai.py` - Harvester AI tests
-- `docker-test.sh` - Docker deployment tests
+### Tech Stack
 
-See **[tests/README.md](tests/README.md)** for usage guide.
+**Backend:**
+- **FastAPI** - Modern async web framework
+- **WebSockets** - Real-time bidirectional communication
+- **llama-cpp-python** - LLM inference engine
+- **Qwen2.5-Coder-1.5B** - Shared model for NL and AI analysis
 
----
+**Frontend:**
+- **Vanilla JavaScript** - No heavy frameworks
+- **HTML5 Canvas** - High-performance rendering
+- **CSS3** - Modern responsive UI
+- **WebSocket Client** - Real-time state synchronization
 
-## 🛠️ Outils (dev/debug/ops)
+**AI/ML:**
+- **Shared Model Manager** - Single LLM instance for efficiency
+- **Thread-safe queue system** - Sequential request processing
+- **Optimized for 2 vCPU** - HuggingFace Free tier compatible
+- **Fallback mechanisms** - Graceful degradation if LLM unavailable
 
-Les scripts utilitaires sont dans **[tools/](tools/)**:
-- `tools/debug_ai.py` — Utilitaires de débogage AI
-- `tools/local_run.sh` — Lancement local pratique
-- `tools/deploy_hf_spaces.sh` — Déploiement vers Hugging Face Spaces
+### Key Components
+
+```
+web/
+├── app.py                  # FastAPI server & game loop
+├── model_manager.py        # Shared LLM instance manager
+├── nl_translator.py        # Natural language → MCP commands
+├── ai_analysis.py          # Tactical analysis engine
+├── localization.py         # Multi-language support
+├── mcp_server.py           # MCP protocol server
+├── static/
+│   ├── game.js            # Game engine & rendering
+│   ├── nl_interface.js    # NL command interface
+│   └── styles.css         # UI styling
+├── backend/
+│   ├── constants.py       # Game constants
+│   └── app/              # Core game logic
+├── docs/                  # 📚 Documentation (28+ files)
+└── tests/                 # 🧪 Test scripts
+```
 
 ---
 
-## 🎮 Key Features
+## 🤖 AI Features Deep Dive
 
-✅ **Real-Time Strategy Gameplay**
-- Resource management (Tiberium harvesting)
-- Base building with power system
-- Unit production and combat
-- Fog of War
+### Shared Model Architecture
 
-✅ **Authentic C&C Experience**
-- GDI faction with classic units
-- Minimap with live updates
-- Construction yard, power plants, barracks, refineries
-- Infantry, tanks, and harvesters
+To optimize memory usage and CPU resources, both the **AI Analysis** and **NL Translator** share a single LLM instance:
 
-✅ **Web-Native**
-- No downloads or installations
-- Play directly in browser
-- Cross-platform compatible
-- Responsive UI
+- **Model**: Qwen2.5-Coder-1.5B (Q4_0 quantized, ~1GB RAM)
+- **Thread-safe**: Queue-based request handling
+- **Memory efficient**: 50% reduction vs. dual instances
+- **CPU optimized**: 1 thread (HuggingFace 2 vCPU environment)
+- **Fast response**: 128-256 token limits, 10-15s timeouts
 
-✅ **Multiplayer Ready** (Foundation)
-- WebSocket-based architecture
-- Real-time state synchronization
-- Scalable server design
+### Natural Language Translation Pipeline
 
----
+1. **User Input** → Natural language command in any language
+2. **LLM Processing** → Qwen2.5 translates to MCP-style JSON
+3. **Validation** → Command structure verified
+4. **Execution** → Converted to game actions
+5. **Feedback** → Success/error notification to user
 
-## 🎯 Controls
+**Supported Command Types:**
+- `MOVE_UNIT` - Move units to position
+- `BUILD_UNIT` - Train units from buildings
+- `BUILD_BUILDING` - Construct new structures
+- `ATTACK_UNIT` - Attack enemy units
+- `ATTACK_BUILDING` - Attack enemy structures
 
-| Action | Key/Mouse |
-|--------|-----------|
-| **Select unit/building** | Left Click |
-| **Move unit** | Right Click (ground) |
-| **Attack** | Right Click (enemy) |
-| **Box select** | Click + Drag |
-| **Build structure** | Click building button |
-| **Place building** | Click grid location |
-| **Change language** | Language buttons (top) |
+### AI Tactical Analysis
+
+The AI analyzer provides strategic insights by:
+1. **State Analysis**: Evaluates current game situation
+2. **Threat Detection**: Identifies immediate dangers
+3. **Resource Assessment**: Checks economic health
+4. **Strategic Planning**: Suggests next moves
+5. **Localization**: Presents analysis in user's language
+
+**Update Frequency**: Every 60 seconds (configurable)
 
 ---
 
-## 🌐 Multi-Language Support
+## 🔧 Performance Optimizations
+
+Optimized for **HuggingFace Free Tier** (2 vCPUs, 16GB RAM):
 
-- 🇬🇧 English
-- 🇫🇷 Français  
-- 🇹🇼 繁體中文
+### LLM Optimizations
+- **Threads**: 1 (instead of 4) to avoid CPU contention
+- **Batch size**: 128 for faster response times
+- **Context size**: 4096 tokens (balanced)
+- **Token limits**: 128-256 (fast responses)
+- **Timeouts**: 10-15s (prevents freezing)
 
-Switch language anytime with top-left buttons.
+### Game Loop Optimizations
+- **Tick rate**: 20 FPS (50ms per frame)
+- **State broadcast**: Only when connections exist
+- **AI analysis**: Every 60s (reduced from 30s)
+- **Debug logging**: Periodic (not per-frame)
+
+### Memory Management
+- **Shared model**: Single LLM instance (~1GB)
+- **Model caching**: Loads once, reused forever
+- **Process isolation**: Fallback if shared model busy
+- **Thread cleanup**: Automatic resource management
 
 ---
 
-## 🏗️ Tech Stack
+## 📊 Project Status
 
-**Backend:**
-- FastAPI (async web framework)
-- WebSockets (real-time communication)
-- Python 3.8+
+**Current Version**: 2.1  
+**Status**: ✅ Production Ready  
+**Deployment**: Live on HuggingFace Spaces
 
-**Frontend:**
-- Vanilla JavaScript
-- HTML5 Canvas (rendering)
-- CSS3 (UI styling)
+### Recent Updates (October 2025)
+
+✅ **Fixed critical bugs**:
+- Game loop now runs continuously (60 FPS maintained)
+- Unit movement working correctly
+- Production system functional
+- NL translator loads properly from /tmp/rts/
+
+✅ **Performance improvements**:
+- LLM optimized for 2 vCPU environment
+- Reduced thread count (4→1)
+- Shorter timeouts (30s→15s)
+- Smaller token limits (512→256)
+
+✅ **New features**:
+- Shared model manager (50% memory reduction)
+- Auto-retry for NL translator connection
+- Comprehensive debug logging
+- Periodic game tick confirmation
 
-**Game Engine:**
-- Custom JavaScript engine
-- Canvas-based rendering
-- WebSocket state sync
+### Known Limitations
+
+⚠️ **Single-player only** (multiplayer infrastructure ready but not enabled)  
+⚠️ **GDI faction only** (Nod not implemented)  
+⚠️ **Limited unit types** (infantry, tanks, helicopters, harvesters)  
+⚠️ **Basic AI opponent** (follows build queue, trains units, attacks)
 
 ---
 
-## 📦 Deployment
+## 📚 Documentation
 
-### Docker (Recommended)
+Complete documentation is available in **[docs/](docs/)** (28+ files):
 
-```bash
-docker build -t rts-web .
-docker run -p 8000:8000 rts-web
-```
+### Essential Docs
+- **[QUICKSTART.md](docs/QUICKSTART.md)** - Detailed getting started guide
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System design and structure
+- **[FEATURES_RESTORED.md](docs/FEATURES_RESTORED.md)** - All implemented features
+- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment instructions
+- **[MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md)** - Model Context Protocol
+
+### Recent Docs
+- **[NL_INTEGRATION_SUCCESS.md](docs/NL_INTEGRATION_SUCCESS.md)** - NL interface implementation
+- **[NL_UI_ARCHITECTURE_FIX.md](docs/NL_UI_ARCHITECTURE_FIX.md)** - Shared model architecture
+- **[CODE_CHANGES_NL_FIX.md](docs/CODE_CHANGES_NL_FIX.md)** - Bug fixes summary
 
-See **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** for complete deployment guide.
+### Full Index
+See **[docs/README.md](docs/README.md)** for complete documentation catalog.
 
 ---
 
 ## 🧪 Testing
 
-Run the test suite:
+Test scripts in **[tests/](tests/)** directory:
+
 ```bash
+# Run main test suite
 ./tests/test.sh
+
+# Test specific features
+./tests/test_features.sh
+
+# Test NL integration
+python tests/scripts/test_nl_integration.py
+
+# Test shared model
+python tests/test_shared_model.py
+
+# Docker deployment test
+./tests/docker-test.sh
 ```
 
-See **[tests/README.md](tests/README.md)** for all available tests.
+See **[tests/README.md](tests/README.md)** for detailed testing guide.
 
 ---
 
-## 📊 Project Status
+## 🐳 Docker Deployment
+
+### Quick Deploy
+
+```bash
+# Build image
+docker build -t rts-commander .
+
+# Run container
+docker run -p 7860:7860 rts-commander
 
-**Version:** 2.0 (Web)  
-**Status:** Production Ready ✅  
-**Rating:** 4.9/5 (97.3% feature parity with Pygame)
+# Access at http://localhost:7860
+```
+
+### HuggingFace Spaces
 
-**Compared to C&C Red Alert:**
-- 49% raw feature parity
-- 4.7/5 context-adjusted score
-- 3 aspects superior to Red Alert
+This project is configured for automatic deployment to HuggingFace Spaces:
 
-See full comparisons inside docs/ (if present).
+1. Model auto-downloads to `/tmp/rts/` on first run
+2. Optimized for 2 vCPU environment
+3. Automatic restart on push to main branch
+4. Health checks and monitoring included
 
 ---
 
-## 📜 License
+## 🛠️ Development Tools
+
+Scripts in **[tools/](tools/)** directory:
 
-MIT License - See LICENSE file for details.
+- `local_run.sh` - Quick local development server
+- `debug_ai.py` - AI debugging utilities
+- `deploy_hf_spaces.sh` - Deploy to HuggingFace Spaces
 
 ---
 
-## 🙏 Credits
+## 🤝 Contributing
+
+Contributions welcome! Areas for improvement:
 
-Inspired by **Command & Conquer: Tiberium Dawn** (Westwood Studios, 1995)
+- **New unit types** (aircraft, advanced vehicles)
+- **Nod faction** (buildings, units, technologies)
+- **More map variety** (different terrains, objectives)
+- **Multiplayer mode** (lobby, matchmaking)
+- **Campaign mode** (missions, story)
+- **Better AI** (strategic planning, tactics)
 
 ---
 
-## 🤖 MCP (Model Context Protocol) Integration
+## 📜 License
+
+MIT License - See [LICENSE](LICENSE) file for details.
 
-This project includes support for the Model Context Protocol (MCP), allowing AI agents to interact with the game programmatically.
+---
 
-### Features
+## 🙏 Credits
 
-- **Game State Access**: AI agents can retrieve the current game state
-- **Action Execution**: AI agents can perform actions in the game
-- **AI Analysis**: Access to tactical analysis from the built-in AI
-- **Documentation Access**: Provides game documentation as resources
+**Inspired by**: Command & Conquer: Tiberium Dawn (Westwood Studios, 1995)
 
-### Running the MCP Server
+**Powered by**:
+- [FastAPI](https://fastapi.tiangolo.com/) - Web framework
+- [Qwen2.5-Coder](https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct) - LLM model
+- [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) - LLM inference
+- [HuggingFace Spaces](https://huggingface.co/spaces) - Hosting platform
 
-```bash
-cd web
-python mcp_server.py
-```
+**Special Thanks**: To all contributors and players who provided feedback!
 
-The MCP server will start on port 8001.
+---
 
-### Documentation
+## 📞 Support
 
-See **[docs/MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md)** for detailed information about the MCP integration.
+- **Bug Reports**: Open an issue on the repository
+- **Feature Requests**: Start a discussion
+- **Questions**: Check the [docs/](docs/) first, then ask!
 
 ---
 
-**📚 Full Documentation:** [docs/](docs/)  
-**🧪 Test Scripts:** [tests/](tests/)
+**🎮 Ready to command your forces? [Play Now!](https://huggingface.co/spaces/Luigi/rts-commander)**
+
+*"In the grim darkness of the Tiberium future, there is only war... and natural language commands."* 🚀

README.old.md

@@ -0,0 +1,244 @@
+---
+title: RTS Commander
+emoji: 🎮
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+---
+
+# 🎮 Command & Conquer: Tiberium Dawn - Web Version
+
+A faithful recreation of the classic Command & Conquer: Tiberium Dawn in **pure web technologies** (FastAPI + WebSocket + Canvas).
+
+---
+
+## 📂 Project Structure
+
+```
+web/
+├── README.md           # This file
+├── app.py              # FastAPI server & WebSocket
+├── start.py            # Server launcher
+├── localization.py     # Multi-language support
+├── ai_analysis.py      # AI engine
+├── mcp_server.py       # MCP server integration
+├── backend/            # Game logic
+├── frontend/           # JavaScript game engine
+├── static/             # Assets (images, sounds)
+├── docs/               # 📚 Documentation
+├── tests/              # 🧪 Test scripts
+└── tools/              # 🛠️ Dev/debug/ops scripts
+```
+
+
+---
+
+## 🚀 Quick Start
+
+### Local Development
+
+1. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **Start the server:**
+   ```bash
+   python start.py
+   ```
+
+3. **Open in browser:**
+   ```
+   http://localhost:8000
+   ```
+
+---
+
+## 📖 Documentation
+
+### 📚 Complete Documentation
+All technical documentation is in **[docs/](docs/)** (28 files organized by category):
+- **Architecture:** System design, project structure
+- **Gameplay:** Features, mechanics, Red Alert compatibility
+- **Harvester AI:** Complete AI implementation (6 docs)
+- **Deployment:** Setup, Docker, testing
+- **Summaries:** Final reports and migration guides
+
+**Quick Links:**
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** - Detailed quick start
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture
+- **[docs/FEATURES_RESTORED.md](docs/FEATURES_RESTORED.md)** - All features
+- **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment guide
+- **[docs/README.md](docs/README.md)** - 📚 Complete documentation index
+
+### 🧪 Testing
+All test scripts are in **[tests/](tests/)** (4 scripts):
+- `test.sh` - Main test suite
+- `test_features.sh` - Feature-specific tests
+- `test_harvester_ai.py` - Harvester AI tests
+- `docker-test.sh` - Docker deployment tests
+
+See **[tests/README.md](tests/README.md)** for usage guide.
+
+---
+
+## 🛠️ Outils (dev/debug/ops)
+
+Les scripts utilitaires sont dans **[tools/](tools/)**:
+- `tools/debug_ai.py` — Utilitaires de débogage AI
+- `tools/local_run.sh` — Lancement local pratique
+- `tools/deploy_hf_spaces.sh` — Déploiement vers Hugging Face Spaces
+
+---
+
+## 🎮 Key Features
+
+✅ **Real-Time Strategy Gameplay**
+- Resource management (Tiberium harvesting)
+- Base building with power system
+- Unit production and combat
+- Fog of War
+
+✅ **Authentic C&C Experience**
+- GDI faction with classic units
+- Minimap with live updates
+- Construction yard, power plants, barracks, refineries
+- Infantry, tanks, and harvesters
+
+✅ **Web-Native**
+- No downloads or installations
+- Play directly in browser
+- Cross-platform compatible
+- Responsive UI
+
+✅ **Multiplayer Ready** (Foundation)
+- WebSocket-based architecture
+- Real-time state synchronization
+- Scalable server design
+
+---
+
+## 🎯 Controls
+
+| Action | Key/Mouse |
+|--------|-----------|
+| **Select unit/building** | Left Click |
+| **Move unit** | Right Click (ground) |
+| **Attack** | Right Click (enemy) |
+| **Box select** | Click + Drag |
+| **Build structure** | Click building button |
+| **Place building** | Click grid location |
+| **Change language** | Language buttons (top) |
+
+---
+
+## 🌐 Multi-Language Support
+
+- 🇬🇧 English
+- 🇫🇷 Français  
+- 🇹🇼 繁體中文
+
+Switch language anytime with top-left buttons.
+
+---
+
+## 🏗️ Tech Stack
+
+**Backend:**
+- FastAPI (async web framework)
+- WebSockets (real-time communication)
+- Python 3.8+
+
+**Frontend:**
+- Vanilla JavaScript
+- HTML5 Canvas (rendering)
+- CSS3 (UI styling)
+
+**Game Engine:**
+- Custom JavaScript engine
+- Canvas-based rendering
+- WebSocket state sync
+
+---
+
+## 📦 Deployment
+
+### Docker (Recommended)
+
+```bash
+docker build -t rts-web .
+docker run -p 8000:8000 rts-web
+```
+
+See **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** for complete deployment guide.
+
+---
+
+## 🧪 Testing
+
+Run the test suite:
+```bash
+./tests/test.sh
+```
+
+See **[tests/README.md](tests/README.md)** for all available tests.
+
+---
+
+## 📊 Project Status
+
+**Version:** 2.0 (Web)  
+**Status:** Production Ready ✅  
+**Rating:** 4.9/5 (97.3% feature parity with Pygame)
+
+**Compared to C&C Red Alert:**
+- 49% raw feature parity
+- 4.7/5 context-adjusted score
+- 3 aspects superior to Red Alert
+
+See full comparisons inside docs/ (if present).
+
+---
+
+## 📜 License
+
+MIT License - See LICENSE file for details.
+
+---
+
+## 🙏 Credits
+
+Inspired by **Command & Conquer: Tiberium Dawn** (Westwood Studios, 1995)
+
+---
+
+## 🤖 MCP (Model Context Protocol) Integration
+
+This project includes support for the Model Context Protocol (MCP), allowing AI agents to interact with the game programmatically.
+
+### Features
+
+- **Game State Access**: AI agents can retrieve the current game state
+- **Action Execution**: AI agents can perform actions in the game
+- **AI Analysis**: Access to tactical analysis from the built-in AI
+- **Documentation Access**: Provides game documentation as resources
+
+### Running the MCP Server
+
+```bash
+cd web
+python mcp_server.py
+```
+
+The MCP server will start on port 8001.
+
+### Documentation
+
+See **[docs/MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md)** for detailed information about the MCP integration.
+
+---
+
+**📚 Full Documentation:** [docs/](docs/)  
+**🧪 Test Scripts:** [tests/](tests/)