chocolatito-code 1.6.6 → 1.6.8

package/README.md

@@ -1,341 +1,437 @@
-# 🦊 Chocolatito Code (v1.0.0)
-
-> **Agente Autónomo de Programación para la Terminal**, desarrollado por **Chocolatito** con la arquitectura del **Motor Espectro**.
-
----
-
-## ⚡ Niveles de Potencia y Esfuerzo (/effort)
-
-Chocolatito Code te permite regular dinámicamente la profundidad y potencia del motor según la complejidad de la tarea:
-
-| Nivel | Nombre | Nivel de Esfuerzo | Uso Recomendado |
-| :--- | :--- | :---: | :--- |
-| Nivel | Modelo real | Uso recomendado |
-| :--- | :--- | :--- |
-| **`1.0`** Ágil | `deepseek-v4-flash` | Tareas cotidianas, funciones y scripts directos. |
-| **`1.5`** Avanzado | `deepseek-v4-flash` | Refactorizaciones, con más margen creativo. |
-| **`2.0`** Razonamiento Pro | `deepseek-v4-pro` | Bugs difíciles, algoritmos y arquitectura. |
-| **`2.5`** MAX | `deepseek-v4-pro` | Proyectos completos y exploración amplia. |
-
-Ventana de contexto: **1.000.000 de tokens** en los cuatro niveles.
-
-Para cambiar de nivel dentro de la sesión, escribe:
-```bash
-/effort 2.0
-```
-
----
-
-## 🛠️ Herramientas Nativas Autónomas
-
-- 👁️ `view_file`: Lectura precisa con numeración de líneas.
-- ✏️ `edit_file`: Modificación de código con diffs visuales tipo Git (verde/rojo).
-- 📄 `write_file`: Creación y sobreescritura de archivos y directorios.
-- 💻 `run_command`: Ejecución de comandos en PowerShell/Bash con captura de logs.
-- 📂 `list_dir`: Exploración de proyectos respetando `.gitignore`.
-- 🔍 `grep_search`: Búsqueda instantánea de texto y regex.
-- 🌐 `chrome`: Controla **tu** Chrome desde dentro, con tus sesiones iniciadas y en segundo
-  plano real (requiere la extensión: ver `extension/README.md`).
-- 🖥️ `computer_use`: Aplicaciones de escritorio por árbol de accesibilidad, sin adivinar píxeles.
-- 🧭 `browser`: Navegador propio por CDP, para webs públicas y `localhost`.
-
-Las lecturas independientes lanzadas en el mismo turno se ejecutan **en paralelo**.
-
-## 🗺️ Mapa del repositorio
-
-Al arrancar, el agente recibe un índice de los símbolos del proyecto ordenado por **cuánto los
-usa el resto del código** (un PageRank sobre el grafo de referencias, con presupuesto de 4.000
-tokens). Sirve para que sepa qué existe y dónde mirar sin gastar turnos en `grep_search`
-buscando a ciegas.
-
-Son nombres y números de línea, no contenido: antes de editar sigue leyendo el archivo.
-
-Lo que escribes también cuenta. Si dices *"arregla calcularImpuesto"* o *"falla en loop.ts"*, se
-detecta la referencia aunque no pongas `@` y se le pasan las rutas —solo las rutas, no el
-contenido, que cuesta más contexto del que ahorra.
-
-## ✅ Verificación automática tras editar
-
-Cuando un turno escribe en disco, Chocolatito puede correr el verificador del proyecto y
-devolverle el error al agente **en el mismo turno**, en vez de dar el trabajo por bueno y que el
-fallo aparezca tres turnos después.
-
-Viene **apagada**: correr un comando del proyecto es ejecutar código, y eso se pide. Para
-activarla, en `.chocolatito/settings.json` (del proyecto o global en `~/.chocolatito/`):
-
-```json
-{
-  "verify": { "auto": true },
-  "limits": { "maxIterations": 60, "subagentIterations": 20 }
-}
-```
-
-También con variables de entorno: `CHOCOLATITO_AUTO_VERIFY=1`, `CHOCOLATITO_VERIFY_CMD`,
-`CHOCOLATITO_MAX_ITERATIONS`, `CHOCOLATITO_SUBAGENT_ITERATIONS`.
-
-El comando se detecta solo, en este orden: `npm run typecheck` → `lint` → `check` → `build`, o
-`npx tsc --noEmit`, `cargo check`, `go build ./...`. **Nunca los tests**: un `npm test` puede
-levantar servidores o tardar minutos, y verificar no puede significar eso. Con `verify.command`
-pones el tuyo. Si falla, el agente tiene tres intentos para arreglarlo; al cuarto para y te lo
-dice.
-
-## ↻ Cuando el agente se atasca
-
-Si repite tres veces la misma llamada con el mismo resultado, se para y pregunta: le dejas
-seguir, o le dices que cambie de enfoque. Sin terminal (CI, `chocolatito "haz X"`) se corta
-solo, para que un bucle que nadie está mirando no se coma la cuota.
-
-## 🧩 VSCode
-
-Si tienes la extensión instalada y abres `chocolatito` en la terminal integrada, **se conecta
-solo**. No hay nada que configurar.
-
-El truco está al revés de lo que parece: la extensión es un **servidor MCP** y el agente es el
-cliente. Cada ventana de VSCode levanta un servidor en `127.0.0.1` y deja una ficha en
-`~/.chocolatito/ide/` con su puerto, su token y la carpeta que tiene abierta. El agente busca la
-ficha cuya carpeta contiene su directorio de trabajo.
-
-Lo que gana el agente (lo único que no puede tener por su cuenta):
-
-| Herramienta | Para qué |
-| --- | --- |
-| `diagnosticos` | Los errores del servidor de lenguaje. Los subrayados rojos, sin esperar a compilar. |
-| `seleccion_actual` | Qué archivo tienes abierto y qué has seleccionado. Hace que «arregla esto» signifique algo. |
-| `archivos_abiertos` | Las pestañas abiertas, en orden. |
-| `mostrar_diff` | Abre el visor de diferencias nativo. No escribe nada: es para que lo veas antes. |
-
-**Con varias ventanas abiertas se elige la correcta**, no la primera: gana la carpeta más
-específica que contenga el directorio de trabajo, y si ninguna lo contiene **no se conecta a
-nada**. Conectarse a la ventana de otro proyecto sería peor que no conectarse: los diffs saldrían
-en el sitio equivocado.
-
-El servidor escucha solo en `127.0.0.1` y exige un token de 32 bytes que va en la ficha, dentro de
-tu carpeta personal. Sin eso, cualquier programa de la máquina podría manejar tu editor.
-
-Para apagarlo: `CHOCOLATITO_SIN_EDITOR=1`, o la opción `chocolatito.puente` en VSCode.
-
-### Instalarla
-
-Mientras no esté en el marketplace, se instala desde el paquete:
-
-```bash
-cd extension-vscode
-npx @vscode/vsce package --allow-missing-repository --skip-license
-code --install-extension chocolatito-code-vscode-0.1.1.vsix
-```
-
-**Con VSCode cerrado**, y reiniciándolo después. Copiar la carpeta a mano a `~/.vscode/extensions`
-**no funciona**: falta el `.vsixmanifest` y VSCode la lista pero no la carga nunca, sin dar ningún
-error. Para desarrollar, `F5` sobre la carpeta abre una ventana con la extensión cargada al vuelo.
-
-En la barra de estado, abajo a la derecha, pone **Chocolatito** con el estado del puente. Si algo
-falla —sin carpeta abierta, puente apagado, puerto ocupado— lo dice ahí, y al pulsarlo se abre el
-detalle.
-
----
-
-## 🔌 MCP (Model Context Protocol)
-
-Conecta cualquier servidor MCP y sus herramientas quedan disponibles para el agente.
-Configuración compatible con Claude Code en `.mcp.json` (ver `.mcp.json.ejemplo`):
-
-```json
-{ "mcpServers": { "github": {
-    "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
-    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } } } }
-```
-
-Las herramientas aparecen como `mcp__<servidor>__<herramienta>`. Usa `/mcp` para ver el estado.
-
-## 🪝 Hooks
-
-Reglas propias que el agente no puede saltarse, en `.chocolatito/settings.json`:
-
-```json
-{ "hooks": { "PreToolUse": [ { "matcher": "run_command",
-    "hooks": [{ "type": "command", "command": "node .chocolatito/hooks/guardia.mjs" }] } ] } }
-```
-
-El hook recibe el evento por stdin como JSON y puede **denegar**, **pedir confirmación** o
-**reescribir los argumentos** antes de que la herramienta se ejecute. Salir con código 2
-bloquea directamente.
-
-
-## 🔐 Permisos
-
-Una sola regla: **mirar es gratis, actuar se pregunta.**
-
-| Acción | Se pregunta |
-| :--- | :--- |
-| `ui_snapshot`, `list_windows`, `snapshot`, `screenshot`, `get_text`, `tabs` | No. Es el paso previo obligatorio de todo. |
-| Clic, escritura, navegación o JavaScript sobre tu ordenador o tu Chrome | **Siempre**, también en `acceptEdits`. |
-| `run_command`, escritura y borrado de archivos | Sí, salvo patrón autorizado. |
-
-### Cambiar de modo con `shift+tab`
-
-Funciona **en cualquier momento**: en el prompt, a mitad de una generación y dentro del
-propio diálogo de permiso (ahí además aprueba la acción pendiente).
-
-```
-normal  →  acepta ediciones  →  automático  →  normal
-```
-
-- **normal** — pregunta antes de cada acción con consecuencias.
-- **acepta ediciones** — escribe archivos sin preguntar; sigue preguntando por comandos y
-  por el control del ordenador.
-- **automático** — no pregunta nada.
-
-El **modo plan** se activa aparte, con `/plan`, para no dejarlo a un golpe de tecla. Es
-solo lectura de verdad: ni comandos, ni clics, ni escrituras.
-
-`--yes` aprueba todo sin preguntar: es para CI, no para el día a día.
-
-## 📋 Pegar texto largo
-
-Pegar un log de 300 líneas ya no mete 300 líneas en el recuadro. Se guarda aparte y en el prompt
-queda una marca corta:
-
-```
-❯ arregla esto [pegado #1 · 347 lineas]
-```
-
-**El modelo recibe el texto entero**, no la marca: al enviar se sustituye por lo que pegaste. Y un
-solo `backspace` con el cursor detrás de la marca se la lleva completa — lo que ocupa una línea se
-borra como una línea.
-
-Por debajo de 5 líneas o 400 caracteres se pega normal, entero y a la vista.
-
----
-
-## ⌨️ Escribir mientras trabaja
-
-No hace falta esperar a que termine. Lo que escribas durante una generación aparece bajo
-el spinner y, al pulsar Enter, queda en cola: el agente acaba su turno y lo toma como
-siguiente orden, sin que tengas que volver a teclearlo.
-
-`Esc` pausa el turno en curso. `Ctrl+C` una vez interrumpe; dos veces cierra la sesión.
-
-
----
-
-## 🔑 Licencia
-
-Al abrirlo por primera vez pide la clave que recibiste por correo al comprar:
-
-```
-🔑 ACTIVACIÓN — CHOCOLATITO CODE
-Licencia ❯ 38b1460a-5104-4067-a91d-77b872934d51
-✔ Licencia activada para tu@correo.com
-```
-
-Se guarda en `~/.chocolatitorc` y no vuelve a pedirla. Una clave sirve para **3 equipos**.
-
-```bash
-/licencia            # ver la licencia activa y en qué equipo estás
-/licencia liberar    # soltar este equipo para usar la clave en otro
-```
-
-Si cambias de ordenador o formateas, libera el equipo antes. Si ya no puedes,
-escribe al soporte y se libera desde el panel.
-
-Se comprueba una vez al día. Si algún día no hay conexión, **sigues trabajando**:
-hay 7 días de margen antes de pedirte que te conectes.
-
----
-
-## 📦 Instalación
-
-```bash
-npm install -g chocolatito-code
-chocolatito --version
-```
-
-Requiere **Node.js 20 o superior**. La primera vez pide la API key y la guarda en
-`~/.chocolatitorc`; también se puede pasar por `CHOCOLATITO_API_KEY` o por un `.env` del
-proyecto.
-
-Para desarrollar sobre el propio proyecto:
-
-```bash
-npm install && npm run build && npm link
-```
-
-### Actualizaciones
-
-Se instalan solas. Al arrancar se le pregunta al registro de npm si hay una versión más
-nueva (como mucho una vez cada 6 horas, y sin retrasar el arranque: si no hay red, no pasa
-nada). Si la hay, se instala de fondo y entra **al reiniciar** `chocolatito` — nunca a
-mitad de sesión.
-
-| | |
-| --- | --- |
-| `/actualizar` | Comprobar e instalar ahora, sin esperar a la siguiente ventana. |
-| `CHOCOLATITO_SIN_ACTUALIZAR=1` | Apagarlo del todo. |
-
-Una instalación de desarrollo (`npm link` sobre el repositorio) **no se toca nunca**:
-instalar encima le borraría el trabajo a quien lo está escribiendo. Y no se baja jamás a
-una preversión, aunque el registro la anuncie como la última.
-
-Si la carpeta global es de administrador y no hay permiso para escribir, no se insiste: se
-dice una vez el comando (`npm i -g chocolatito-code@latest`) y se sigue trabajando.
-
----
-
-## 🚀 Uso Rápido
-
-```bash
-# Iniciar sesión interactiva
-chocolatito
-
-# O ejecutar una orden directa
-chocolatito "crea una API REST con Node.js y Express"
-
-# Modo no interactivo: aprueba las acciones sin preguntar
-chocolatito --yes "ejecuta los tests y arregla lo que falle"
-
-# Ayuda y versión, sin gastar tokens
-chocolatito --help
-chocolatito --version
-```
-
-### Códigos de salida
-
-En modo orden única el código dice qué pasó de verdad. Antes siempre era `0`: una cuota
-agotada o una licencia caída dejaban el paso del CI en verde sin haber tocado nada.
-
-| Código | Qué significa | Qué hacer |
-| :---: | :--- | :--- |
-| `0` | La tarea se completó. | Nada. |
-| `1` | El agente no pudo terminar: el motor falló tras los reintentos, o se agotó el límite de 30 iteraciones. | Reintentar tiene sentido. |
-| `2` | Error de uso: no se dio ninguna orden, o no hay terminal para pedirla. | Arreglar la invocación. |
-| `3` | Cuota agotada. | Esperar a que se libere la ventana; reintentar no la devuelve. |
-| `4` | Licencia o API key no válida. | Revisar `/licencia` o `~/.chocolatitorc`. |
-| `5` | Ya hay 4 peticiones en curso con esta licencia. | Esperar los segundos que dice el mensaje y reintentar. |
-| `130` | Interrumpido con `Esc` (128 + SIGINT, como cualquier otro programa). | Nada. |
-
-Lo que no es `0` se explica también por `stderr`, con el motivo del corte. Un ejemplo:
-
-```bash
-chocolatito --yes "ejecuta los tests y arregla lo que falle"
-case $? in
-  0) echo "hecho" ;;
-  3|4) echo "problema de cuenta, no de código: no reintentes" ;;
-  *) echo "falló, se puede reintentar" ;;
-esac
-```
-
-## 🧪 Pruebas
-
-```bash
-npm run build && npm test
-```
-
-## 📚 Documentación
-
-- `MEJORAS.md` — auditoría del núcleo y de permisos: qué estaba roto, qué se arregló y cómo se comprobó.
-- `COMPUTER-USE.md` — diseño del control de ordenador y navegador.
-- `extension/README.md` — instalación de la extensión de Chrome.
-
----
-
-Desarrollado con pasión por **Chocolatito**. 🦊⚡
+# 🦊 Chocolatito Code (v1.0.0)
+
+> **Agente Autónomo de Programación para la Terminal**, desarrollado por **Chocolatito** con la arquitectura del **Motor Espectro**.
+
+---
+
+## ⚡ Niveles de Potencia y Esfuerzo (/effort)
+
+Chocolatito Code te permite regular dinámicamente la profundidad y potencia del motor según la complejidad de la tarea:
+
+| Nivel | Nombre | Nivel de Esfuerzo | Uso Recomendado |
+| :--- | :--- | :---: | :--- |
+| Nivel | Modelo real | Uso recomendado |
+| :--- | :--- | :--- |
+| **`1.0`** Ágil | `deepseek-v4-flash` | Tareas cotidianas, funciones y scripts directos. |
+| **`1.5`** Avanzado | `deepseek-v4-flash` | Refactorizaciones, con más margen creativo. |
+| **`2.0`** Razonamiento Pro | `deepseek-v4-pro` | Bugs difíciles, algoritmos y arquitectura. |
+| **`2.5`** MAX | `deepseek-v4-pro` | Proyectos completos y exploración amplia. |
+
+Ventana de contexto: **1.000.000 de tokens** en los cuatro niveles.
+
+Para cambiar de nivel dentro de la sesión, escribe:
+```bash
+/effort 2.0
+```
+
+---
+
+## 🛠️ Herramientas Nativas Autónomas
+
+- 👁️ `view_file`: Lectura precisa con numeración de líneas.
+- ✏️ `edit_file`: Modificación de código con diffs visuales tipo Git (verde/rojo).
+- 📄 `write_file`: Creación y sobreescritura de archivos y directorios.
+- 💻 `run_command`: Ejecución de comandos en PowerShell/Bash con captura de logs.
+- ⏳ `start_background_task`: Ejecución de servidores y procesos en segundo plano (`npm run dev`, watchers) con lectura incremental (`read_task_output`), listado (`list_background_tasks`) y parada limpia del árbol de procesos (`stop_background_task`).
+- 🧠 `save_memory` / `read_memory`: Memoria jerárquica en dos niveles (ámbito local de proyecto en `.chocolatito/memory/` y preferencias globales en `~/.chocolatito/memory/`).
+- 📂 `list_dir`: Exploración de proyectos respetando `.gitignore`.
+- 🔍 `grep_search`: Búsqueda instantánea de texto y regex.
+- 🌐 `chrome`: Controla **tu** Chrome desde dentro con telemetría web en vivo: captura de excepciones de consola (`console_logs`) y errores de red HTTP (`network_errors`).
+- 🖥️ `computer_use`: Aplicaciones de escritorio por árbol de accesibilidad, sin adivinar píxeles.
+- 🧭 `browser`: Navegador propio por CDP, para webs públicas y `localhost`.
+
+Las lecturas independientes lanzadas en el mismo turno se ejecutan **en paralelo**.
+
+## 🗺️ Mapa del repositorio
+
+Al arrancar, el agente recibe un índice de los símbolos del proyecto ordenado por **cuánto los
+usa el resto del código** (un PageRank sobre el grafo de referencias, con presupuesto de 4.000
+tokens). Sirve para que sepa qué existe y dónde mirar sin gastar turnos en `grep_search`
+buscando a ciegas.
+
+Son nombres y números de línea, no contenido: antes de editar sigue leyendo el archivo.
+
+Lo que escribes también cuenta. Si dices *"arregla calcularImpuesto"* o *"falla en loop.ts"*, se
+detecta la referencia aunque no pongas `@` y se le pasan las rutas —solo las rutas, no el
+contenido, que cuesta más contexto del que ahorra.
+
+## ✅ Verificación automática tras editar
+
+Cuando un turno escribe en disco, Chocolatito puede correr el verificador del proyecto y
+devolverle el error al agente **en el mismo turno**, en vez de dar el trabajo por bueno y que el
+fallo aparezca tres turnos después.
+
+Viene **apagada**: correr un comando del proyecto es ejecutar código, y eso se pide. Para
+activarla, en `.chocolatito/settings.json` (del proyecto o global en `~/.chocolatito/`):
+
+```json
+{
+  "verify": { "auto": true },
+  "limits": { "maxIterations": 60, "subagentIterations": 20 }
+}
+```
+
+También con variables de entorno: `CHOCOLATITO_AUTO_VERIFY=1`, `CHOCOLATITO_VERIFY_CMD`,
+`CHOCOLATITO_MAX_ITERATIONS`, `CHOCOLATITO_SUBAGENT_ITERATIONS`.
+
+El comando se detecta solo, en este orden: `npm run typecheck` → `lint` → `check` → `build`, o
+`npx tsc --noEmit`, `cargo check`, `go build ./...`. **Nunca los tests**: un `npm test` puede
+levantar servidores o tardar minutos, y verificar no puede significar eso. Con `verify.command`
+pones el tuyo. Si falla, el agente tiene tres intentos para arreglarlo; al cuarto para y te lo
+dice.
+
+## ↻ Cuando el agente se atasca
+
+Si repite tres veces la misma llamada con el mismo resultado, se para y pregunta: le dejas
+seguir, o le dices que cambie de enfoque. Sin terminal (CI, `chocolatito "haz X"`) se corta
+solo, para que un bucle que nadie está mirando no se coma la cuota.
+
+## 📱 En el móvil, sin instalar nada (`--servir`)
+
+Abre **esta misma sesión** en el navegador de cualquier aparato de tu red. El agente
+sigue corriendo en tu PC, con tus archivos y tus permisos; el móvil es la pantalla y el
+teclado.
+
+```bash
+chocolatito --servir        # solo desde esta máquina
+chocolatito --servir-red    # también desde el móvil o la tablet de tu red
+```
+
+Imprime un enlace con un token dentro. Ese enlace **es** la llave: quien lo tenga entero
+entra. El token se borra solo de la barra de direcciones en cuanto la página carga, para
+que no se quede en el historial ni salga en una captura.
+
+Resuelve de paso el **iPhone**, donde no hay forma de instalarlo: Apple no permite un
+Termux, y el emulador de iSH no implementa las instrucciones que necesita el motor de
+JavaScript de Node. Por el navegador no hace falta instalar nada.
+
+| | |
+| --- | --- |
+| `--puerto N` | Otro puerto (por defecto 4700). |
+| Se reconecta solo | Un móvil pierde la red a cada rato; la sesión no se pierde con ella. |
+| Los permisos | Salen en el móvil, con los mismos botones que en el terminal. |
+
+**Manda el navegador.** Con `--servir`, lo que escribas en el terminal ya no se lee: el
+terminal queda de monitor. Es a propósito — dos entradas peleándose por el mismo teclado
+es de donde salen los cuelgues raros.
+
+**Lo que NO hace, a propósito:** no hay HTTPS ni túnel propio. Para entrar desde fuera de
+tu casa, usa Tailscale o `cloudflared`, que ya existen y están auditados. Un túnel casero
+es la parte fácil de una responsabilidad muy grande.
+
+### Lo que protege la puerta
+
+Detrás de ese enlace hay ejecución de comandos en tu máquina, así que:
+
+1. **Token en todo**, incluido el WebSocket — que es justo el que manda órdenes, y el que
+   más se olvida. Se compara en tiempo constante.
+2. **La cabecera `Host` tiene que ser una IP o `localhost`.** Corta el *DNS rebinding*, que
+   es la única forma real de atacar algo que solo escucha en 127.0.0.1: una web cualquiera
+   apunta su dominio a tu 127.0.0.1 y usa tu navegador como puente. Un ataque así llega
+   siempre con un nombre de dominio; exigiendo IP se cae solo.
+3. **`Origin`, si viene, tiene que coincidir.**
+4. **127.0.0.1 por defecto.** Salir a la red hay que escribirlo (`--servir-red`) y se avisa
+   en pantalla.
+
+Y un permiso **nunca** se aprueba solo. Si no hay nadie conectado, la pregunta vuelve al
+terminal; si el navegador se cae con una pregunta abierta, la respuesta es *no*.
+
+---
+
+## 🧩 VSCode
+
+Si tienes la extensión instalada y abres `chocolatito` en la terminal integrada, **se conecta
+solo**. No hay nada que configurar.
+
+El truco está al revés de lo que parece: la extensión es un **servidor MCP** y el agente es el
+cliente. Cada ventana de VSCode levanta un servidor en `127.0.0.1` y deja una ficha en
+`~/.chocolatito/ide/` con su puerto, su token y la carpeta que tiene abierta. El agente busca la
+ficha cuya carpeta contiene su directorio de trabajo.
+
+Lo que gana el agente (lo único que no puede tener por su cuenta):
+
+| Herramienta | Para qué |
+| --- | --- |
+| `diagnosticos` | Los errores del servidor de lenguaje. Los subrayados rojos, sin esperar a compilar. |
+| `seleccion_actual` | Qué archivo tienes abierto y qué has seleccionado. Hace que «arregla esto» signifique algo. |
+| `archivos_abiertos` | Las pestañas abiertas, en orden. |
+| `mostrar_diff` | Abre el visor de diferencias nativo. No escribe nada: es para que lo veas antes. |
+
+**Con varias ventanas abiertas se elige la correcta**, no la primera: gana la carpeta más
+específica que contenga el directorio de trabajo, y si ninguna lo contiene **no se conecta a
+nada**. Conectarse a la ventana de otro proyecto sería peor que no conectarse: los diffs saldrían
+en el sitio equivocado.
+
+El servidor escucha solo en `127.0.0.1` y exige un token de 32 bytes que va en la ficha, dentro de
+tu carpeta personal. Sin eso, cualquier programa de la máquina podría manejar tu editor.
+
+Para apagarlo: `CHOCOLATITO_SIN_EDITOR=1`, o la opción `chocolatito.puente` en VSCode.
+
+### Instalarla
+
+Mientras no esté en el marketplace, se instala desde el paquete:
+
+```bash
+cd extension-vscode
+npx @vscode/vsce package --allow-missing-repository --skip-license
+code --install-extension chocolatito-code-vscode-0.1.1.vsix
+```
+
+**Con VSCode cerrado**, y reiniciándolo después. Copiar la carpeta a mano a `~/.vscode/extensions`
+**no funciona**: falta el `.vsixmanifest` y VSCode la lista pero no la carga nunca, sin dar ningún
+error. Para desarrollar, `F5` sobre la carpeta abre una ventana con la extensión cargada al vuelo.
+
+En la barra de estado, abajo a la derecha, pone **Chocolatito** con el estado del puente. Si algo
+falla —sin carpeta abierta, puente apagado, puerto ocupado— lo dice ahí, y al pulsarlo se abre el
+detalle.
+
+---
+
+## 🔌 MCP (Model Context Protocol)
+
+Conecta cualquier servidor MCP y sus herramientas quedan disponibles para el agente.
+Configuración compatible con Claude Code en `.mcp.json` (ver `.mcp.json.ejemplo`):
+
+```json
+{ "mcpServers": { "github": {
+    "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } } } }
+```
+
+Las herramientas aparecen como `mcp__<servidor>__<herramienta>`. Usa `/mcp` para ver el estado.
+
+## 🪝 Hooks
+
+Reglas propias que el agente no puede saltarse, en `.chocolatito/settings.json`:
+
+```json
+{ "hooks": { "PreToolUse": [ { "matcher": "run_command",
+    "hooks": [{ "type": "command", "command": "node .chocolatito/hooks/guardia.mjs" }] } ] } }
+```
+
+El hook recibe el evento por stdin como JSON y puede **denegar**, **pedir confirmación** o
+**reescribir los argumentos** antes de que la herramienta se ejecute. Salir con código 2
+bloquea directamente.
+
+
+## 🔐 Permisos
+
+Una sola regla: **mirar es gratis, actuar se pregunta.**
+
+| Acción | Se pregunta |
+| :--- | :--- |
+| `ui_snapshot`, `list_windows`, `snapshot`, `screenshot`, `get_text`, `tabs` | No. Es el paso previo obligatorio de todo. |
+| Clic, escritura, navegación o JavaScript sobre tu ordenador o tu Chrome | **Siempre**, también en `acceptEdits`. |
+| `run_command`, escritura y borrado de archivos | Sí, salvo patrón autorizado. |
+
+### Cambiar de modo con `shift+tab`
+
+Funciona **en cualquier momento**: en el prompt, a mitad de una generación y dentro del
+propio diálogo de permiso (ahí además aprueba la acción pendiente).
+
+```
+normal  →  acepta ediciones  →  automático  →  normal
+```
+
+- **normal** — pregunta antes de cada acción con consecuencias.
+- **acepta ediciones** — escribe archivos sin preguntar; sigue preguntando por comandos y
+  por el control del ordenador.
+- **automático** — no pregunta nada.
+
+El **modo plan** se activa aparte, con `/plan`, para no dejarlo a un golpe de tecla. Es
+solo lectura de verdad: ni comandos, ni clics, ni escrituras.
+
+`--yes` aprueba todo sin preguntar: es para CI, no para el día a día.
+
+## 📋 Pegar texto largo
+
+Pegar un log de 300 líneas ya no mete 300 líneas en el recuadro. Se guarda aparte y en el prompt
+queda una marca corta:
+
+```
+❯ arregla esto [pegado #1 · 347 lineas]
+```
+
+**El modelo recibe el texto entero**, no la marca: al enviar se sustituye por lo que pegaste. Y un
+solo `backspace` con el cursor detrás de la marca se la lleva completa — lo que ocupa una línea se
+borra como una línea.
+
+Por debajo de 5 líneas o 400 caracteres se pega normal, entero y a la vista.
+
+---
+
+## ⌨️ Escribir mientras trabaja
+
+No hace falta esperar a que termine. Lo que escribas durante una generación aparece bajo
+el spinner y, al pulsar Enter, queda en cola: el agente acaba su turno y lo toma como
+siguiente orden, sin que tengas que volver a teclearlo.
+
+`Esc` pausa el turno en curso. `Ctrl+C` una vez interrumpe; dos veces cierra la sesión.
+
+---
+
+## 🛡️ Auditoría Pre-Commit (/audit y /review)
+
+Antes de hacer un commit o desplegar cambios, corre `/audit` o `/review`:
+- **Detección de secretos:** escanea el diff en busca de claves expuestas de OpenAI, Anthropic, AWS, Google, GitHub, tokens genéricos y claves privadas.
+- **Detección de archivos sensibles:** alerta sobre la inclusión de archivos como `.env`, `.env.local`, `id_rsa` o `*.pem`.
+- **Limpieza de depuración:** localiza sentencias residuales como `console.log`, `debugger;` o `print()`.
+- **Sugerencia de Conventional Commits:** genera automáticamente la propuesta de commit semántico según los archivos modificados (ej. `feat(tools): ...`, `test: ...`).
+
+---
+
+## 📌 Widget de Tareas en Vivo y Selector /resume
+
+- **Checklist visual interactivo:** cuando el agente define tareas con `todo_write`, la terminal muestra de forma fija en el pie el progreso en vivo (`⎿ ✔ 2/4 tareas · En curso: <tarea>`).
+- **Reanudar sesiones visualmente:** al escribir `/resume` sin argumentos, Chocolatito abre un selector interactivo con flechas mostrando el historial, número de mensajes, fecha y previsualización de tu primer mensaje.
+
+---
+
+## 🔑 Licencia
+
+Al abrirlo por primera vez pide la clave que recibiste por correo al comprar:
+
+```
+🔑 ACTIVACIÓN — CHOCOLATITO CODE
+Licencia ❯ 38b1460a-5104-4067-a91d-77b872934d51
+✔ Licencia activada para tu@correo.com
+```
+
+Se guarda en `~/.chocolatitorc` y no vuelve a pedirla. Una clave sirve para **3 equipos**.
+
+```bash
+/licencia            # ver la licencia activa y en qué equipo estás
+/licencia liberar    # soltar este equipo para usar la clave en otro
+```
+
+Si cambias de ordenador o formateas, libera el equipo antes. Si ya no puedes,
+escribe al soporte y se libera desde el panel.
+
+Se comprueba una vez al día. Si algún día no hay conexión, **sigues trabajando**:
+hay 7 días de margen antes de pedirte que te conectes.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install -g chocolatito-code
+chocolatito --version
+```
+
+Requiere **Node.js 20 o superior**, en Windows, macOS, Linux o Android (Termux). La primera vez pide la API key y la guarda en
+`~/.chocolatitorc`; también se puede pasar por `CHOCOLATITO_API_KEY` o por un `.env` del
+proyecto.
+
+Para desarrollar sobre el propio proyecto:
+
+```bash
+npm install && npm run build && npm link
+```
+
+### En el celular, con Termux (Android)
+
+El mismo paquete. No hay versión aparte ni nada que compilar: ninguna dependencia es
+nativa.
+
+```bash
+pkg update && pkg install nodejs git
+npm install -g chocolatito-code
+chocolatito
+```
+
+Termux no tiene `/bin`, así que el shell se **busca** en vez de darlo por fijo: primero en
+`$PREFIX/bin` (el prefijo real de tu instalación, que cambia en los forks) y luego en las
+rutas de siempre. Si en algún momento sale un error diciendo que no encuentra `bash`, se
+arregla con `pkg install bash`.
+
+Al modelo se le dice que está en **Android (Termux)**, no en Linux, para que no proponga
+`sudo` ni `apt-get`: aquí no hay root y se instala con `pkg`.
+
+Lo que **no** funciona en el móvil, porque no puede: `computer_use` (no hay escritorio),
+`chrome` y `browser` (no hay Chrome de escritorio ni extensión), y el puente con VSCode. Se
+avisa al intentarlo, no se rompe la sesión. Todo lo demás —leer, editar, ejecutar comandos,
+buscar, el mapa del repositorio, git— es igual que en el escritorio.
+
+Consejo práctico: en vertical se ve poco ancho. La interfaz se adapta, pero para trabajar
+de verdad vale mucho un teclado bluetooth y girar la pantalla.
+
+### Actualizaciones
+
+Se instalan solas. Al arrancar se le pregunta al registro de npm si hay una versión más
+nueva (como mucho una vez cada 6 horas, y sin retrasar el arranque: si no hay red, no pasa
+nada). Si la hay, se instala de fondo y entra **al reiniciar** `chocolatito` — nunca a
+mitad de sesión.
+
+| | |
+| --- | --- |
+| `/actualizar` | Comprobar e instalar ahora, sin esperar a la siguiente ventana. |
+| `CHOCOLATITO_SIN_ACTUALIZAR=1` | Apagarlo del todo. |
+
+Una instalación de desarrollo (`npm link` sobre el repositorio) **no se toca nunca**:
+instalar encima le borraría el trabajo a quien lo está escribiendo. Y no se baja jamás a
+una preversión, aunque el registro la anuncie como la última.
+
+Si la carpeta global es de administrador y no hay permiso para escribir, no se insiste: se
+dice una vez el comando (`npm i -g chocolatito-code@latest`) y se sigue trabajando.
+
+---
+
+## 🚀 Uso Rápido
+
+```bash
+# Iniciar sesión interactiva
+chocolatito
+
+# O ejecutar una orden directa
+chocolatito "crea una API REST con Node.js y Express"
+
+# Modo no interactivo: aprueba las acciones sin preguntar
+chocolatito --yes "ejecuta los tests y arregla lo que falle"
+
+# Ayuda y versión, sin gastar tokens
+chocolatito --help
+chocolatito --version
+```
+
+### Códigos de salida
+
+En modo orden única el código dice qué pasó de verdad. Antes siempre era `0`: una cuota
+agotada o una licencia caída dejaban el paso del CI en verde sin haber tocado nada.
+
+| Código | Qué significa | Qué hacer |
+| :---: | :--- | :--- |
+| `0` | La tarea se completó. | Nada. |
+| `1` | El agente no pudo terminar: el motor falló tras los reintentos, o se agotó el límite de 30 iteraciones. | Reintentar tiene sentido. |
+| `2` | Error de uso: no se dio ninguna orden, o no hay terminal para pedirla. | Arreglar la invocación. |
+| `3` | Cuota agotada. | Esperar a que se libere la ventana; reintentar no la devuelve. |
+| `4` | Licencia o API key no válida. | Revisar `/licencia` o `~/.chocolatitorc`. |
+| `5` | Ya hay 4 peticiones en curso con esta licencia. | Esperar los segundos que dice el mensaje y reintentar. |
+| `130` | Interrumpido con `Esc` (128 + SIGINT, como cualquier otro programa). | Nada. |
+
+Lo que no es `0` se explica también por `stderr`, con el motivo del corte. Un ejemplo:
+
+```bash
+chocolatito --yes "ejecuta los tests y arregla lo que falle"
+case $? in
+  0) echo "hecho" ;;
+  3|4) echo "problema de cuenta, no de código: no reintentes" ;;
+  *) echo "falló, se puede reintentar" ;;
+esac
+```
+
+## 🧪 Pruebas
+
+```bash
+npm run build && npm test
+```
+
+## 📚 Documentación
+
+- `MEJORAS.md` — auditoría del núcleo y de permisos: qué estaba roto, qué se arregló y cómo se comprobó.
+- `COMPUTER-USE.md` — diseño del control de ordenador y navegador.
+- `extension/README.md` — instalación de la extensión de Chrome.
+
+---
+
+Desarrollado con pasión por **Chocolatito**. 🦊⚡