docs: add Kimi K2 onboarding handoff

KIMI_K2_ACTIVE_HANDOFF.md

@@ -0,0 +1,203 @@
+# Kimi K2 Active Handoff
+
+Este es el handoff activo y actualizado.
+
+Si otro documento contradice este, usa este archivo y despues valida con codigo y runtime.
+
+## Estado real a 2026-03-30
+
+### Arquitectura activa
+
+- Cliente MCP -> `mcp_wrapper.py` -> `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/server.py`
+- Ableton Live -> `AbletonMCP_AI/__init__.py` -> `abletonmcp_init.py`
+- `_Framework/` contiene el shim minimo para que el runtime no dependa de imports rotos
+
+### Verificaciones hechas
+
+- `server.py` tiene `89` tools y `89` nombres unicos
+- los shims de `AbletonMCP_AI` cargan primero `abletonmcp_init.py`
+- el repo publicado ya existe y tiene `README`, `ROADMAP`, `KNOWN_ISSUES` y `TODO`
+
+### Lo que funciona
+
+- MCP por `stdio`
+- Control Surface `AbletonMCP_AI`
+- `get_session_info` y `get_tracks` cuando Live esta abierto
+- generacion de cancion con fallback de audio en Arrangement
+- selecciones mas coherentes para reggaeton que antes
+
+### Lo que sigue flojo
+
+- `clear_all_tracks` limpia casi todo pero termina con error blando
+- Z.ai devuelve `429` a veces
+- falta same-pack estricto en algunos roles
+- falta groove real derivado desde loops
+- falta critica cerrada sobre audio renderizado
+- falta automatizacion real robusta dentro del runtime
+
+## Archivos que Kimi debe mirar primero
+
+### Entrada MCP
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
+
+### Runtime de Live
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py`
+
+### Logica musical
+
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_manager.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\pack_brain.py`
+- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\zai_judges.py`
+
+## Tareas inmediatas explicadas para Kimi
+
+### 1. Arreglar `clear_all_tracks`
+
+Problema:
+
+- al limpiar la sesion, el runtime devuelve `"Couldn't delete track."`
+- aun asi deja casi todo limpio
+
+Objetivo:
+
+- limpiar sin error final
+- dejar exactamente el estado esperado despues del reset
+
+Archivos probables:
+
+- `abletonmcp_init.py`
+- `AbletonMCP_AI/abletonmcp_runtime.py`
+
+Validacion:
+
+- ejecutar limpieza dos veces seguidas sin crash
+- `get_session_info` debe responder con cantidad consistente de tracks
+
+### 2. Backoff, retry y cache para Z.ai
+
+Problema:
+
+- el selector usa jueces externos
+- Z.ai puede responder `429`
+- si no hay amortiguacion, la calidad del ranking cae
+
+Objetivo:
+
+- reintentos cortos con backoff
+- cache local de decisiones por prompt/palette
+- fallback heuristico limpio si la API falla
+
+Archivo principal:
+
+- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/zai_judges.py`
+
+Validacion:
+
+- si Z.ai falla, el sistema no debe romper generacion
+- si el mismo prompt se repite, el cache debe evitar llamadas innecesarias
+
+### 3. Same-pack estricto para `atmos_fx` y `vocal_shot`
+
+Problema:
+
+- esos roles todavia pueden salir bien aislados pero mal integrados al mismo universo sonoro
+
+Objetivo:
+
+- si existe opcion buena dentro del mismo pack musical principal, usarla primero
+- solo salir del pack si no hay candidato valido
+
+Archivos principales:
+
+- `server.py`
+- `sample_selector.py`
+- `pack_brain.py`
+
+Validacion:
+
+- inspeccionar paths elegidos en una generacion de prueba
+- confirmar que `atmos_fx` y `vocal_shot` vienen del mismo entorno del pack principal cuando sea posible
+
+### 4. Groove extraction desde dembow loops
+
+Problema:
+
+- el ritmo actual es mejor que antes, pero todavia es demasiado reglado
+
+Objetivo:
+
+- leer transientes, densidad y acentos desde loops reales de dembow
+- usar eso para posicionar kicks, claps y hats
+
+Archivos probables:
+
+- `audio_analyzer.py`
+- `song_generator.py`
+- `server.py`
+
+Validacion:
+
+- los patrones generados deben parecer menos mecanicos
+- no deben volver al feel house straight
+
+### 5. Smoke test de generacion async
+
+Problema:
+
+- hoy la generacion larga puede verse como timeout desde algunos clientes
+
+Objetivo:
+
+- un test corto que lance job async, haga poll y verifique estado final
+
+Archivos probables:
+
+- `server.py`
+- script de prueba nuevo o reutilizable
+
+Validacion:
+
+- job creado
+- job termina
+- `get_generation_job_status` devuelve resultado util
+
+## Reglas para no romper cosas
+
+- no toques primero scripts legacy de root si el bug esta en el runtime o en `server.py`
+- no tomes `KIMI_K2_CODEBASE_FIXES.md` como verdad total; tiene partes historicas
+- no tomes `KIMI_K2_NOTE_API_FIX.md` salvo si el bug actual es escritura de notas MIDI
+- no declares exito por un string bonito; valida con runtime
+- no uses bash ni rutas `/c/...`
+
+## Bucle de trabajo recomendado
+
+1. leer `KIMI_K2_START_HERE.md`
+2. leer `CLAUDE.md`
+3. confirmar archivo activo
+4. editar solo el archivo correcto
+5. compilar
+6. recargar Control Surface o reiniciar Live si hace falta
+7. validar con `get_session_info`, `get_tracks` y log
+8. documentar que cambio y que sigue faltando
+
+## Si el puerto 9877 no responde
+
+No declares bug del MCP automaticamente.
+
+Primero verifica:
+
+- Ableton abierto
+- `AbletonMCP_AI` seleccionado en `Control Surface`
+- log de Ableton sin crash
+- `netstat -an | findstr 9877`
+
+Si eso falla, el problema puede ser del runtime de Live, no del wrapper MCP.