@jmanuelcorral/openteam 0.2.1 → 0.9.0

package/.opencode/command/openteam.md

@@ -1,5 +1,5 @@
 ---
-description: openteam runtime commands (baseline show|set|auto, doctor, agents, console, report)
+description: openteam runtime commands (baseline show|set|auto, doctor, agents, console, report, clear-cache)
 ---
 
 Use the `openteam` tool to execute the command indicated by the user: $ARGUMENTS
@@ -13,5 +13,6 @@ Interpret the arguments like this and call the `openteam` tool exactly once:
 - `agents` → `action: "agents"`
 - `console` → `action: "console"`
 - `report` → `action: "report"`
+- `clear-cache` → `action: "clear-cache"`
 
 Return the tool output as-is, without reinterpreting it.

package/.opencode/openteam.example.json

@@ -9,10 +9,7 @@
   },
   "router": {
     "mode": "balanced",
-    "localDefault": {
-      "providerID": "ollama",
-      "modelID": "qwen3:8b"
-    },
+    "localDefault": null,
     "trivialPromptMaxChars": 280,
     "frontierPromptMinChars": 2000
   },
@@ -20,7 +17,7 @@
     "runtimes": [
       {
         "id": "ollama",
-        "enabled": true,
+        "enabled": false,
         "baseURL": "http://localhost:11434/v1",
         "defaultModel": {
           "providerID": "ollama",
@@ -29,16 +26,25 @@
       },
       {
         "id": "lmstudio",
-        "enabled": true,
+        "enabled": false,
         "baseURL": "http://localhost:1234/v1",
         "defaultModel": {
           "providerID": "lmstudio",
           "modelID": "qwen2.5-coder-local"
         }
       },
+      {
+        "id": "lemonade",
+        "enabled": false,
+        "baseURL": "http://localhost:8000/api/v1",
+        "defaultModel": {
+          "providerID": "lemonade",
+          "modelID": "Qwen3-Coder-30B-A3B-Instruct-GGUF"
+        }
+      },
       {
         "id": "foundry-local",
-        "enabled": true,
+        "enabled": false,
         "discovery": "cli",
         "defaultModel": {
           "providerID": "foundry-local",
@@ -55,8 +61,21 @@
   },
   "privacyMode": "forceLocalOnSensitive",
   "graph": {
-    "mode": "off",
+    "mode": "shadow",
     "killSwitch": false,
     "operatorApproval": false
+  },
+  "orchestrator": {
+    "roles": {
+      "galadriel": {
+        "opencodeAgent": "galadriel",
+        "defaultTier": "moderate",
+        "minReasoningTier": 3,
+        "minCodeQualityTier": 3,
+        "needsToolCallingByDefault": true,
+        "preferredFrontierModels": [],
+        "localFirst": true
+      }
+    }
   }
 }

package/AGENTS.md

@@ -15,9 +15,11 @@ openteam is an opencode plugin built with **TypeScript + Bun** with **local-firs
 - Read `docs/architecture.md`, `docs/testing-and-quality.md`, and `PLAN.md` before large changes.
 - `router/` is pure: no I/O, clock, random, env vars, or logs.
 - `plugin/` contains opencode hooks; any use of an undocumented surface needs a contract test.
-- `local/` isolates Ollama, LM Studio, and Foundry Local.
+- `local/` isolates Ollama, LM Studio, Lemonade Server, and Foundry Local.
 - `config/` validates and persists `.opencode/openteam.json`.
 - `telemetry/` does not store full prompts; it uses a hash and redacted metadata.
+- `messages/` holds all user-facing text; it is pure and has no I/O.
+- `opencodeArtifacts/` builds the `.opencode/agent/*.md` and `.opencode/command/*.md` content that opencode consumes. That prose is model-facing, not user-facing — do not extract it into the message catalog.
 
 ## opencode config and agents
 
@@ -32,6 +34,7 @@ openteam is an opencode plugin built with **TypeScript + Bun** with **local-firs
 - Code, paths, types, and identifiers: English.
 - TypeScript strict, ESM only, Zod at boundaries.
 - Biome governs lint/format; do not introduce ESLint/Prettier unless a new decision is made.
+- **Any string a user can read — CLI output, warnings, errors surfaced to the user, prompts — must live in `src/messages/`, not inlined at the call site.** Strings that are not user-facing (log keys, ids, file paths, protocol literals, SQL, test fixtures, model-facing artifact prose) stay where they are. Enforcement: `tests/contract/messages-catalog-ratchet.test.ts` (shared literal walker: `tests/contract/literalWalker.ts`) gates `*.ts` files under `src/commands/**` and `src/console/**` — the CLI output layer. It deliberately does not gate all of `src/**`; `src/storage/**`, `src/plugin/**` etc. carry SQL and model-prompt prose that a detector cannot distinguish from user text. Every gated file is in exactly one of two lists: **MIGRATED** (must contain zero detectable inline user-facing messages — gaining one fails the build) or **LEGACY** (not yet extracted — the list may only shrink; when a LEGACY file no longer has any detectable message the gate fails and tells you to promote it). A new `src/commands/**` or `src/console/**` file that appears in neither list also fails, forcing an explicit, reviewable choice. Adding a file to a list to turn a red build green is a fake fix — the gate's own error message says so. Note: MIGRATED means "no *detectable* inline message"; the detector is high-precision / lower-recall by design.
 
 ## Test-first with Gherkin
 
@@ -51,6 +54,6 @@ openteam is an opencode plugin built with **TypeScript + Bun** with **local-firs
 ## Non-negotiables
 
 - No merge without tests, coverage, typecheck, lint/format, and determinism green.
-- Do not send `privacySensitive` data to frontier with `forceLocalOnSensitive`.
+- Privacy-sensitive tasks prefer local and are never misleadingly labelled. When `privacyMode` is `"forceLocalOnSensitive"` and a local runtime is configured, sensitive prompts stay local. When **no local runtime is configured**, they escalate to the frontier model, labelled `"frontier"` in telemetry, with rationale `"privacy-force-local-none-configured"` recorded. Hard blocking remains available via the `alwaysLocal` explicit override or the `blockFrontier` budget action. A startup warning fires when the privacy setting is inert (no local runtime configured).
 - Do not hardcode a premium frontier as the baseline: use a configurable cheapest-capable one.
 - Do not depend on real local runtimes, network, or secrets in CI.

package/README.es.md

@@ -35,7 +35,7 @@ El router mantiene una garantía de privacidad: con `privacyMode: "forceLocalOnS
 ## 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.
+- Registro de runtimes locales OpenAI-compatible: Ollama, LM Studio, Lemonade Server 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`.
@@ -46,12 +46,13 @@ El router mantiene una garantía de privacidad: con `privacyMode: "forceLocalOnS
 
 ## Requisitos
 
-- opencode compatible con `@opencode-ai/plugin` `1.18.18`.
+- opencode compatible con `@opencode-ai/plugin` `1.18.19`.
 - 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`.
+  - Lemonade Server en `http://localhost:8000/api/v1`.
   - Foundry Local con puerto dinámico descubierto por CLI en Windows.
 
 ## Instalación
@@ -68,6 +69,8 @@ El paquete se publica como `@jmanuelcorral/openteam`. Estas son las rutas de ins
 
 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`.
 
+> **Ruta de GitHub Packages:** las versiones se publican tanto en npmjs como en GitHub Packages privado. Consulta [docs/es/guide/install-github-packages.md](docs/es/guide/install-github-packages.md) para el procedimiento de instalación autenticada desde GitHub Packages, configuración del PATH en zsh y verificación del proveedor Lemonade.
+
 Para la carga directa desde opencode, basta con referenciar el paquete:
 
 ```jsonc
@@ -127,7 +130,7 @@ Para la carga directa desde opencode, basta con referenciar el paquete:
         "privacyMode": "forceLocalOnSensitive",
         "telemetry": {
           "enabled": true,
-          "path": ".opencode/openteam-telemetry.jsonl"
+          "path": ".opencode/openteam-local/telemetry.jsonl"
         }
       }
     ]
