@jmanuelcorral/openteam 0.1.38 → 0.1.41

package/README.es.md

@@ -0,0 +1,759 @@
+# openteam
+
+> 🌐 **Language / Idioma:** [English](README.md) · **Español** (este documento)
+
+**openteam — plugin de opencode con routing coste-consciente local-first, fallback FRONTIER cheapest-capable y orquestación multiagente a demanda.**
+
+> 📖 **Sitio de documentación:** <https://jmanuelcorral.github.io/openteam/es/> (también en [English](https://jmanuelcorral.github.io/openteam/))
+
+## Tabla de contenidos
+
+- [Qué es y por qué existe](#qué-es-y-por-qué-existe)
+- [Características](#características)
+- [Requisitos](#requisitos)
+- [Instalación](#instalación)
+- [Quickstart: `openteam setup`](#quickstart-openteam-setup)
+- [Probar en otra máquina](#probar-en-otra-máquina)
+- [Actualizar openteam](#actualizar-openteam)
+- [Configuración](#configuración)
+- [Uso](#uso)
+- [Ejemplos en Windows](#ejemplos-en-windows)
+- [Publicación segura](#publicación-segura)
+- [Privacidad](#privacidad)
+- [Calidad](#calidad)
+- [Compatibilidad](#compatibilidad)
+- [Roadmap](#roadmap)
+- [Licencia](#licencia)
+- [Agradecimientos e inspiración](#agradecimientos-e-inspiración)
+
+## Qué es y por qué existe
+
+openteam añade a opencode una capa de routing y orquestación para ahorrar tokens y coste frontier sin perder calidad ni privacidad. La estrategia por defecto es **local-first**: tareas triviales, resúmenes, documentación sencilla y diffs pequeños intentan usar runtimes locales; tareas de arquitectura, seguridad, refactors multiarchivo, tool calling crítico o debugging ambiguo escalan a **FRONTIER cheapest-capable**.
+
+El router mantiene una garantía de privacidad: con `privacyMode: "forceLocalOnSensitive"`, una tarea marcada como `privacySensitive` no escala a frontier.
+
+## Características
+
+- Routing por turno desde el hook `chat.message`, mutando `output.message.model` antes de que opencode persista el mensaje.
+- Registro de runtimes locales OpenAI-compatible: Ollama, LM Studio y Foundry Local.
+- Clasificador local JSON con fallback heurístico determinista.
+- Perfiles de capacidad desde Models.dev, con cache y fallback curado cuando el catálogo no está disponible.
+- Selección frontier **cheapest-capable** por coste blended `0.75 * inputUSD + 0.25 * outputUSD`.
+- Presupuestos por sesión, mes y tokens frontier por sesión.
+- Telemetría `CostRecord` JSONL hash-only: guarda `promptHash`, métricas de coste y decisión, nunca prompts crudos.
+- Orquestación multiagente con `runRoleTask` / `runRoleTasks`, subsesiones SDK y modelo explícito en `client.session.prompt({ body: { model } })`.
+- Refresh de disponibilidad local al arrancar y en eventos `session.created` / `session.idle`.
+
+## Requisitos
+
+- opencode compatible con `@opencode-ai/plugin` `1.17.13`.
+- Bun `1.3.14` para instalaciones, desarrollo y tests reproducibles.
+- Node.js `^22.22.2 || ^24.15.0 || >=26.0.0` para la CLI y el plugin publicados.
+- Runtimes locales opcionales:
+  - Ollama en `http://localhost:11434/v1`.
+  - LM Studio en `http://localhost:1234/v1`.
+  - Foundry Local con puerto dinámico descubierto por CLI en Windows.
+
+## Instalación
+
+### Opción A: paquete npm
+
+El paquete se publica como `@jmanuelcorral/openteam`. Estas son las rutas de instalación soportadas:
+
+| Necesidad | Método soportado |
+| --- | --- |
+| Cargar el plugin en opencode | Añadir `@jmanuelcorral/openteam` al array `plugin` de `opencode.json`. opencode resuelve el paquete; no hace falta instalar la CLI globalmente. |
+| Ejecutar setup una vez | `bunx --package @jmanuelcorral/openteam@latest openteam setup` |
+| Mantener la CLI `openteam` en el `PATH` | `bun add --global @jmanuelcorral/openteam@latest` y después `openteam setup` |
+
+La instalación global con npm **no está soportada**. Bun es el único instalador de paquetes soportado. Node.js ejecuta la CLI y el plugin publicados dentro del rango declarado de engines; npm se limita a operaciones de mantenedor: `pack`, Trusted Publishing y `link:local`.
+
+Para la carga directa desde opencode, basta con referenciar el paquete:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "ollama/qwen3:8b",
+  "plugin": [
+    [
+      "@jmanuelcorral/openteam",
+      {
+        "baseline": {
+          "mode": "auto",
+          "pinnedModel": null,
+          "hardDefault": {
+            "providerID": "anthropic",
+            "modelID": "claude-sonnet-4-5"
+          }
+        },
+        "router": {
+          "mode": "balanced",
+          "localDefault": {
+            "providerID": "ollama",
+            "modelID": "qwen3:8b"
+          },
+          "trivialPromptMaxChars": 280,
+          "frontierPromptMinChars": 2000
+        },
+        "local": {
+          "runtimes": [
+            {
+              "id": "ollama",
+              "enabled": true,
+              "baseURL": "http://localhost:11434/v1",
+              "defaultModel": {
+                "providerID": "ollama",
+                "modelID": "qwen3:8b"
+              }
+            },
+            {
+              "id": "lmstudio",
+              "enabled": true,
+              "baseURL": "http://localhost:1234/v1",
+              "defaultModel": {
+                "providerID": "lmstudio",
+                "modelID": "qwen2.5-coder-local"
+              }
+            }
+          ]
+        },
+        "budgets": {
+          "sessionUSD": 2,
+          "monthlyUSD": 30,
+          "frontierTokensPerSession": 250000,
+          "hardStopOnBudgetExhaustion": false
+        },
+        "privacyMode": "forceLocalOnSensitive",
+        "telemetry": {
+          "enabled": true,
+          "path": ".opencode/openteam-telemetry.jsonl"
+        }
+      }
+    ]
+  ],
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (local)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1",
+        "apiKey": "ollama",
+        "chunkTimeout": 60000
+      },
+      "models": {
+        "qwen3:8b": {
+          "name": "Qwen3 8B (Ollama)",
+          "tool_call": true,
+          "limit": { "context": 32768, "output": 8192 }
+        }
+      }
+    },
+    "lmstudio": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "LM Studio (local)",
+      "options": {
+        "baseURL": "http://localhost:1234/v1",
+        "apiKey": "lm-studio"
+      },
+      "models": {
+        "qwen2.5-coder-local": {
+          "name": "Qwen2.5 Coder Local",
+          "tool_call": true,
+          "limit": { "context": 32768, "output": 8192 }
+        }
+      }
+    }
+  }
+}
+```
+
+### Opción B: ruta de desarrollo
+
+Durante desarrollo puedes cargar un plugin local desde `.opencode/plugins/openteam.ts`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "./.opencode/plugins/openteam.ts",
+      {
+        "router": {
+          "mode": "balanced",
+          "localDefault": {
+            "providerID": "ollama",
+            "modelID": "qwen3:8b"
+          }
+        },
+        "telemetry": {
+          "path": ".opencode/openteam-telemetry.jsonl"
+        }
+      }
+    ]
+  ]
+}
+```
+
+## Quickstart: `openteam setup`
+
+La forma más rápida de dejar un repositorio listo para opencode + openteam es el comando interactivo `openteam setup`. Detecta los runtimes locales instalados (Ollama, LM Studio, Foundry Local) —que son **opcionales**: puedes usar openteam **solo con frontier**, o apuntar a un Ollama/LM Studio que corra en **otra máquina de la red local**—, te deja elegir los modelos locales y el modelo **frontier baseline** (ordenados de más barato-capaz a más caro), y genera tres ficheros:
+
+- `opencode.json` en la raíz: declara el plugin `@jmanuelcorral/openteam`, los `provider` locales OpenAI-compatible, el `model` frontier y el `small_model` local.
+- `.opencode/openteam.json`: la configuración runtime validada de openteam (baseline, routing, runtimes locales y privacidad).
+- `.opencode/agent/openteam.md`: el **agente primario `openteam`**, visible en el Tab-switcher.
+
+```powershell
+# Ejecución puntual, sin instalación global
+bunx --package @jmanuelcorral/openteam@latest openteam setup
+# O después de la instalación global soportada con Bun
+openteam setup
+```
+
+> El antiguo comando `openteam init` sigue funcionando como **alias obsoleto** de `openteam setup`.
+
+El asistente:
+
+1. Sondea los runtimes locales y marca los detectados.
+2. Te deja habilitar runtimes (o **ninguno**: puedes usar openteam **solo con modelos frontier**) y, por cada runtime que habilites, elegir si corre **en esta máquina** o **en otra máquina de la red local** (introduciendo su URL, p. ej. `http://192.168.1.50:11434/v1`); luego eliges el modelo por defecto de cada uno (o lo escribes si no se detectan modelos).
+3. Ofrece el modelo frontier baseline a partir del **catálogo completo de [Models.dev](https://models.dev)** que openteam ya integra: una lista rápida con los más **baratos-capaces primero** (incluidos los **gratuitos**, etiquetados como `gratis`), una opción **«Ver todos los modelos por proveedor…»** para navegar el catálogo completo, y **«Otro (custom)»** para escribir un `provider/model`. Si el catálogo no se puede cargar (offline), cae a la lista curada.
+4. Pregunta el modo de routing (`balanced`/`economy`/`quality`), la política de privacidad y si quieres activar el **modo YOLO** (auto-aprobar permisos de opencode). Si no habilitas ningún runtime local, avisa de que estás en **modo solo frontier** y recomienda `consentBeforeFrontier` (porque `forceLocalOnSensitive` no tendría destino local).
+5. Si ya existe `opencode.json` o `.opencode/openteam.json`, pide confirmación antes de sobrescribir.
+
+Tras `setup`, autentica el provider frontier (`opencode auth login`), asegúrate de que tu runtime local (en esta máquina o en la red) esté accesible si lo habilitaste, y abre opencode en el repositorio: openteam enruta local-first automáticamente. Puedes reajustar el baseline después con `openteam baseline set <provider/model>` o `openteam baseline auto`.
+
+### El agente `openteam`
+
+`openteam setup` genera un único **agente primario** llamado `openteam` (`.opencode/agent/openteam.md`). Pulsa **Tab** en opencode para seleccionarlo: así sabes explícitamente que estás en modo openteam, mientras el plugin sigue optimizando el modelo por debajo.
+
+Ese orquestador **no trae subagentes precreados**. En **cada petición** su primera acción es comprobar si ya existe equipo (`.opencode/openteam-roster.md` + subagentes en `.opencode/agent/`). Si **existe**, reparte el trabajo entre los especialistas adecuados; si **no existe**, entiende las tareas que implica tu petición, diseña el equipo mínimo y **lo crea a demanda** —sin que tengas que pedírselo explícitamente— antes de pasarle esas tareas (escribiendo `.opencode/agent/<nombre>.md` con `mode: subagent`), reutilizando los existentes antes de crear nuevos. Los roles mecánicos/bulk se dejan enrutar a modelos locales y solo se escala a frontier para arquitectura, seguridad o debugging ambiguo. (Este modelo de equipo temático creado a demanda está inspirado en [Squad](https://bradygaster.github.io/squad/); ver [Agradecimientos](#agradecimientos-e-inspiración).)
+
+El equipo tiene **identidad temática**: el orquestador elige (o te pregunta) un **universo** y nombra a cada agente con un personaje de ese universo, registrando el reparto en `.opencode/openteam-roster.md` (fuera de `.opencode/agent/`, para que opencode no lo cargue como un agente fantasma) para que los nombres **persistan** entre sesiones. Además de los roles específicos del proyecto, contempla tres **roles estándar** creados a demanda:
+
+- **scribe** — memoria silenciosa: registra decisiones y aprendizajes en `.opencode/openteam-decisions.md` sin tocar el código (modelo local).
+- **ralph** — automatización y triage: monitoriza el trabajo pendiente, lo prioriza, coordina la ejecución y **escala al humano** ante bloqueos o aprobaciones.
+- **guardian** — seguridad y privacidad: **detecta y enmascara datos sensibles** (PII, secretos, API keys, tokens) antes de que salgan a frontier y hace revisión de seguridad; corre siempre en local y respeta `forceLocalOnSensitive`.
+
+Antes de delegar, el orquestador **planifica dependencias y paraleliza**: descompone la petición en tareas, y como opencode ejecuta en paralelo todas las llamadas `task` emitidas en un mismo turno (Vercel AI SDK), lanza a la vez las tareas independientes y secuencia por olas solo las que dependen de un resultado previo. El trabajo que colisiona sobre los mismos ficheros se separa en olas distintas para evitar conflictos.
+
+En la **lista de tareas** (`todowrite`, la que ves en el todo general de opencode) cada entrada lleva **visible el responsable**. opencode no tiene un campo de "agente" en sus todos (solo `content`/`status`/`priority`, y la lista es por sesión), así que el orquestador usa una convención en el texto: prefija cada tarea con el nombre del casting, p. ej. `[@Basher] Implementar el router` o `[@openteam] Sintetizar resultados`. Así, de un vistazo, sabes quién es responsable de cada tarea.
+
+## Probar en otra máquina
+
+Para instalar y probar openteam en otro equipo que ya tenga [opencode](https://opencode.ai) y [Bun](https://bun.sh):
+
+1. **Ejecuta o instala la CLI.** Elige una de estas rutas soportadas:
+
+   ```powershell
+   # Opción global (deja el comando `openteam` en el PATH)
+   bun add --global @jmanuelcorral/openteam@latest
+
+   # Opción puntual (no instala globalmente)
+   bunx --package @jmanuelcorral/openteam@latest openteam setup
+   ```
+
+2. **Inicializa el repositorio** donde vayas a trabajar. Genera `opencode.json`, `.opencode/openteam.json` y `.opencode/agent/openteam.md`:
+
+   ```powershell
+   cd C:\ruta\a\tu\repo
+   openteam setup          # global
+   # La opción puntual ya ejecutó setup en el paso anterior.
+   ```
+
+   El asistente detecta Ollama / LM Studio / Foundry Local, te deja elegir los modelos locales (locales o en otra máquina de la red) o **ninguno** para funcionar solo con frontier, y el frontier baseline, y escribe la configuración.
+
+3. **Autentica el provider frontier** que hayas elegido:
+
+   ```powershell
+   opencode auth login
+   ```
+
+4. **Arranca tu runtime local** si lo habilitaste y no estaba activo (p. ej. `ollama serve`, o abre LM Studio / Foundry Local). Si apuntaste a un runtime en **otra máquina de la red**, asegúrate de que sea accesible desde este equipo (host expuesto y puerto abierto); para Ollama esto normalmente implica arrancarlo con `OLLAMA_HOST=0.0.0.0 ollama serve` en la máquina remota. Si configuraste **solo frontier**, sáltate este paso.
+
+5. **Abre opencode en el repo**, pulsa **Tab** y elige el agente `openteam`. Dale el primer prompt: creará el equipo de subagentes a demanda y enrutará local-first automáticamente.
+
+Comprueba el estado con `openteam doctor` (runtimes + config) y el ahorro con `openteam report`.
+
+## Actualizar openteam
+
+openteam se publica en npm al publicar una GitHub Release. Para traer la última versión:
+
+```powershell
+# Instalación global
+bun add --global @jmanuelcorral/openteam@latest
+```
+
+Comprobar versiones:
+
+```powershell
+bun pm ls --global                         # paquetes globales instalados
+```
+
+La versión publicada más reciente aparece en
+<https://www.npmjs.com/package/@jmanuelcorral/openteam>.
+
+Notas al actualizar:
+
+- **No necesitas volver a ejecutar `openteam setup`** para actualizar el plugin: opencode resuelve el paquete `@jmanuelcorral/openteam` declarado en `opencode.json` a la versión instalada. Reinicia opencode para que recargue el plugin.
+- Vuelve a ejecutar `openteam setup` **solo** si quieres regenerar la configuración (cambiar runtimes, modelos o baseline). Pedirá confirmación antes de sobrescribir `opencode.json`, `.opencode/openteam.json` o `.opencode/agent/openteam.md`; **no toca los subagentes** que el orquestador haya creado a demanda.
+- Ajustes puntuales sin reinit: `openteam baseline set <provider/model>` o `openteam baseline auto`.
+
+## Configuración
+
+La configuración runtime canónica vive en `.opencode/openteam.json`; este repositorio incluye `.opencode/openteam.example.json` como ejemplo completo. La forma validada por Zod es la de `src/config/schema.ts`. `telemetry` es una opción del plugin leída por `src/index.ts`, no parte del objeto `OpenTeamConfig` persistido.
+
+| Key | Tipo | Default | Descripción |
+| --- | --- | --- | --- |
+| `baseline.mode` | `"auto" \| "pinned"` | `"auto"` | En `auto`, usa perfiles frontier cheapest-capable cuando se pasan al router; en `pinned`, usa `baseline.pinnedModel` si existe. |
+| `baseline.pinnedModel` | `ModelRef \| null` | `null` | Modelo frontier fijado explícitamente. `ModelRef` usa `{ "providerID": string, "modelID": string }`. |
+| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }` | Fallback frontier si no hay perfiles cheapest-capable o pin válido. |
+| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Modo de routing validado y reservado para política. |
+| `router.localDefault` | `ModelRef` | `{ "providerID": "ollama", "modelID": "qwen3:8b" }` | Modelo local principal. |
+| `router.trivialPromptMaxChars` | `number` entero positivo | `280` | Prompts sin código hasta este tamaño prefieren local. |
+| `router.frontierPromptMinChars` | `number` entero positivo | `2000` | Prompts desde este tamaño se tratan como candidatos a frontier si no aplican guards. |
+| `local.runtimes` | `LocalRuntime[]` | Ollama enabled en `http://localhost:11434/v1` con `qwen3:8b` | Lista mínima de un runtime local. |
+| `local.runtimes[].id` | `"ollama" \| "lmstudio" \| "foundry-local"` | requerido | Runtime local. |
+| `local.runtimes[].enabled` | `boolean` | `true` | Habilita o deshabilita ese runtime. |
+| `local.runtimes[].baseURL` | URL opcional | según runtime/config | Endpoint OpenAI-compatible `/v1`; Foundry Local puede omitirlo si usa discovery. |
+| `local.runtimes[].discovery` | `"cli" \| "sdk" \| "manual"` opcional | sin default por item | Discovery de Foundry Local; el registry usa CLI si está configurado y no es `manual`. |
+| `local.runtimes[].defaultModel` | `ModelRef` | requerido | Modelo por defecto de ese runtime. |
+| `budgets.sessionUSD` | `number` positivo opcional | sin límite | Presupuesto frontier por sesión. |
+| `budgets.monthlyUSD` | `number` positivo opcional | sin límite | Presupuesto frontier mensual. |
+| `budgets.frontierTokensPerSession` | `number` entero positivo opcional | sin límite | Límite de tokens frontier por sesión. |
+| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | Si es `true`, agotar presupuesto devuelve `blockFrontier`; si es `false`, fuerza local. |
+| `privacyMode` | `"forceLocalOnSensitive" \| "consentBeforeFrontier" \| "off"` | `"forceLocalOnSensitive"` | Política de privacidad para tareas sensibles. |
+| `telemetry.enabled` | `boolean` plugin option | `true` | Activa/desactiva escritura JSONL. |
+| `telemetry.path` | `string` plugin option | `.opencode/openteam-telemetry.jsonl` | Ruta del log `CostRecord` JSONL. |
+
+## Uso
+
+En cada turno, openteam deriva señales del prompt (`promptChars`, `hasCode`, `privacySensitive`, `requiresTools` y override de modelo si existe), ejecuta `chooseModel` y asigna `output.message.model`.
+
+La orquestación multiagente usa roles estáticos y subsesiones opencode:
+
+| Rol | Agent opencode | Tier base | Política |
+| --- | --- | --- | --- |
+| `rusty` | `architect` | `hard` | Arquitectura y decisiones de alto riesgo; frontier auto. |
+| `livingston` | `integration` | `moderate` | Integración TS/opencode; tool calling por defecto. |
+| `yen` | `local-runtime` | `moderate` | Runtimes locales; local-first con fallback frontier. |
+| `basher` | `routing-cost` | `moderate` | Router, coste y presupuesto; local-first. |
+| `scribe` | `scribe` | `trivial` | Documentación y resúmenes; local-first. |
+| `linus` | `tester` | `simple` | Tests y contratos; local-first con tools. |
+
+`runRoleTask` ejecuta una subsesión; `runRoleTasks` ejecuta varias con `batchID`. Los roles con `destructive` o `multiFileEdit` elevan el tier antes de elegir modelo.
+
+Para ver ahorro y decisiones, revisa el JSONL de telemetría. Campos clave: `promptHash`, `promptChars`, `tier`, `routeKind`, `selected`, `rationale`, `estimatedCostUSD`, `baselineCostUSD`, `estimatedSavingsUSD`, `budgetAction`, `tokensIn` y `tokensOut`.
+
+## Comandos runtime
+
+openteam expone comandos para inspeccionar y cambiar el routing sin editar JSON a mano. Hay tres superficies equivalentes:
+
+### 1. Tool en la conversación
+
+El plugin registra la herramienta `openteam`. Pídele al agente que la use, o instala el comando `/openteam` (ver más abajo). Acciones:
+
+- `show` — muestra el baseline efectivo.
+- `set` (con `model` en formato `provider/model`) — fija el baseline (modo `pinned`).
+- `auto` — vuelve a cheapest-capable (modo `auto`).
+- `doctor` — diagnóstico de runtimes locales, privacidad y telemetría.
+- `report` — resumen de coste y ahorro desde la telemetría.
+
+Los cambios de `set`/`auto` se persisten en `.opencode/openteam.json` y aplican en el siguiente arranque del plugin.
+
+### 2. Slash command `/openteam`
+
+`openteam setup` **genera automáticamente** `.opencode/command/openteam.md`, así que el comando `/openteam` aparece en opencode sin pasos manuales. (Si vienes de una versión anterior, vuelve a ejecutar `openteam setup` para crearlo, o cópialo a mano a tu proyecto o a `~/.config/opencode/command/`.) Después:
+
+```text
+/openteam baseline show
+/openteam baseline set anthropic/claude-sonnet-4-5
+/openteam baseline auto
+/openteam doctor
+/openteam agents
+/openteam console
+/openteam report
+```
+
+> ¿No ves `/openteam` en opencode? Asegúrate de que existe `.opencode/command/openteam.md` (lo crea `openteam setup`) y **reinicia/recarga opencode** para que descubra el comando.
+
+### 3. CLI (`bin`)
+
+El paquete expone el binario `openteam`. Con instalación global:
+
+```powershell
+bun add --global @jmanuelcorral/openteam@latest
+openteam baseline show
+openteam baseline set openai/gpt-5-mini
+openteam doctor --config .opencode/openteam.json
+openteam agents
+openteam console
+openteam report --telemetry .opencode/openteam-telemetry.jsonl
+openteam yolo status
+openteam yolo on
+openteam local status
+openteam local off
+```
+
+Flags: `--config <path>` y `--telemetry <path>` sobrescriben las rutas por defecto; `--opencode <path>` apunta el comando `yolo` a un `opencode.json` concreto.
+
+### Ver el LLM de cada agente: `openteam agents`
+
+Lista los agentes de `.opencode/agent/` indicando **qué LLM usa cada uno**: si es **local** (Ollama/LM Studio/Foundry, sin coste de tokens) o **frontier** (consume tu suscripción), y el **proveedor** (Anthropic, OpenAI, GitHub Copilot, Google…). Los agentes sin `model` propio **heredan** el default de `opencode.json` (que openteam enruta local-first por mensaje).
+
+```powershell
+openteam agents
+```
+
+```text
+openteam agents — LLM por agente:
+
+  ● openteam  [primary ]  frontier · Anthropic (consume tu suscripción) (anthropic/claude-sonnet-4-5)
+  ○ basher    [subagent]  local · Ollama (sin coste de tokens) (ollama/qwen3:8b)
+  ○ scribe    [subagent]  hereda default → frontier · Anthropic (consume tu suscripción) · openteam enruta local-first por mensaje
+
+Default de opencode.json: anthropic/claude-sonnet-4-5 (frontier · Anthropic)
+Leyenda: ● primary · ○ subagent · local = sin coste de tokens · frontier = consume tu suscripción.
+```
+
+También está disponible **dentro de opencode**: pídele a openteam la lista de agentes y ejecutará la acción `agents` de su herramienta de comandos.
+
+
+### Modo YOLO (auto-aprobar permisos)
+
+El **modo YOLO** hace que opencode auto-apruebe **todos** los permisos (equivale al flag nativo `opencode --auto`, pero persistente). Escribe la regla global `permission: { "*": "allow" }` en `opencode.json` y **regenera el agente `openteam`** (`.opencode/agent/openteam.md`) con el mismo comodín, conservando el resto de tu configuración:
+
+```powershell
+openteam yolo status   # ¿está activo?
+openteam yolo on       # activa YOLO
+openteam yolo off      # desactiva YOLO
+```
+
+También puedes activarlo durante `openteam setup` (te lo pregunta), o al vuelo con `opencode --auto` sin tocar la config.
+
+> **Importante: el permiso del agente anula al global.** opencode fusiona el permiso del frontmatter de cada agente **después** del global y gana la última regla que casa; por eso `openteam yolo on/off` regenera `.opencode/agent/openteam.md` para que su `permission` coincida con el estado YOLO. Sin esto, un `bash: ask`/`external_directory: deny` en el agente seguiría pidiendo confirmación aunque el global fuese `"*": allow`. Tras cambiar el modo, **reinicia o recarga opencode** para que los agentes tomen los nuevos permisos, y crea los subagentes con el mismo comodín cuando YOLO esté activo (el orquestador ya lo hace).
+
+> **YOLO no desactiva la privacidad de openteam.** Solo afecta a las aprobaciones de permisos de opencode; con `privacyMode: "forceLocalOnSensitive"`, los prompts sensibles siguen sin salir a frontier. Úsalo solo en entornos de confianza: auto-aprueba también `bash`, escrituras y accesos fuera del workspace (salvo reglas `deny` explícitas).
+
+### Solo frontier (sin runtime local): `openteam local`
+
+Si **no tienes ningún runtime local** (Ollama/LM Studio/Foundry Local) o prefieres no usarlo, puedes forzar que openteam enrute **siempre a modelos frontier**. `openteam setup` ya activa este modo automáticamente cuando no habilitas ningún runtime, pero puedes alternarlo en cualquier momento sin repetir el setup:
+
+```powershell
+openteam local status   # ¿local-first o solo frontier? + runtimes configurados
+openteam local off      # solo frontier (desactiva el routing local-first)
+openteam local on       # vuelve al routing local-first
+```
+
+Esto persiste el flag `router.frontierOnly` en `.opencode/openteam.json`. Con `frontierOnly` activo, el router escoge el **frontier cheapest-capable** en lugar de la heurística local-first, pero **respeta la privacidad, los presupuestos y los overrides explícitos por tarea**: los prompts sensibles con `forceLocalOnSensitive` no salen a frontier, y `local off` degrada esa política a `consentBeforeFrontier` (imposible forzar local sin runtime) informándote del cambio.
+
+### Modo desatendido: `openteam loop` (patrón Ralph) 🎯 *(diseño)*
+
+Segundo modo de operación: un **bucle externo** que invoca `opencode run` contra un backlog persistente hasta vaciarlo, con contexto fresco por iteración y topes de seguridad (presupuesto, máx. iteraciones, sin-progreso). Complementa al orquestador interactivo, no lo sustituye. Consulta el diseño y los ejemplos en **[docs/loop.md](docs/loop.md)**.
+
+### Console web multi-sesión (se lanza desde la CLI) — alfa
+
+> ⚠️ **Alfa — sin terminar.** La Console (y el comando `tunnel` de más abajo) es
+> una funcionalidad **experimental** que todavía puede **rehacerse o
+> reconstruirse**, con cambios incompatibles en su UI, endpoints, config (bloque
+> `console`) y formato de eventos. El router, presupuestos, telemetría y el core
+> de memoria son estables; la superficie web aún no. Úsala para observación
+> local, no como API estable.
+
+openteam expone una **Console web local** que **lanzas tú desde la CLI** con
+`openteam console`.
+Agrega **todas** las sesiones de opencode a la vez: puedes tener varias pestañas
+de opencode abiertas y todas aparecen en la **misma** Console, con una pestaña por
+sesión (más "Todas"), porque cada plugin **escribe eventos redactados** en logs
+JSONL por sesión y la Console los vigila (`fs.watch`) y **agrega**.
+
+Muestra en vivo: **coste y tokens reales por mensaje** (input/output/reasoning/
+cache), **toolcalls con duración** y ok/fallo, ruteo reciente (coste/ahorro y
+modelo elegido, **solo hashes de prompt, nunca el texto**), **decisiones** de los
+agentes (scribe) y **reuniones** (batches multi-agente del orquestador), progreso
+del backlog del loop, el equipo de agentes (LLM local/frontier de cada uno) y
+últimos commits. Se actualiza por **SSE** (con *polling* de respaldo).
+
+Cada pestaña de sesión incluye además una **vista "Sesión"**: una consola por la
+que puedes **ver la salida en vivo** (SSE) y **enviar prompts** o **responder
+permisos** a esa sesión de opencode, autenticada con un **token efímero** por
+arranque. Opcionalmente, con el flag `terminal.pty`, una **vista "Terminal"** abre
+una **shell real** en el workspace vía la API de PTY de opencode (sin `node-pty`).
+
+Lánzala contra el repo actual; escucha en loopback y corre hasta **Ctrl+C**:
+
+```powershell
+openteam console          # imprime la URL y sirve la Console multi-sesión
+openteam console --open   # además abre el navegador
+openteam console --status # solo imprime la config (no lanza el servidor)
+```
+
+Las sesiones se leen de:
+
+```text
+.opencode/openteam/sessions/*.jsonl
+```
+
+Puedes ajustar host/puerto y la terminal en `.opencode/openteam.json` (bloque
+`console`):
+
+```json
+{
+  "console": {
+    "host": "127.0.0.1",
+    "port": 4599,
+    "autoPortFallback": true,
+    "refreshMs": 2000,
+    "recentRoutes": 50,
+    "openBrowser": false,
+    "terminal": { "enabled": true, "pty": false }
+  }
+}
+```
+
+> **Seguridad**: el servidor escucha **solo en loopback** (`127.0.0.1`/`localhost`, validado por Zod) y **nunca expone prompts** (solo `promptHash`), args de toolcall ni contenido de mensajes: solo contadores, costes y resúmenes redactados. La vista "Sesión"/"Terminal" exige el token efímero. Si el puerto está ocupado y `autoPortFallback` es `true`, prueba el siguiente libre.
+
+### Acceso remoto seguro: `openteam tunnel` — alfa
+
+> ⚠️ **Alfa — sin terminar.** Igual que la Console, `tunnel` es experimental y
+> puede rehacerse o reconstruirse. Trata sus flags y comportamiento como
+> inestables.
+
+Para acceder a la Console (y, opcionalmente, operar la terminal) **desde fuera**,
+`openteam tunnel` la expone vía **Microsoft Dev Tunnels** en lugar de bindear a
+`0.0.0.0`. Comprueba que `devtunnel` esté instalado y con sesión iniciada,
+hospeda el puerto de la Console e imprime la URL pública hasta **Ctrl+C**:
+
+```powershell
+openteam tunnel                    # expone solo la Console (observación), autenticado
+openteam tunnel --terminal         # además expone opencode para la terminal remota
+openteam tunnel --allow-anonymous --yes  # túnel anónimo (requiere doble confirmación)
+```
+
+> **Seguridad del túnel**: autenticado por defecto. La **terminal remota** exige
+> `OPENCODE_SERVER_PASSWORD` definido; sin ella, `--terminal` se ignora y solo se
+> expone la Console (observación). El túnel **anónimo** requiere `--yes` (doble
+> confirmación) y avisa de que opencode puede ejecutar comandos y editar ficheros.
+> Instala devtunnel con `winget install Microsoft.devtunnel` e inicia sesión con
+> `devtunnel user login`.
+
+### Memoria del equipo por MCP (solo lectura): `openteam mcp`
+
+`openteam mcp` arranca un **servidor MCP de solo lectura** (JSON-RPC 2.0 sobre
+stdio, sin dependencias) que expone la memoria del equipo agregada desde los
+eventos por sesión para que agentes/herramientas la consulten. Se apoya en el
+mismo `StorageProvider` que la Console y **nunca** expone prompts crudos, solo el
+estado ya redactado. Tools disponibles: `list_decisions` (filtrable por
+`agent`/`tag`), `list_meetings`, `list_sessions` y `cost_summary` (coste/tokens
+reales + ahorro estimado vs baseline all-frontier).
+
+Regístralo en `opencode.json` como cualquier MCP server local:
+
+```json
+{
+  "mcp": {
+    "openteam-memory": {
+      "type": "local",
+      "command": ["openteam", "mcp"]
+    }
+  }
+}
+```
+
+#### Recall semántico (opt-in): `recall_facts`, `recall_preferences`, `similar_tasks`
+
+Además de la memoria de equipo, `openteam mcp` puede exponer **recall semántico**
+de la memoria de conocimiento long-term (hechos, preferencias, tareas similares).
+Está **desactivado por defecto**; se activa con el bloque `memory.semantic` en
+`.opencode/openteam.json`:
+
+```json
+{
+  "memory": {
+    "semantic": { "enabled": true }
+  }
+}
+```
+
+Al activarlo, y si hay un runtime local con `baseURL`, el servidor añade tres
+tools: `recall_facts`, `recall_preferences` y `similar_tasks`. La query se embebe
+**en local** (nunca sale a frontier) y los records están **redactados en origen**
+(`storeContent=false` por defecto), por lo que las tools nunca devuelven prompts
+crudos. Si falta `bun:sqlite` o el índice no puede abrirse, `openteam mcp`
+**degrada con seguridad** y sigue exponiendo solo la memoria de equipo.
+
+#### Consolidación / olvido: `openteam memory consolidate`
+
+La memoria long-term **olvida** por decay: la confianza de cada record decae con
+el tiempo y, al caer bajo el umbral, se marca como soft-invalidated (sin borrar:
+el histórico se conserva para auditoría "as-of"). Ejecuta la pasada de olvido con:
+
+```powershell
+openteam memory consolidate
+```
+
+Anexa *tombstones* al log de memoria y reporta cuántos records se olvidaron. Es
+idempotente y no destructivo.
+
+#### Push automático a contexto (opt-in)
+
+Con la inyección activada, openteam **prepende** memoria relevante al prompt en
+cada turno (`chat.message`), respetando un presupuesto de tokens:
+
+```json
+{
+  "memory": {
+    "semantic": {
+      "enabled": true,
+      "injection": { "enabled": true, "maxChars": 1200, "maxItems": 8 }
+    }
+  }
+}
+```
+
+Está **desactivado por defecto**. La inyección ocurre **después** de decidir el
+modelo, así que no altera el routing ni la telemetría, y **nunca rompe el turno**
+si el recall falla. Solo inyecta lo que ya está en los records (redactado en
+origen si `storeContent=false`).
+
+
+
+### Ollama
+
+```powershell
+ollama serve
+ollama pull qwen3:8b
+Invoke-RestMethod -Uri "http://localhost:11434/v1/models" -Method Get
+```
+
+### LM Studio
+
+1. Abre LM Studio.
+2. Carga un modelo compatible.
+3. Activa el servidor local OpenAI-compatible en el puerto `1234`.
+
+```powershell
+Invoke-RestMethod -Uri "http://localhost:1234/v1/models" -Method Get
+```
+
+### Foundry Local
+
+```powershell
+foundry service status
+```
+
+openteam extrae el puerto de la salida del CLI y normaliza el endpoint a `http://localhost:<PORT>/v1`.
+
+### Telemetría
+
+```powershell
+$telemetryPath = "C:\gitrepos\openteam\.opencode\openteam-telemetry.jsonl"
+Get-Content -Path $telemetryPath -Tail 5
+```
+
+### Verificación local
+
+```powershell
+Set-Location -Path "C:\gitrepos\openteam"
+bun test
+bun run typecheck
+bun run lint
+bun run format:check
+# Cuando el empaquetado de Fase 4 exponga el script:
+bun run build
+```
+
+### Desarrollo local en modo dev (sin registry)
+
+Para que la CLI global `openteam` y opencode usen la build local de este repo en
+lugar de la versión publicada (sin pasar por ningún registry), se enlaza el
+paquete con un symlink global:
+
+```powershell
+Set-Location -Path "C:\gitrepos\openteam"
+bun run link:local   # = bun run build && npm link
+```
+
+`npm link` crea un enlace global (junction/symlink) hacia este repo, así que tras
+cada `bun run build` la CLI global refleja el código local.
+
+Un hook `pre-push` versionado (`.githooks/pre-push`) puede ejecutar
+`bun run link:local` antes de cada `git push`, manteniendo la instalación local al
+día. La instalación de dependencias **no** modifica Git. Activa el hook
+explícitamente, una vez por clone:
+
+```powershell
+bun run hooks:install
+```
+
+El hook avisa si el build o el link fallan, pero **no bloquea** el push.
+
+## Publicación segura
+
+El workflow de release construye y verifica un único tarball sin permisos de
+escritura ni OIDC. Otro job publica exactamente ese artefacto, después de validar
+su integridad, mediante npm Trusted Publishing; un último job con solo
+`contents: write` lo adjunta a la GitHub Release. No existe fallback a credenciales
+persistentes y el CI normal no necesita configuración de npm.
+
+Antes de la primera release real, el propietario debe registrar en npm un Trusted
+Publisher para `@jmanuelcorral/openteam` con owner `jmanuelcorral`, repositorio
+`openteam`, workflow `release.yml`, acción permitida `npm publish` y sin
+environment. Hasta completar ese alta única, la publicación falla de forma
+cerrada. Tras la primera publicación OIDC correcta, hay que exigir 2FA sin tokens,
+revocar el antiguo token de automatización y eliminar su secreto heredado de
+GitHub Actions.
+
+## Privacidad
+
+Con `privacyMode: "forceLocalOnSensitive"`, si `TaskSignals.privacySensitive` es `true`, `chooseModel` usa local y no permite fallback frontier. Si no hay local utilizable, la decisión conserva la ruta local y registra la razón en `rationale`.
+
+La telemetría usa `hashPrompt`, actualmente `fnv1a32:<hash>`, y no serializa el prompt completo.
+
+## Calidad
+
+Gates no negociables:
+
+- `bun test`
+- Coverage global: líneas `>= 85%`, branches `>= 80%`.
+- Coverage de `src/router/**`: `100%` lines, branches, statements y functions.
+- `bun run typecheck`
+- `biome check .` o `bun run lint` + `bun run format:check`
+- Test de determinismo del router.
+- Tests de contrato si cambian hooks opencode, agents, comandos, providers o SDK.
+
+## Compatibilidad
+
+Consulta [docs/compatibility.md](docs/compatibility.md). Resumen verificado el `2026-08-19`:
+
+| Superficie | Versión / contrato |
+| --- | --- |
+| openteam | `0.1.41`; versión actual del paquete |
+| `@opencode-ai/plugin` | `1.17.13` |
+| `@opencode-ai/sdk` | `1.17.13` |
+| Hook de routing | `chat.message`; no `chat.params` para cambiar modelo |
+| Subsesiones | `client.session.create` + `client.session.prompt({ body: { model } })` |
+
+## Roadmap
+
+| Fase | Estado | Entregables |
+| --- | --- | --- |
+| 0. Scaffold/PoC | Hecha | TS/Bun, plugin mínimo, hook `chat.message`. |
+| 1. Local registry + router heurístico | Hecha | Ollama/LM Studio/Foundry, probes y `chooseModel` determinista. |
+| 2. Clasificador + perfiles + presupuesto + telemetría | Hecha | Clasificador local, `ModelCapabilityProfile`, budgets y `CostRecord`. |
+| 3. Orquestación multiagente | Hecha | Coordinator, roles, child sessions y permisos. |
+| 4. Empaquetado npm + docs | Hecha | Package exportable, README, ejemplos Windows y matriz de compatibilidad. |
+| 5. Comandos runtime | Hecha | `baseline show/set/auto`, `doctor` y `report` vía tool, `/openteam` y CLI `bin`. |
+
+## Licencia
+
+MIT. Consulta [LICENSE](LICENSE).
+
+## Agradecimientos e inspiración
+
+openteam se apoya en trabajo previo. Estos proyectos han inspirado su diseño: tomamos ideas de ellos, las adaptamos a opencode y las reimplementamos desde cero en TypeScript:
+
+- **[Squad](https://bradygaster.github.io/squad/)** ([bradygaster/squad](https://github.com/bradygaster/squad)) — el modelo de equipo multiagente temático creado a demanda: un único orquestador que castea subagentes especialistas según lo pide el trabajo. Inspiró el agente orquestador `openteam` y la convención de equipo/roster.
+- **[Superpowers](https://github.com/obra/superpowers)** de Jesse Vincent — una metodología componible basada en *skills* para agentes de código. Inspiró las convenciones de agentes basadas en skills y el flujo spec-first / subagent-driven.
+- **[agent-memory-dotnet](https://github.com/joslat/agent-memory-dotnet)** de José Luis Latorre — un modelo de memoria semántica a largo plazo para agentes. Inspiró el subsistema de memoria (extraer → rankear → consolidar → recuperar) con almacenamiento local-first y hash-redactado.
+
+Todas las marcas y nombres de proyecto pertenecen a sus respectivos dueños; los enlaces anteriores son atribución, no un aval.