docs: add Kimi K2 onboarding handoff

CLAUDE.md

@@ -26,8 +26,10 @@ The goal is to operate Ableton Live 12 through MCP and a Remote Script so an AI
 Read in this order before doing substantial work:
 
 1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\CLAUDE.md`
-2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_CODEBASE_FIXES.md`
+2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_START_HERE.md`
-3. inspect the active entrypoints and code directly
+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. inspect the active entrypoints and code directly
 
 Do not trust stale docs over live code.
 Do not trust live code over runtime evidence.
@@ -74,10 +76,10 @@ Verified executable paths:
 
 Important:
 
-- those shims currently prefer `AbletonMCP_AI_BAK_20260328_200801\Remote_Script.py`
+- those shims currently prefer `abletonmcp_init.py`
-- they only fall back to `abletonmcp_init.py`
+- the backup runtime only remains as fallback
 
-This means MCP and Ableton Live are not currently using a single implementation.
+This means the canonical runtime is now the root `abletonmcp_init.py`.
 
 ## Source Of Truth Rules
 
@@ -213,12 +215,14 @@ As of the latest audit:
 
 - Claude Code and opencode can connect to the MCP
 - Ableton can load the `AbletonMCP_AI` Control Surface
-- `generate_track` can still push Live into `Audio queue timeout`
+- `server.py` currently exposes unique tools without duplicate registrations
+- the active runtime path now points to `abletonmcp_init.py` first
+- `generate_song` can materialize audio fallback in Arrangement
 - `server_v2.py` does not compile
-- `server.py` contains duplicated MCP tools
+- `clear_all_tracks` still has a soft failure at the end of cleanup
-- the backup runtime is still in the active load path
+- Z.ai can return `429` and force fallback heuristics
 
-If your task involves repairs, read `KIMI_K2_CODEBASE_FIXES.md` immediately after this file.
+If your task involves repairs, read `KIMI_K2_START_HERE.md` and `KIMI_K2_ACTIVE_HANDOFF.md` immediately after this file.
 
 ## Fast Diagnostic Checklist
 

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.

KIMI_K2_CODEBASE_FIXES.md

@@ -1,5 +1,22 @@
 # Kimi K2 Handoff: Codigo Fuente y Qué Hay Que Arreglar
 
+IMPORTANT:
+
+Read these files first:
+
+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\KIMI_K2_ACTIVE_HANDOFF.md`
+
+This document is now historical context.
+
+Some statements below are outdated because the project moved forward.
+Examples of things that changed after this document was written:
+
+- the active runtime now prefers `abletonmcp_init.py`
+- `server.py` no longer has duplicate MCP tool registrations
+
+Use this file for background only, not as the first source of truth.
+
 ## Objetivo
 
 Este documento es un handoff tecnico para que Kimi K2 pueda entrar al proyecto sin perder tiempo en arboles duplicados ni archivos muertos. El foco es el codigo fuente que afecta al MCP, al Remote Script de Ableton y a la generacion musical.

KIMI_K2_NOTE_API_FIX.md

@@ -1,5 +1,16 @@
 # Kimi K2 Handoff: Fix del Error `Clip.add_new_note`
 
+IMPORTANT:
+
+Do not start from this file unless the current bug is specifically about MIDI note writing.
+
+Read first:
+
+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\KIMI_K2_ACTIVE_HANDOFF.md`
+
+This document is a specialized handoff for one bug family only.
+
 ## Estado General
 
 Kimi avanzo parte importante del handoff anterior. Verificado en disco:

KIMI_K2_START_HERE.md

@@ -0,0 +1,148 @@
+# 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.
+
+## 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
+- la automatizacion real dentro de Live sigue incompleta
+- el sistema aun no renderiza, escucha y rerrollea automaticamente
+
+## Primer sprint que debes hacer
+
+Haz esto en este orden:
+
+1. arreglar `clear_all_tracks`
+2. agregar backoff + retry + cache a Z.ai
+3. endurecer `atmos_fx` y `vocal_shot` con same-pack estricto
+4. extraer groove real desde drum loops dembow
+5. dejar smoke test de generacion async
+
+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`

README.md

@@ -26,6 +26,10 @@ Sistema MCP + Remote Script para controlar Ableton Live 12 desde clientes tipo C
   Launcher estable para clientes MCP por `stdio`.
 - `CLAUDE.md`
   Documentacion operativa para agentes.
+- `KIMI_K2_START_HERE.md`
+  Entrada minima y obligatoria para Kimi K2.
+- `KIMI_K2_ACTIVE_HANDOFF.md`
+  Handoff activo, simple y actualizado.
 - `MCP_CLAUDE_OPENCODE_SETUP.md`
   Setup puntual para Claude Code y opencode.
 - `docs/KNOWN_ISSUES.md`
@@ -121,6 +125,8 @@ El sistema usa fallback heuristico si la API no responde o devuelve rate limit.
 ## Documentacion adicional
 
 - `CLAUDE.md`
+- `KIMI_K2_START_HERE.md`
+- `KIMI_K2_ACTIVE_HANDOFF.md`
 - `MCP_CLAUDE_OPENCODE_SETUP.md`
 - `KIMI_K2_CODEBASE_FIXES.md`
 - `KIMI_K2_NOTE_API_FIX.md`