@@ -187,7 +190,7 @@ Durante desarrollo puedes cargar un plugin local desde `.opencode/plugins/opente
           }
         },
         "telemetry": {
-          "path": ".opencode/openteam-telemetry.jsonl"
+          "path": ".opencode/openteam-local/telemetry.jsonl"
         }
       }
     ]
@@ -197,10 +200,10 @@ Durante desarrollo puedes cargar un plugin local desde `.opencode/plugins/opente
 
 ## 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:
+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, Lemonade Server, Foundry Local) —que son **opcionales**: puedes usar openteam **solo con frontier**, o apuntar a un Ollama/LM Studio/Lemonade Server 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/openteam.json`: la configuración runtime validada de openteam (baseline, routing, runtimes locales, roles del orquestador y privacidad).
 - `.opencode/agent/openteam.md`: el **agente primario `openteam`**, visible en el Tab-switcher.
 
 ```powershell
@@ -222,15 +225,15 @@ El asistente:
 
 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`
+## 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).)
+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:
+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).
+- **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`.
 
@@ -302,19 +305,70 @@ Notas al actualizar:
 
 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.
 
+Los archivos de configuración son estrictos: las claves desconocidas fallan
+cerrado tanto en la CLI como en el plugin en vez de ignorarse en silencio. Los
+errores nombran cada ruta rechazada (por ejemplo `router.trivialPromptMxChars`)
+e incluyen una sugerencia de la clave más cercana cuando existe.
+Esta validación estricta se aplica al archivo de configuración en ambas rutas;
+las opciones programáticas del plugin son una superficie separada y aún no se
+validan de forma estricta (#102). Las configs existentes sin `configVersion`
+siguen siendo válidas porque openteam las migra a la versión actual antes de
+validarlas.
+
+### Resolución del archivo de configuración de opencode
+
+openteam lee la configuración del proyecto opencode desde **dos rutas candidatas**
+y las fusiona — igual que hace el propio opencode con múltiples archivos de config:
+
+| Prioridad | Ruta |
+| --- | --- |
+| Mayor (prevalece) | `.opencode/opencode.json` |
+| Base | `opencode.json` (raíz del proyecto) |
+
+Las claves no conflictivas de ambos archivos se conservan. Cuando la misma
+clave aparece en los dos, `.opencode/opencode.json` gana. Esto está verificado
+contra opencode 1.18.18: un provider declarado en cualquiera de las dos
+ubicaciones aparece en `opencode models --pure`.
+
+**Comentarios JSONC** — los comentarios de línea (`//`) y de bloque (`/* … */`)
+están permitidos en ambos archivos. El propio opencode los acepta; openteam los
+elimina antes de parsear, así que un archivo con comentarios funciona igual que
+uno JSON puro.
+
+**Config malformada** — si uno de los archivos candidatos existe pero no puede
+parsearse (JSON inválido, violación de schema), `doctor` y `agents` emiten un
+aviso que nombra el archivo problemático y continúan en vez de abortar.
+
+**Mensajes "provider not configured"** — nombran las dos rutas buscadas, para
+que sepas de inmediato si el archivo no se encontró o si el provider está
+genuinamente ausente en ambas ubicaciones.
+
+**Ubicación de escritura de `openteam setup`** — al configurar un proyecto nuevo
+(sin archivo de config opencode existente), `setup` escribe ahora en
+`.opencode/opencode.json`. Cuando se detecta un archivo existente, se actualiza
+en el mismo sitio — nunca se escribe en los dos a la vez. Usuarios que hacen
+upgrade: si no existe un `opencode.json` en la raíz, una nueva ejecución de
+`setup` escribirá en `.opencode/`.
+
+**Sin traversal ascendente** — openteam lee únicamente las dos rutas candidatas
+relativas al directorio de trabajo actual. No sube hasta la raíz git. Los
+comandos están diseñados para ejecutarse desde la raíz del proyecto; si los
+ejecutas desde un subdirectorio verás "provider not configured" y debes hacer
+`cd` a la raíz primero.
+
 | 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.localDefault` | `ModelRef \| null` | `null` | Modelo local principal. No configurado por defecto — ningún modelo local se enruta hasta que configures uno con `openteam setup` o manualmente. |
 | `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` | `LocalRuntime[]` | `[]` | Runtimes locales a sondear. Vacío por defecto — ningún runtime está configurado hasta que ejecutes `openteam setup` o añadas una entrada manualmente. |
+| `local.runtimes[].id` | `"ollama" \| "lmstudio" \| "foundry-local" \| "lemonade"` | 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[].baseURL` | URL opcional | según runtime/config | Endpoint OpenAI-compatible (`/v1` para Ollama/LM Studio, `/api/v1` para Lemonade); 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. |
@@ -322,8 +376,36 @@ La configuración runtime canónica vive en `.opencode/openteam.json`; este repo
 | `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. |
+| `orchestrator.roles` | `Record<string, AgentRoleProfile>` | `{}` | Perfiles de rol personalizados o sobrescritos, indexados por role ID. Las entradas de config se validan con el mismo schema estricto que los roles integrados y tienen prioridad sobre `TEAM_ROLES`; si una entrada omite `roleID`, se usa la clave del mapa. Los roles desconocidos no declarados aquí siguen usando el fallback neutral y avisan una vez. |
+| `orchestrator.roles.<role>.opencodeAgent` | `string` no vacío opcional | role ID | Nombre del agente opencode al que se despacha ese rol. |
+| `orchestrator.roles.<role>.defaultTier` | `"trivial" \| "simple" \| "moderate" \| "hard"` | requerido | Tier base de complejidad antes de aplicar heurística y elevación por permisos. |
+| `orchestrator.roles.<role>.minReasoningTier` | `1`–`5` | requerido | Capacidad mínima de razonamiento para candidatos frontier. |
+| `orchestrator.roles.<role>.minCodeQualityTier` | `1`–`5` | requerido | Capacidad mínima de calidad de código para candidatos frontier. |
+| `orchestrator.roles.<role>.needsToolCallingByDefault` | `boolean` | requerido | Si el rol requiere tool calling salvo que la tarea indique otra cosa. |
+| `orchestrator.roles.<role>.preferredFrontierModels` | `Array<ModelRef \| "auto">` | requerido | Modelos frontier preferidos; usa `[]` para un rol local-first sin preferencia frontier explícita. |
+| `orchestrator.roles.<role>.localFirst` | `boolean` | requerido | Si el rol conserva la postura local-first normal en vez de forzar frontier para tareas hard. |
 | `telemetry.enabled` | `boolean` plugin option | `true` | Activa/desactiva escritura JSONL. |
-| `telemetry.path` | `string` plugin option | `.opencode/openteam-telemetry.jsonl` | Ruta del log `CostRecord` JSONL. |
+| `telemetry.path` | `string` plugin option | `.opencode/openteam-local/telemetry.jsonl` | Ruta del log `CostRecord` JSONL. |
+
+Ejemplo de auditor de privacidad/seguridad personalizado:
+
+```jsonc
+{
+  "orchestrator": {
+    "roles": {
+      "galadriel": {
+        "opencodeAgent": "galadriel",
+        "defaultTier": "moderate",
+        "minReasoningTier": 3,
+        "minCodeQualityTier": 3,
+        "needsToolCallingByDefault": true,
+        "preferredFrontierModels": [],
+        "localFirst": true
+      }
+    }
+  }
+}
+```
 
 ## Uso
 
@@ -387,18 +469,20 @@ 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 report --telemetry .opencode/openteam-local/telemetry.jsonl
 openteam yolo status
 openteam yolo on
 openteam local status
 openteam local off
+openteam clear-cache
+openteam clear-cache --delete
 ```
 
-Flags: `--config <path>` y `--telemetry <path>` sobrescriben las rutas por defecto; `--opencode <path>` apunta el comando `yolo` a un `opencode.json` concreto.
+Flags: `--config <path>` y `--telemetry <path>` sobrescriben las rutas por defecto; `--opencode <path>` apunta el comando `yolo` a un `opencode.json` concreto. Un `--config` explícito puede ser relativo o absoluto y debe poder leerse; solo la búsqueda por defecto de `.opencode/openteam.json` cae a los defaults integrados cuando falta.
 
 ### 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).
+Lista los agentes de `.opencode/agent/` indicando **qué LLM usa cada uno**: si es **local** (Ollama/LM Studio/Lemonade/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
@@ -446,18 +530,38 @@ 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)*
+### Actualizar el plugin y limpiar la caché: `openteam clear-cache`
+
+opencode almacena cada instalación de plugin en un directorio de caché y no
+refresca las entradas existentes: no hay comparación de versión, TTL ni comando
+de evicción en upstream. Publicar una nueva versión del plugin no tiene **ningún
+efecto** en una máquina que ya tiene una entrada de caché. Borrar el directorio
+de caché es la única vía de evicción que existe.
+
+```powershell
+openteam clear-cache                       # solo informe — imprime la tabla, no borra nada
+openteam clear-cache --delete              # borra todas las entradas de caché coincidentes
+openteam clear-cache --cache-root <ruta>   # sobreescribe el directorio raíz de caché
+```
+
+Alias de slash command dentro de opencode: `/openteam-clear-cache`
+
+El modo por defecto (sin flags) imprime una tabla con columnas `spec dir`,
+`spec-pinned`, `installed` y `mtime` para cada entrada de caché
+`@jmanuelcorral/openteam*` encontrada. Solo se tocan entradas de ese scope.
+Los symlinks y reparse points de Windows aparecen como `[SKIP — reparse point]`
+y nunca se borran. En Windows, cierra opencode antes de ejecutar `--delete`
+para evitar errores `[LOCKED]`.
+
+Consulta [docs/es/guide/update-plugin.md](docs/es/guide/update-plugin.md)
+para la explicación completa del mecanismo de congelamiento y el procedimiento
+de actualización paso a paso.
 
-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)**.
+### Modo desatendido: `openteam loop` (patrón Ralph) 🎯 *(`--dry-run` verificado; despacho real en diseño)*
 
