vbgate · xunilzita-git · Aug 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,10 @@
+## Unreleased
+
+### Added
+- Dashboard and CLI now support Spanish (`es`) alongside English and Chinese.
+- CLI `--lang es` / `SUPERTASK_LANG=es`, and automatic selection from Spanish system locales.
+- Dashboard language switcher includes **ES**; `Accept-Language` and `supertask_locale` negotiate `es`.
+
 # Changelog
 
 All notable user-facing changes are recorded here. This project follows semantic versioning while it is in the `0.x` development series.

diff --git a/README.es.md b/README.es.md
@@ -0,0 +1,240 @@
+# SuperTask
+
+<p align="center"><strong>Encola. Programa. Reintenta. Sabe qué ocurrió.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-supertask"><img alt="npm version" src="https://img.shields.io/npm/v/opencode-supertask.svg"></a>
+  <a href="https://github.com/vbgate/opencode-supertask/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/vbgate/opencode-supertask/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/vbgate/opencode-supertask/blob/main/README.md">English</a> | <a href="https://github.com/vbgate/opencode-supertask/blob/main/README.zh-CN.md">简体中文</a> | <strong>Español</strong>
+</p>
+
+SuperTask convierte los comandos puntuales `opencode run` en operaciones durables de agentes. Ofrece a los agentes de OpenCode una cola SQLite persistente, programación, reintentos, control de concurrencia, cancelación segura, historial de ejecución y un panel web local.
+
+OpenCode puede ejecutar un agente ahora. SuperTask garantiza que el trabajo siga rastreado tras cerrar el terminal, si el proceso falla o si la máquina se reinicia.
+
+## ¿Por qué SuperTask?
+
+| Si necesitas... | Usa |
+| --- | --- |
+| Ejecutar un agente una sola vez | `opencode run` |
+| Ejecutar unos pocos comandos fijos a horas fijas | `cron`, `launchd`, `systemd` o GitHub Actions |
+| Reiniciar un proceso de larga duración con una programación | PM2 `cron_restart` |
+| Gestionar trabajos de agentes variables con estado durable, reintentos, prioridades e historial | **SuperTask** |
+
+SuperTask no es otro envoltorio sobre cron. El trabajo programado se convierte en una tarea normal de la cola durable, de modo que los trabajos manuales y programados comparten las mismas reglas de concurrencia, reintento, cancelación, dependencia e historial.
+
+## Qué obtienes
+
+| Capacidad | Qué significa |
+| --- | --- |
+| Cola durable | Las tareas y cada ejecución sobreviven a reinicios de proceso y de máquina en SQLite WAL |
+| Tres tipos de programación | Cron, retraso de una sola vez e intervalo fijo recurrente |
+| Recuperación automática | Presupuesto de reintentos, backoff exponencial, estado dead-letter y reintento manual |
+| Ejecución controlada | Concurrencia global, orden por prioridad, dependencias y serialización global por lote |
+| Conciencia de proyecto | Cada tarea conserva su directorio de proyecto OpenCode, agente, modelo y variante opcional |
+| Manejo seguro de procesos | Cancelación y apagado esperan a que el grupo de procesos Unix gestionado de OpenCode se drene |
+| Ejecuciones observables | ID de sesión, comando exacto reproducible, salida del modelo, herramientas, errores y JSONL en bruto |
+| Panel local | Crear, programar, inspeccionar, reintentar, cancelar y diagnosticar desde `127.0.0.1` |
+
+## Inicio rápido en tres minutos
+
+### 1. Instala una versión exacta
+
+```bash
+VERSION="$(npm view opencode-supertask dist-tags.latest)"
+npm install -g "opencode-supertask@$VERSION"
+opencode plugin "opencode-supertask@$VERSION" --global --force
+```
+
+Fijar la versión exacta mantiene alineados el plugin de OpenCode, la CLI global y el Gateway. No lo sustituyas por el nombre del paquete sin versión ni por `@latest` en `opencode.json`.
+
+### 2. Reinicia OpenCode e inicia el Gateway
+
+```bash
+supertask install   # recomendado: arranque con PM2, recuperación ante fallos y rotación de logs
+```
+
+Para desarrollo en primer plano:
+
+```bash
+supertask gateway
+```
+
+El plugin nunca instala servicios globales al arrancar OpenCode. La configuración de PM2 solo ocurre cuando ejecutas explícitamente `supertask install`.
+
+### 3. Pide a OpenCode que cree una tarea
+
+```text
+Crea una SuperTask llamada "Revisar errores de API".
+Usa el agente build en este proyecto, reintenta dos veces y ejecútala ahora.
+```
+
+OpenCode recibe ocho herramientas nativas del plugin `supertask_*`. El directorio del proyecto actual se toma del contexto de herramientas de OpenCode y no se confía en la entrada del modelo.
+
+### 4. Observa la ejecución
+
+```bash
+supertask status
+supertask list --limit 10
+supertask ui
+```
+
+El panel se abre en <http://127.0.0.1:4680>.
+
+## Cómo funciona
+
+```mermaid
+flowchart LR
+    A[Herramientas OpenCode / CLI / Panel] --> B[Cola de tareas SQLite]
+    B --> C[Gateway]
+    C --> D[Worker]
+    C --> E[Scheduler]
+    C --> F[Watchdog]
+    D --> G[opencode run]
+    G --> H[Historial de ejecución y sesión]
+```
+
+Un único Gateway posee las transiciones de estado en tiempo de ejecución. Los clientes crean y gestionan trabajo; solo el Gateway marca las ejecuciones como iniciadas, completadas, fallidas, reintentadas o canceladas.
+
+## Úsalo a tu manera
+
+### Lenguaje natural en OpenCode
+
+```text
+Ejecuta una revisión de seguridad con el agente build, el modelo provider/model y la variante high.
+
+Cada día laborable a las 9:00, crea una tarea de informe para este proyecto.
+
+Muestra las tareas fallidas de este proyecto y reintenta las recuperables.
+
+Comprueba si el lote "release" se está ejecutando en otro proyecto.
+```
+
+Herramientas del plugin disponibles:
+
+```text
+supertask_add       supertask_schedule  supertask_status   supertask_retry
+supertask_list      supertask_get       supertask_next     supertask_upgrade
+```
+
+### CLI
+
+```bash
+# Encolar trabajo
+supertask add --name "Revisión de seguridad" --agent build \
+  --model openai/gpt-5.6-sol --variant xhigh \
+  --prompt "Revisar autenticación y autorización" \
+  --importance 5 --urgency 4 --max-retries 2 \
+  --retry-backoff 30s --timeout 30min
+
+# Programar trabajo
+supertask template add --name "Informe laborable" --agent build \
+  --model openai/gpt-5.6-sol --variant high \
+  --prompt "Resumir cambios importantes del proyecto" \
+  --type cron --cron "0 9 * * 1-5"
+
+# Inspeccionar y recuperar
+supertask status
+supertask list --status failed --limit 20
+supertask retry --id 42
+supertask cancel --id 42
+```
+
+Ejecuta `supertask --help` o `supertask <command> --help` para la superficie completa de comandos. La ayuda de la CLI y los diagnósticos legibles admiten `auto`, `en`, `es` y `zh-CN`.
+
+## Panel
+
+El panel adaptable admite inglés, español y chino, temas claro y oscuro, y cuatro vistas centradas:
+
+| Página | Propósito |
+| --- | --- |
+| Cola de tareas | Explorar proyectos, crear/editar tareas, ver prioridades y estado activo, reintentar, cancelar o eliminar con seguridad |
+| Tareas programadas | Crear/editar plantillas cron, retrasadas y recurrentes; ejecutar una de inmediato sin saltarse la cola |
+| Registros de ejecución | Leer salida estructurada, herramientas, errores, sesiones y el comando histórico exacto |
+| Estado del sistema | Inspeccionar la configuración activa, la salud, la concurrencia y el mantenimiento de la base de datos con copia de seguridad previa |
+
+El selector de proyectos lee la salida real de `opencode agent list` y `opencode models --verbose` del directorio elegido, de modo que los formularios solo ofrecen modelos disponibles localmente, las variantes declaradas de cada modelo y agentes directamente ejecutables. Dejar la variante en su valor predeterminado omite `--variant` y sigue la configuración del agente/modelo.
+
+## Fiabilidad sin rodeos
+
+- SQLite `BEGIN IMMEDIATE` protege el bloqueo de un solo Gateway y la serialización global por lote.
+- La selección de candidatos y la transición a `running` ocurren en una sola transacción inmediata, de modo que ediciones concurrentes no pueden alterar una tarea reclamada.
+- Cada ejecución gestionada tiene una identidad de lanzador única y un grupo de procesos Unix aislado.
+- Una ejecución solo se cierra después de que el lanzador demuestra que todo el grupo de procesos se ha drenado.
+- La contención de procesos termina en ese grupo: los descendientes que llaman deliberadamente a `setsid()` o arrancan como daemons desacoplados deben gestionar su propio ciclo de vida.
+- El apagado y la cancelación fallan de forma cerrada cuando no se puede demostrar la propiedad del proceso.
+- `supertask doctor` verifica OpenCode, el plugin fijado efectivo, la caché, la CLI, el paquete del Gateway, el bloqueo de listo, SQLite, el panel y el entorno PM2.
+- Vaciar y restaurar la base de datos son operaciones transaccionales, con copia de seguridad previa, coherentes con WAL y rechazan el trabajo activo.
+
+Las garantías detalladas y las reglas de recuperación están en [Architecture](docs/architecture.md) y [Operations and Troubleshooting](docs/operations.md).
+
+## Actualizar y diagnosticar
+
+```bash
+supertask upgrade          # actualizar solo cuando las versiones o componentes hayan divergido
+supertask upgrade --force  # reinstalar la versión actual, refrescar el entorno y reiniciar
+supertask doctor
+supertask doctor --smoke --smoke-agent build --smoke-model provider/model --smoke-variant high
+```
+
+Cuando todos los componentes ya coinciden con npm `latest`, la actualización normal no hace nada y no reinicia el Gateway. Los diagnósticos smoke realizan una llamada real al modelo; el `doctor` ordinario no.
+
+## Requisitos
+
+- OpenCode
+- Bun 1.1.45 o posterior
+- Node.js/npm para el flujo documentado de instalación y actualización
+- macOS o Linux para la ejecución de tareas del Gateway
+
+La ejecución del Worker en Windows permanece deshabilitada hasta que el aislamiento con OS Job Object pueda ofrecer un drenado gestionado equivalente y una prueba recuperable. La ejecución de la cola no requiere PM2 cuando el Gateway corre en primer plano.
+
+## Instalar desde el código fuente
+
+```bash
+git clone https://github.com/vbgate/opencode-supertask.git
+cd opencode-supertask
+bun install
+bun run build
+```
+
+Apunta OpenCode al archivo del plugin construido:
+
+```json
+{
+  "plugin": [
+    "file:///home/user/src/opencode-supertask/dist/plugin/supertask.js"
+  ]
+}
+```
+
+Luego reinicia OpenCode y ejecuta `bun run gateway` desde el repositorio.
+
+## Documentación
+
+- [Operaciones y resolución de problemas](docs/operations.md)
+- [Arquitectura y decisiones actuales](docs/architecture.md)
+- [Changelog](CHANGELOG.md)
+- [Índice de documentación](docs/README.md)
+- [Reglas para contribuidores y agentes](AGENTS.md)
+
+## Desarrollo
+
+```bash
+bun install --frozen-lockfile
+bun test
+bun run typecheck
+bun run typecheck:tests
+bun run lint
+bun run test:coverage
+bun run test:browser
+bun run build
+bun run package:smoke
+```
+
+## Licencia
+
+MIT
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>English</strong> | <a href="https://github.com/vbgate/opencode-supertask/blob/main/README.zh-CN.md">简体中文</a>
+  <strong>English</strong> | <a href="https://github.com/vbgate/opencode-supertask/blob/main/README.zh-CN.md">简体中文</a> | <a href="https://github.com/vbgate/opencode-supertask/blob/main/README.es.md">Español</a>
 </p>
 
 SuperTask turns one-off `opencode run` commands into durable Agent operations. It gives OpenCode agents a persistent SQLite queue, scheduling, retries, concurrency control, safe cancellation, execution history, and a local Web Dashboard.
