diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0c28f69
--- /dev/null
+++ b/README.md
@@ -0,0 +1,328 @@
+# 🎛️ AbletonMCP_AI v3.0 - Senior Architecture
+
+[![Gitea](https://img.shields.io/badge/Gitea-renato97%2FAbletonMCP_AI-blue?style=flat-square&logo=gitea)](https://gitea.cbcren.online/renato97/AbletonMCP_AI)
+[![Python](https://img.shields.io/badge/Python-3.7%2B-yellow?style=flat-square&logo=python)](https://python.org)
+[![Ableton](https://img.shields.io/badge/Ableton%20Live-12%20Suite-black?style=flat-square&logo=ableton)](https://www.ableton.com)
+[![Status](https://img.shields.io/badge/Status-Production%20Ready-green?style=flat-square)]()
+[![License](https://img.shields.io/badge/License-MIT-orange?style=flat-square)]()
+
+> **MCP-based AI system for professional music production in Ableton Live 12 Suite**
+>
+> *100% prompt-based music creation. No manual steps required.*
+
+---
+
+## ✨ What is AbletonMCP_AI?
+
+AbletonMCP_AI is an **AI-powered music production system** that lets you create complete professional tracks in Ableton Live using **natural language prompts only**.
+
+**No clicking. No dragging samples. No manual mixing.** Just describe what you want, and the AI does everything:
+- 🥁 Creates drum patterns (dembow, trap, perreo)
+- 🎹 Generates basslines, chords, and melodies
+- 🎚️ Applies professional mixing and mastering
+- 📀 Places everything in Arrangement View
+
+---
+
+## 🚀 Quick Example
+
+```
+"Reggaeton perreo intenso, 95 BPM, Am, drumloop gata como protagonista, 
+1 minuto 30 segundos, bass y chords acompañando"
+```
+
+**Result:** Complete 1:38 track with 204 audio clips, 7 tracks, professionally mixed.
+
+---
+
+## 🏗️ Architecture v3.0 (Senior)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  AI Agent (OpenCode / Claude / Kimi)                        │
+│  ↓ Natural language prompts                                  │
+├─────────────────────────────────────────────────────────────┤
+│  MCP Server (FastMCP, stdio)                                 │
+│  ↓ JSON commands                                             │
+├─────────────────────────────────────────────────────────────┤
+│  50+ Production Engines                                      │
+│  ├── 🥁 Drum Layer Engine                                    │
+│  ├── 🎸 Bass/Chords/Melody Generators                      │
+│  ├── 🎛️ Mixing & Mastering (EQ, Compression, Bus)          │
+│  ├── 🎯 Coherence Validator                                  │
+│  └── 🔥 Intelligent Sample Selector (375+ samples)           │
+├─────────────────────────────────────────────────────────────┤
+│  LiveBridge (TCP Socket → Ableton Live API)                  │
+│  ↓ Real-time clip creation                                   │
+├─────────────────────────────────────────────────────────────┤
+│  Ableton Live 12 Suite ←── 🎵 Arrangement View               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📦 Key Features
+
+### 🎵 Music Generation
+| Feature | Description |
+|---------|-------------|
+| **Dembow Generator** | Classic reggaeton rhythm with variations |
+| **Bass Engine** | Reese bass, sub-bass, melodic patterns |
+| **Chord Progressions** | i-v-vi-iv and custom progressions |
+| **Melody Engine** | Scale-based with motivic development |
+| **Texture Layers** | Pads, ambience, FX |
+
+### 🎚️ Professional Mixing
+| Feature | Description |
+|---------|-------------|
+| **Bus Architecture** | Kick, Snare, Drums, Bass, Synths, FX buses |
+| **Parallel Compression** | NY-style compression for punch |
+| **EQ Presets** | Extended 15+ presets (kick_sub, bass_glue, etc.) |
+| **Auto Gain Staging** | Automatic level balancing |
+| **Master Chain** | Professional mastering preset |
+
+### 🔬 Smart Selection
+| Feature | Description |
+|---------|-------------|
+| **Coherence Scoring** | Ensures samples work together (0.90+ threshold) |
+| **Metadata Store** | SQLite database of 375+ analyzed samples |
+| **Spectral Analysis** | MFCC, RMS, spectral centroid matching |
+| **Variation Engine** | Different samples per section |
+
+---
+
+## 🛠️ Installation
+
+### 1. Clone Repository
+```bash
+git clone https://gitea.cbcren.online/renato97/AbletonMCP_AI.git
+cd AbletonMCP_AI
+```
+
+### 2. Configure Ableton Live
+1. Open **Ableton Live 12 Suite**
+2. Go to **Preferences → Link/Tempo/MIDI**
+3. Under **Control Surfaces**, add **AbletonMCP_AI**
+4. The script auto-starts on TCP port 9877
+
+### 3. Configure OpenCode
+Edit `~/.config/opencode/opencode.json`:
+```json
+{
+  "mcp": {
+    "ableton-live-mcp": {
+      "type": "local",
+      "command": ["python", "C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py"],
+      "enabled": true,
+      "timeout": 300000
+    }
+  }
+}
+```
+
+### 4. Sample Library
+Place your samples in `libreria/reggaeton/`:
+```
+libreria/
+└── reggaeton/
+    ├── kick/
+    ├── snare/
+    ├── hihat/
+    ├── bass/
+    ├── chords/
+    ├── melody/
+    ├── fx/
+    └── drumloops/
+```
+
+---
+
+## 🎮 Available Tools (96+)
+
+### Project Info
+- `get_session_info` - Tempo, tracks, scenes, playback state
+- `get_tracks` / `get_scenes` - List all elements
+- `get_arrangement_clips` - Timeline content
+- `get_master_info` - Master track settings
+
+### Transport & Settings
+- `start_playback` / `stop_playback` / `toggle_playback`
+- `set_tempo` (20-300 BPM) / `set_time_signature` / `set_metronome`
+
+### Tracks & Mixing
+- `create_midi_track` / `create_audio_track`
+- `set_track_volume` / `set_track_pan` / `set_track_mute` / `set_track_solo`
+- `create_bus_track` / `route_track_to_bus`
+- `configure_eq` / `configure_compressor` / `setup_sidechain`
+
+### Clip Creation
+- `create_clip` - MIDI clips in Session View
+- `add_notes_to_clip` - Add MIDI note data
+- `create_arrangement_audio_pattern` - Load audio files to timeline
+- `load_sample_to_clip` / `load_sample_to_drum_rack`
+
+### 🎯 **AI Generation (The Good Stuff)**
+- `generate_intelligent_track` - One-prompt complete track
+- `generate_expansive_track` - 12+ samples per category
+- `build_song` - Full arrangement with sections
+- `produce_reggaeton` - Complete reggaeton production
+- `produce_from_reference` - Match reference audio style
+
+### Advanced
+- `create_riser` / `create_downlifter` / `create_impact` - FX generation
+- `automate_filter` / `generate_curve_automation` - Parameter automation
+- `humanize_track` - Velocity/timing variations
+- `apply_professional_mix` - Complete mix chain
+
+---
+
+## 📂 Project Structure
+
+```
+AbletonMCP_AI/
+├── 📄 __init__.py              # Remote Script entry (~6500 lines)
+├── 📄 runtime.py              # TCP server runtime
+├── 📁 mcp_server/
+│   ├── 📄 server.py           # MCP FastMCP server
+│   ├── 📄 integration.py      # Senior Architecture coordinator
+│   └── 📁 engines/
+│       ├── 📄 sample_selector.py       # Smart sample selection
+│       ├── 📄 song_generator.py        # Track generation
+│       ├── 📄 arrangement_recorder.py  # Session→Arrangement
+│       ├── 📄 live_bridge.py           # Live API execution
+│       ├── 📄 mixing_engine.py         # Professional mixing
+│       ├── 📄 metadata_store.py        # SQLite sample DB
+│       ├── 📄 massive_selector.py      # 330+ sample selection
+│       ├── 📄 coherence_system.py      # Compatibility validation
+│       └── 📄 ... (50+ more engines)
+├── 📁 docs/
+│   ├── 📄 skill_produccion_audio.md    # Production skills
+│   ├── 📄 skill_reinicio_ableton.md    # Restart procedures
+│   ├── 📄 WORKFLOW_REGGAETON.md        # Reggaeton workflow
+│   └── 📄 API_REFERENCE_PRO.md         # Complete API docs
+├── 📁 examples/
+│   └── 📄 professional_production.py   # Usage examples
+└── 📁 presets/
+    └── 📄 *.json                        # Saved configurations
+
+mcp_wrapper.py               # Launcher script
+AGENTS.md                    # Agent instructions
+CLAUDE.md / QWEN.md         # Per-agent guides
+```
+
+---
+
+## 🧪 Testing
+
+### Compile Check
+```powershell
+python -m py_compile "AbletonMCP_AI\__init__.py"
+python -m py_compile "AbletonMCP_AI\mcp_server\server.py"
+```
+
+### Health Check
+```python
+# Run in OpenCode
+ableton-live-mcp_health_check()
+```
+
+Expected: Score 5/5 (all systems operational)
+
+---
+
+## 🎵 Production Workflow Example
+
+```python
+# 1. Health check
+ableton-live-mcp_health_check()
+
+# 2. Generate complete track
+ableton-live-mcp_generate_intelligent_track(
+    description="reggaeton perreo intenso 95bpm Am drumloop gata",
+    structure_type="short",
+    variation_level="high",
+    coherence_threshold=0.90
+)
+
+# 3. Get arrangement status
+ableton-live-mcp_get_arrangement_status()
+
+# 4. Apply professional mix
+ableton-live-mcp_apply_professional_mix(
+    track_assignments='{"21": "drumloop", "22": "bass", "23": "chords"}'
+)
+
+# 5. Export
+ableton-live-mcp_render_full_mix(output_path="C:\\temp\\track.wav")
+```
+
+---
+
+## 🔧 Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Connection refused | Check Ableton has AbletonMCP_AI loaded in Preferences |
+| Port 9877 blocked | Run: `netstat -an \| findstr 9877` |
+| Changes not reflecting | Restart Ableton (delete `CrashRecoveryInfo.cfg` first) |
+| Sample selection empty | Verify `libreria/reggaeton/` has .wav files |
+| Timeout on generation | Check Ableton log for errors |
+
+---
+
+## 📊 Project Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total Files | 119 |
+| Lines of Code | ~90,000 |
+| Python Engines | 50+ |
+| MCP Tools | 96+ |
+| Documentation | 30+ pages |
+| Sample Library | 375+ analyzed |
+| Presets | 7 saved |
+
+---
+
+## 📝 Changelog
+
+### v3.0 - Senior Architecture (Current)
+- ✅ Arrangement-first workflow (no Session View intermediate)
+- ✅ SQLite metadata store (no numpy for queries)
+- ✅ 50+ production engines
+- ✅ Professional mixing chains
+- ✅ VST plugin support
+
+### v2.0 - Clean Rewrite
+- ✅ Simplified architecture
+- ✅ FastMCP stdio transport
+- ✅ TCP socket per command
+
+---
+
+## 🤝 Credits
+
+- **Architecture:** Senior v3.0 (Arrangement-first)
+- **AI Agents:** Kimi K2 (coding), Qwen (validation)
+- **Platform:** Ableton Live 12 Suite
+- **Protocol:** Model Context Protocol (MCP)
+
+---
+
+## 📜 License
+
+MIT License - See LICENSE file for details.
+
+---
+
+## 🔗 Links
+
+- **Repository:** https://gitea.cbcren.online/renato97/AbletonMCP_AI
+- **Ableton:** https://www.ableton.com
+- **MCP Docs:** https://modelcontextprotocol.io
+
+---
+
+<p align="center">
+  <strong>🎛️ Produce music with your voice. No limits. 🎵</strong>
+</p>