-### Console web multi-sesión (se lanza desde la CLI) — alfa
+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. Como propiedad de seguridad, `openteam loop` **se niega a ejecutarse de forma desatendida sin confirmación explícita**: ejecutado sin argumentos imprime *"Refusing to run unattended without confirmation. Re-run with --dry-run to preview the plan, or --yes to run."* y termina con código distinto de cero; `openteam loop --dry-run` previsualiza el plan (backlog, topes de iteraciones y presupuesto, sleep, contexto fresco y condiciones de parada) sin despachar nada. La previsualización con `--dry-run` y la negativa al invocarlo sin argumentos están **verificadas contra el binario publicado**; el despacho desatendido real (`--yes`) **aún no está verificado de extremo a extremo y sigue en fase de diseño**. Consulta el diseño y los ejemplos en **[docs/loop.md](docs/loop.md)**.
 
-> ⚠️ **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.
+### Console web multi-sesión (se lanza desde la CLI)
 
 openteam expone una **Console web local** que **lanzas tú desde la CLI** con
 `openteam console`.
@@ -487,10 +591,12 @@ openteam console --open   # además abre el navegador
 openteam console --status # solo imprime la config (no lanza el servidor)
 ```
 
+Consulta la [guía de la Console](docs/es/console.md) para la referencia completa.
+
 Las sesiones se leen de:
 
 ```text