@@ -144,11 +144,11 @@ supertask retry --id 42
 supertask cancel --id 42
 ```
 
-Run `supertask --help` or `supertask <command> --help` for the complete command surface. CLI help and human-readable diagnostics support `auto`, `en`, and `zh-CN`.
+Run `supertask --help` or `supertask <command> --help` for the complete command surface. CLI help and human-readable diagnostics support `auto`, `en`, `es`, and `zh-CN`.
 
 ## Dashboard
 
-The responsive Dashboard supports English and Chinese, light and dark themes, and four focused views:
+The responsive Dashboard supports English, Spanish, and Chinese, light and dark themes, and four focused views:
 
 | Page | Purpose |
 | --- | --- |

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -144,7 +144,7 @@ supertask retry --id 42
 supertask cancel --id 42
 ```
 
-运行 `supertask --help` 或 `supertask <命令> --help` 查看完整参数。CLI 帮助和人类可读诊断支持 `auto`、`zh-CN` 和 `en`。
+运行 `supertask --help` 或 `supertask <命令> --help` 查看完整参数。CLI 帮助和人类可读诊断支持 `auto`、`zh-CN`、`en` 和 `es`。
 
 ## Web 控制台
 

diff --git a/docs/README.md b/docs/README.md
@@ -6,7 +6,7 @@
 
 | 文档 | 用途 | 权威范围 |
 |---|---|---|
