# 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`