-.opencode/openteam/sessions/*.jsonl
+.opencode/openteam-local/sessions/*.jsonl
 ```
 
 Puedes ajustar host/puerto y la terminal en `.opencode/openteam.json` (bloque
@@ -510,31 +616,11 @@ Puedes ajustar host/puerto y la terminal en `.opencode/openteam.json` (bloque
 }
 ```
 
-> **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
+**Vista del grafo de agentes en vivo.** La Console también puede renderizar un **grafo de agentes** en vivo de una ejecución de Graph; está **desactivada por defecto** y se activa con `console.graphView.enabled: true` — consulta [Graph observability web](docs/es/guide/graph-observability-web.md) para la configuración y los requisitos completos.
 
-> ⚠️ **Alfa — sin terminar.** Igual que la Console, `tunnel` es experimental y
-> puede rehacerse o reconstruirse. Trata sus flags y comportamiento como
-> inestables.
+> **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. El acceso remoto mediante `openteam tunnel` se **eliminó del MVP** (2026-08-31) y se redefinirá más adelante; la Console no tiene camino de exposición remota integrado.
 
-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`.
+**Estabilidad de la interfaz.** La superficie web de la Console es **pre-1.0**: su UI, sus endpoints, el bloque de configuración `console` y el formato de eventos pueden cambiar todavía. El router, los presupuestos, la telemetría y el core de memoria son estables.
 
 ### Memoria del equipo por MCP (solo lectura): `openteam mcp`
 
@@ -635,6 +721,12 @@ Invoke-RestMethod -Uri "http://localhost:11434/v1/models" -Method Get
 Invoke-RestMethod -Uri "http://localhost:1234/v1/models" -Method Get
 ```
 
+### Lemonade Server
+
+```powershell
+Invoke-RestMethod -Uri "http://localhost:8000/api/v1/models" -Method Get
+```
+
 ### Foundry Local
 
 ```powershell
@@ -646,14 +738,14 @@ openteam extrae el puerto de la salida del CLI y normaliza el endpoint a `http:/
 ### Telemetría
 
 ```powershell
-$telemetryPath = "C:\gitrepos\openteam\.opencode\openteam-telemetry.jsonl"
+$telemetryPath = "C:\ruta\a\tu\repo\.opencode\openteam-telemetry.jsonl"
 Get-Content -Path $telemetryPath -Tail 5
 ```
 
 ### Verificación local
 
 ```powershell
-Set-Location -Path "C:\gitrepos\openteam"
+Set-Location -Path "C:\ruta\a\tu\repo"
 bun test
 bun run typecheck
 bun run lint
@@ -669,7 +761,7 @@ 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"
+Set-Location -Path "C:\ruta\a\tu\repo"
 bun run link:local   # = bun run build && npm link
 ```
 
@@ -723,22 +815,26 @@ Gates no negociables:
 
 ## Compatibilidad
 
-Consulta [docs/compatibility.md](docs/compatibility.md). Resumen verificado el `2026-08-23`:
+Consulta [docs/compatibility.md](docs/compatibility.md). Resumen verificado el `2026-08-24`:
 
 | Superficie | Versión / contrato |
 | --- | --- |
-| openteam | `0.2.1`; versión actual del paquete |
-| `@opencode-ai/plugin` | `1.18.18` |
-| `@opencode-ai/sdk` | `1.18.18` |
+| openteam | `0.9.0`; versión actual del paquete |
+| `@opencode-ai/plugin` | `1.18.19` |
+| `@opencode-ai/sdk` | `1.18.19` |
 | Hook de routing | `chat.message`; no `chat.params` para cambiar modelo |
 | Subsesiones | `client.session.create` + `client.session.prompt({ body: { model } })` |
 
+## Contribuir
+
+Las contribuciones son bienvenidas. Lee [CONTRIBUTING.md](CONTRIBUTING.md) para la configuración de desarrollo (Bun), las barreras de calidad no negociables, los límites de módulos (`router/` es puro — sin I/O, reloj, aleatoriedad ni logging) y el proceso de pull request. Al participar aceptas cumplir nuestro [Código de conducta](CODE_OF_CONDUCT.md).
+
 ## 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. |
+| 1. Local registry + router heurístico | Hecha | Ollama/LM Studio/Lemonade/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. |