-| [README](../README.md) / [简体中文](../README.zh-CN.md) | 产品定位、安装、快速开始、CLI 摘要 | 面向使用者的双语入口 |
+| [README](../README.md) / [简体中文](../README.zh-CN.md) / [Español](../README.es.md) | 产品定位、安装、快速开始、CLI 摘要 | 面向使用者的多语言入口 |
 | [CHANGELOG](../CHANGELOG.md) | 各稳定版本与未发布变更 | 面向升级与发布核对 |
 | [当前架构与决策](./architecture.md) | 组件边界、执行链路、状态语义、架构取舍 | 当前源码架构的权威说明 |
 | [运行与排障手册](./operations.md) | 启停、PM2、配置、重试、备份、故障定位 | 当前运行行为的权威说明 |

diff --git a/docs/operations.md b/docs/operations.md
@@ -89,7 +89,7 @@ PM2 生命周期操作和 macOS supervisor 始终先获取 `PM2_HOME/supertask-g
 
 CLI 的任务/模板 ID、优先级、重试次数和列表数量均按完整十进制整数解析；带尾随字符、小数、越界值和未知任务状态会返回非零退出码，不会再由 `parseInt` 静默截断。
 
-CLI 帮助、`doctor` 和数据库维护的交互式摘要支持 `auto | zh-CN | en`。默认 `auto` 根据 `LC_ALL`、`LC_MESSAGES`、`LANG` 选择，非中文 locale 回退英文；可用全局 `--lang` 或 `SUPERTASK_LANG` 覆盖。JSON 字段和底层诊断错误保持原样，不因界面语言变化而破坏 Agent、管道和脚本解析。
+CLI 帮助、`doctor` 和数据库维护的交互式摘要支持 `auto | zh-CN | en | es`。默认 `auto` 根据 `LC_ALL`、`LC_MESSAGES`、`LANG` 选择，中文/西班牙文 locale 分别选择对应语言，其余回退英文；可用全局 `--lang` 或 `SUPERTASK_LANG` 覆盖。JSON 字段和底层诊断错误保持原样，不因界面语言变化而破坏 Agent、管道和脚本解析。
 
 ## 完整配置