Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

KIMI_K2_START_HERE.md

@@ -0,0 +1,155 @@
+# Kimi K2 Start Here
+
+Si eres Kimi K2, no empieces a editar codigo hasta leer este archivo completo.
+
+Este proyecto tiene codigo activo, codigo legacy y docs viejas. Si eliges el archivo equivocado, vas a perder tiempo o romper Ableton.
+
+## Orden obligatorio de lectura
+
+Lee en este orden:
+
+1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_START_HERE.md`
+2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\CLAUDE.md`
+3. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_ACTIVE_HANDOFF.md`
+4. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\ROADMAP.md`
+5. solo despues de eso abrir codigo
+
+No uses primero `KIMI_K2_CODEBASE_FIXES.md`.
+No uses primero `KIMI_K2_NOTE_API_FIX.md`.
+Esos documentos quedan como contexto historico y contienen partes viejas.
+
+## Que es este proyecto
+
+Es un sistema para controlar Ableton Live 12 desde MCP.
+
+Tiene tres capas:
+
+- wrapper MCP y configuracion de clientes
+- MCP server con tools y logica musical
+- Remote Script dentro de Ableton Live
+
+## Verdad actual del proyecto
+
+### MCP activo
+
+- wrapper:
+  `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
+- server real:
+  `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
+
+### Runtime activo en Ableton
+
+- shim:
+  `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py`
+- shim espejo:
+  `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py`
+- runtime canonico:
+  `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
+
+Importante:
+
+- hoy los shims cargan primero `abletonmcp_init.py`
+- el backup solo queda como fallback
+- no asumas que el backup es el runtime principal
+
+### Libreria privada del usuario
+
+No esta en el repo, pero el codigo la usa localmente:
+
+`C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton`
+
+### Ejecutable real de Ableton
+
+`C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe`
+
+## Que ya esta arreglado
+
+- `AbletonMCP_AI` aparece como Control Surface.
+- el wrapper MCP funciona por `stdio`.
+- `server.py` ya no tiene tools duplicadas.
+- el runtime canonico es el primero en la ruta activa.
+- existe fallback de audio en Arrangement.
+- existe `pack_brain` para elegir material mas coherente.
+- existe `docs/ROADMAP.md` con prioridades reales.
+- existe `docs/REFERENCE_TRACK_EJEMPLO_ANALYSIS.md` con una referencia real que ya fue analizada.
+- existe `docs/REFERENCE_TRACK_EJEMPLO_MICRO_STEMS.md` con el destripe fino de esa referencia.
+- existe `docs/MICRO_STEMS_APPROACH.md` explicando el cableado nuevo.
+
+## Que sigue roto o flojo
+
+- `clear_all_tracks` devuelve error blando al final de la limpieza
+- Z.ai puede responder `429`
+- `atmos_fx` y `vocal_shot` todavia pueden salir flojos
+- el sistema sigue siendo audio-first para remakes de referencia
+- si el hook correcto vive en `MIDI` o presets, hoy todavia puede no aparecer
+- la automatizacion real dentro de Live sigue incompleta
+- el sistema aun no renderiza, escucha y rerrollea automaticamente
+- las ultimas generaciones pueden sonar como capas y loops sin una identidad musical clara
+
+## Primer sprint que debes hacer
+
+Haz esto en este orden:
+
+1. leer `docs/REFERENCE_TRACK_EJEMPLO_ANALYSIS.md`
+2. leer `docs/CONSOLIDADO_v0.1.8_PARA_CODEX.md`
+3. seguir `docs/SPRINT_v0.1.10_NEXT.md`
+4. hacer que la generacion use un hook armonico real, no solo loops
+5. bajar cantidad de capas y tracks opcionales
+6. validar el resultado con una generacion real y comparacion simple contra la referencia
+
+No abras un frente nuevo antes de cerrar el anterior.
+
+## Reglas duras
+
+- usa PowerShell, no bash
+- usa rutas absolutas de Windows
+- compila antes de probar runtime
+- valida con logs y socket, no con intuicion
+- no declares exito sin verificar `get_session_info`
+- no edites el backup salvo que estes reparando el fallback
+- no crees otro server o wrapper
+- no uses docs viejas que contradigan el runtime actual
+
+## Comandos minimos antes de tocar codigo
+
+Compilar:
+
+```powershell
+python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"
+python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
+python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
+```
+
+Ver si Live escucha:
+
+```powershell
+netstat -an | findstr 9877
+```
+
+Ver log de Ableton:
+
+```powershell
+Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
+```
+
+## Si estas confundido
+
+No adivines.
+
+Haz esto:
+
+1. confirma el entrypoint activo
+2. confirma el runtime cargado
+3. confirma si el puerto 9877 esta escuchando
+4. confirma si el bug esta en MCP o en Live
+5. recien ahi parchea
+
+## Repositorio publicado
+
+Repo canonico:
+
+`https://gitea.cbcren.online/renato97/ableton-mcp-ai`
+
+Roadmap canonico:
+
+`docs/ROADMAP.md`