specrails-desktop 2.8.0 → 2.9.0

package/docs/guide/es/integrations/4-mobile-companion.md

@@ -0,0 +1,38 @@
+# La app complementaria para el móvil
+
+Specrails tiene una app complementaria para el teléfono para que puedas vigilar tus rails mientras estás lejos del escritorio: ver los trabajos en marcha, verlos terminar y mantenerte al tanto sin estar sentado frente al panel.
+
+## Para qué sirve
+
+La app complementaria es una superficie de **monitorización**. Se conecta a tu app de escritorio de Specrails en ejecución a través de tu red local y refleja en tu teléfono la actividad en vivo de proyectos y trabajos. Piénsala como una ventana de un vistazo a los mismos rails que verías de otro modo en el panel.
+
+## Emparejar tu teléfono
+
+El emparejamiento gira en torno a un **código QR** para que no tengas que teclear nada engorroso:
+
+1. Asegúrate de que tu app de escritorio de Specrails está en ejecución y de que tu teléfono está en la **misma red local** (misma Wi-Fi).
+2. En la app de escritorio, abre la pantalla de emparejamiento para mostrar un código QR.
+3. En la app complementaria de tu teléfono, escanea ese código.
+4. El teléfono descubre la app de escritorio en la red y se conecta.
+
+A partir de ahí, la app complementaria mantiene una conexión en vivo y transmite las listas de proyectos y las actualizaciones de los trabajos a medida que ocurren.
+
+## Cómo funciona la conexión
+
+La app de escritorio se anuncia en tu red local para que el teléfono pueda encontrarla, y el código QR lleva los datos que el teléfono necesita para conectarse de forma segura. Todo se queda en tu red local: la app complementaria habla directamente con tu máquina, no a través de ningún servicio en la nube.
+
+Como se basa en la red local, los dos dispositivos tienen que poder alcanzarse mutuamente. Si el emparejamiento no funciona:
+
+- Confirma que ambos dispositivos están en la **misma Wi-Fi** (y que la red no aísla a los clientes entre sí).
+- Asegúrate de que la app de escritorio está **en ejecución** cuando escaneas.
+- Vuelve a abrir la pantalla de emparejamiento para refrescar el código QR e inténtalo escanear de nuevo.
+
+## Qué verás
+
+Una vez emparejada, la app complementaria muestra tus proyectos y su actividad de trabajos en vivo, así que recibes las mismas actualizaciones de rails en tiempo real que fluyen al panel de escritorio, enviadas a tu teléfono según se producen. Es la forma más sencilla de enterarte en el momento en que un rail de larga duración llega a su fin.
+
+## Bueno saberlo
+
+- **Monitorización ante todo.** La app complementaria está pensada para mantener un ojo sobre los rails, no para dirigir todo el flujo de trabajo de escritorio desde el teléfono.
+- **Solo local.** Sin cuenta, sin relay en la nube: tu máquina y tu teléfono, en tu red.
+- **Mantén el escritorio despierto.** La app complementaria refleja una app de escritorio en ejecución; si tu máquina entra en suspensión o la app se cierra, las actualizaciones en vivo se pausan hasta que vuelva.

package/docs/guide/es/pipeline/1-rails-and-jobs.md

@@ -0,0 +1,94 @@
+# Rails y jobs
+
+Ya tienes specs en el tablero. Aquí es donde se convierten en código. Un **rail** es el carril que lleva una spec a través de todo el pipeline — Architect → Developer → Reviewer → Ship — ejecutando agentes de IA reales dentro del directorio de tu proyecto. En esta página verás cómo lanzar un rail, la cola de jobs y cómo seguir el trabajo en vivo.
+
+## Qué es un rail
+
+Imagina la pantalla dividida en dos:
+
+```
+SpecsBoard (izquierda)      Rails (derecha)
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  arrastra hacia
+#3 Cost limits      │ ────────────►   Rail 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   Rail 2   ▶ Play
+```
+
+Un rail es un **carril de ejecución**. Arrastras una tarjeta de spec desde el SpecsBoard hasta un rail y luego pulsas **▶ Play**. El rail lanza el pipeline y trabaja la spec de principio a fin, directamente en el directorio de trabajo de tu proyecto — editando archivos, ejecutando tests, todo lo necesario.
+
+Puedes tener varios rails para organizar el trabajo en carriles con nombre (uno para la funcionalidad en la que estás centrado, otro en cola detrás). Tienes más sobre multi-rail y procesamiento por lotes en [Batch implement y multifuncionalidad](batch-implement-and-multi-feature).
+
+## Lanzar un rail sobre una spec
+
+1. **Arrastra una tarjeta de spec** desde el SpecsBoard hasta un rail. El ID de la spec aparece en la lista de specs del rail. (¿Prefieres no arrastrar? Usa el popover **Mover a rail** en la tarjeta de la spec — muestra un punto de estado por cada rail para que no dejes trabajo en un carril ocupado.)
+2. **Elige un modo** si quieres algo distinto al predeterminado — el control segmentado de la cabecera del rail ofrece `Implement`, `Batch` y (solo en rails de Claude) `Ultra`.
+3. **Pulsa ▶ Play.**
+
+Eso es todo. El rail arranca un proceso de la CLI de IA en tu proyecto y empieza el pipeline.
+
+### Qué hay en la cabecera de un rail
+
+| Control | Qué hace |
+|---------|--------------|
+| **Pastilla de estado** | `idle`, `running` o `failed`. No hay un estado "completed" aparte — un rail vuelve a `idle` cuando su job termina limpiamente. |
+| **Lista de specs** | Los IDs asignados a este rail. Arrastra más para añadirlas, o sácalas para desvincularlas. |
+| **Control de modo** | `Implement` / `Batch` / `Ultra` — mira la tabla de más abajo. Se recuerda por rail. |
+| **Selector de perfil** | Qué perfil de agentes se ejecuta (solo en rails de Claude). Solo aparece cuando el proyecto tiene al menos un perfil. |
+| **Selector de motor** | Qué proveedor instalado ejecuta este rail — Claude, Codex o Gemini. Solo se muestra cuando el proyecto tiene más de un proveedor. Mira [Elegir un motor por rail](picking-an-engine-per-rail). |
+| **▶ Play / ■ Stop** | Iniciar o cancelar. |
+
+### Los tres modos de rail
+
+| Modo | Comando | Qué hace |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | Un job que cubre todas las specs del rail. Ejecuta el pipeline completo Architect → Developer → Reviewer → Ship. El predeterminado del día a día. |
+| **Batch** | `/specrails:batch-implement` | Un job que recorre las specs del rail de forma secuencial, en oleadas según sus dependencias. Lo mejor para varias specs relacionadas. |
+| **Ultra** | Ultracode | Claude implementa cada spec de forma autónoma, **saltándose** el pipeline. Un job independiente por spec. Solo Claude. |
+
+Ultra es el caso especial: se salta la cadena de agentes y le entrega a Claude la spec en bruto para que la trabaje con sus herramientas nativas. Es de final abierto, así que al pulsar Play primero se abre una confirmación, y un selector de modelo por rail te deja elegir Haiku / Sonnet / Opus. Solo aparece cuando el motor del rail es Claude.
+
+## La cola de jobs
+
+Cada vez que pulsas Play, la ejecución del rail se convierte en un **job**. La regla más importante que debes interiorizar:
+
+> **Un job a la vez, por proyecto.** Cada proyecto tiene una única cola. Dentro de un mismo proyecto solo se ejecuta un job de rail a la vez — el resto esperan en cola detrás y arrancan automáticamente a medida que se liberan huecos.
+
+Esto sorprende a quien añade tres rails esperando que se ejecuten en paralelo. No lo harán — no dentro del mismo proyecto. Añadir rails *organiza* tu trabajo en carriles; no hace que esos carriles se ejecuten a la vez.
+
+**El paralelismo real es entre proyectos.** Cada proyecto tiene su propia cola independiente, así que un rail en el Proyecto A y un rail en el Proyecto B se ejecutan al mismo tiempo sin competir. ¿Quieres más rendimiento? Abre más proyectos.
+
+No hay ninguna palanca global de concurrencia que ajustar. El único freno automático se basa en el presupuesto: si has fijado un presupuesto diario (de proyecto o de toda la app), la cola se pausa sola en cuanto el gasto de ese día llega al tope.
+
+## Verlo en marcha
+
+Encuentra todos los jobs en **Jobs**, en la barra lateral derecha del proyecto — una lista de tarjetas, la más reciente primero. Cada tarjeta muestra una insignia de estado, la insignia de perfil, una insignia de prioridad, la duración, el coste y el comando lanzado. Encima de la lista:
+
+- **Chips de filtro por estado** — muestra solo los jobs en un estado concreto.
+- **Filtro por rango de fechas** — acota a una ventana temporal.
+- **Comparar** — elige dos jobs y velos lado a lado.
+
+Pulsa cualquier tarjeta para abrir la **vista de detalle del job**, donde están el log en streaming en vivo y las métricas en vivo. Eso es la página siguiente: [La vista de detalle del job](the-job-detail-view).
+
+## Cancelar un job
+
+Pulsa **■ Stop** en la cabecera del rail. La app envía `SIGTERM` al subproceso, espera **5 segundos** a que salga limpiamente y luego le aplica `SIGKILL`. No queda nada a medio arrancar.
+
+## Si un rail no se lanza
+
+Si eliges un motor cuya CLI no está instalada en tu máquina, el lanzamiento **falla rápido** en vez de iniciar un job roto — no se arranca nada. Instala la CLI del proveedor que falte ([Usar Codex](../integrations/using-codex), [Usar Gemini](../integrations/using-gemini)) y vuelve a lanzar. Si falta Claude o Codex, verás un mensaje preciso de "*<provider> CLI not found*"; si falta Gemini, hoy aparece un error de lanzamiento genérico, pero el resultado es el mismo.
+
+## Detenerlo todo
+
+Si algo parece ir mal:
+
+- **Un rail** — pulsa **■ Stop** en su cabecera.
+- **Pausa automática por presupuesto** — fija un presupuesto diario y la cola se pausará sola cuando el gasto de ese día llegue al tope.
+- **Todo** — cierra la app de escritorio o ejecuta `specrails-desktop stop`.
+
+## A dónde ir después
+
+- [La vista de detalle del job](the-job-detail-view) — fases, métricas en vivo, tarjetas de ticket.
+- [Batch implement y multifuncionalidad](batch-implement-and-multi-feature) — ejecuta varias specs a la vez.
+- [Elegir un motor por rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.

package/docs/guide/es/pipeline/2-the-job-detail-view.md

@@ -0,0 +1,90 @@
+# La vista de detalle del job
+
+Pulsa cualquier tarjeta de job en la página **Jobs** y aterrizas aquí: la cabina de mando de una ejecución de rail concreta. Está construida en torno a una promesa — **los números en vivo que ves son reales, nunca estimaciones.** En esta página recorremos las fases, las métricas en vivo y las tarjetas de ticket.
+
+## La distribución
+
+Dos paneles se sitúan encima del log completo en streaming:
+
+```
+┌─────────────────────────────────────────────┐
+│  Cabecera de estado  (icono · duración en vivo · …)  │
+├─────────────────────────────────────────────┤
+│  Cabecera de tickets  ( #12  #14  #15 )     │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Log en streaming  (auto-scroll · búsqueda · …)  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Fases del pipeline
+
+Para los jobs `Implement` y `Batch`, la ejecución avanza por las fases que define el slash command — por defecto:
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+Cada fase es un agente especializado que el motor del rail invoca en el directorio de tu proyecto:
+
+| Fase | Agente | Qué hace |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | Planifica la implementación. |
+| **Developer** | `sr-developer` | Escribe el código. |
+| **Reviewer** | `sr-reviewer` | Revisa el resultado. |
+| **Ship** | (varía) | Cierre final: tests, commit, borrador de PR. |
+
+Qué agente se encarga de cada fase lo decide el **perfil de agentes** del proyecto. El trío base (`sr-architect`, `sr-developer`, `sr-reviewer`) está siempre presente; las reglas de enrutamiento de un perfil pueden añadir agentes o cambiar cuál ejecuta una fase. La barra de progreso de fases solo aparece cuando el comando define realmente fases — los jobs de Ultracode (que se saltan el pipeline) no mostrarán ninguna.
+
+## Métricas en vivo — honestas por diseño
+
+La cabecera de estado es el titular. Muestra un icono de estado, una línea de actividad que describe qué está haciendo el job *ahora mismo*, un recuento de pasos dados y una fila de métricas:
+
+| Métrica | Cuándo ves el valor real |
+|--------|------------------------------|
+| **Duración** | **En vivo.** Un contador de 1 segundo va sumando mientras el job se ejecuta — este es el único número genuinamente en vivo. |
+| **Turnos** | Se deriva de forma incremental a partir de los eventos de assistant en streaming según van llegando. |
+| **Tokens** | Se agrega de forma incremental desde el mismo stream (tolerante con eventos a los que les faltan los campos de uso). |
+| **Coste** | Se muestra como `—` hasta que el job termina, y entonces se revela como el `total_cost_usd` autoritativo. |
+
+El principio de diseño: **ningún número aproximado o estimado a media ejecución.** La duración es real porque es simplemente un reloj. Los turnos y los tokens se acumulan a partir de actividad real en streaming. El coste, deliberadamente, *no* se estima mientras se ejecuta — se muestra como pendiente y solo se resuelve a su cifra final y autoritativa cuando el proveedor la reporta al terminar el job. Si un número parece estar esperando, es intencionado — te estamos mostrando la verdad, no una proyección.
+
+La etiqueta y el icono de la cabecera se corresponden con el estado del job, y el panel se renderiza igual para los jobs `running`, `completed` y `failed` — así, la vista de detalle de un job terminado muestra las mismas métricas congeladas en sus valores finales.
+
+## Las tarjetas de ticket
+
+La **cabecera de tickets** se sitúa entre la cabecera de estado y el log. Es una tarjeta de identidad premium que muestra un chip por cada spec que tocó el job — extraídos del comando lanzado, así que reflejan exactamente qué tickets abarcó esta ejecución.
+
+- **2–3 tickets** — se muestran como una lista de chips.
+- **4 o más** — se colapsan en un modo compacto `+ N más` con un chevron para expandir, así la cabecera se mantiene ordenada.
+
+Pulsar un chip abre el detalle de esa spec **sobre la página del job** — no pierdes tu sitio ni cambias de ruta. Es una forma rápida de releer qué se supone que tiene que entregar un job mientras lo ves trabajar. (En pantallas de ancho de tablet incluso puedes arrastrar a un lado un modal de ticket para comparar dos specs lado a lado.)
+
+## El log en streaming
+
+Bajo los paneles está el log completo de la ejecución, transmitido en tiempo real por el WebSocket:
+
+- **Auto-scroll** mantiene a la vista la salida más reciente (sube el scroll y se pausa para que puedas leer).
+- **Búsqueda** para saltar a una frase.
+- **Copiar** para llevarte el log entero.
+
+Esta es la verdad en bruto de lo que está haciendo la IA — cada llamada a una herramienta, cada edición de archivo, cada ejecución de tests.
+
+## Exportar diagnóstico
+
+Si la [telemetría](../settings/customizing) estaba activada para el job, aparece un botón **Exportar diagnóstico** en la cabecera. Descarga un ZIP que contiene:
+
+- `job-metadata.json` — comando, estado, perfil, plugins.
+- `telemetry.ndjson` — señales OTLP/JSON sin comprimir.
+- `logs.txt` — el log completo en streaming.
+- `summary.md` — lo más destacado en formato legible.
+- `profile.json`, `plugins.json` — instantáneas exactas de lo que se ejecutó (cuando existen).
+
+Práctico para compartir una ejecución con un compañero o para abrir un informe de bug preciso.
+
+## A dónde ir después
+
+- [Rails y jobs](rails-and-jobs) — lanzamiento y encolado.
+- [Batch implement y multifuncionalidad](batch-implement-and-multi-feature) — muchas specs, oleadas por dependencias.
+- [Seguimiento de costes](../analytics/tracking-cost) — convierte los costes por job en analíticas de proyecto.

package/docs/guide/es/pipeline/3-batch-implement-and-multi-feature.md

@@ -0,0 +1,78 @@
+# Batch implement y multifuncionalidad
+
+Una spec a la vez está bien, pero buena parte del trabajo real viene en racimos — una funcionalidad más sus tests más su migración, o un backlog que quieres dejar limpio de una sentada. Esta página cubre cómo ejecutar varias specs juntas: el modo Batch, las oleadas por dependencias y cómo el pipeline evita que el trabajo concurrente se pise.
+
+## Ejecutar varias specs a la vez
+
+La forma más sencilla de ejecutar un montón de specs desde un mismo rail es el modo **Batch**:
+
+1. **Arrastra todas las specs** que quieras a un único rail. Se apilan en la lista de specs de ese rail.
+2. **Cambia el modo del rail a Batch** (el control segmentado de la cabecera del rail).
+3. **Pulsa ▶ Play.**
+
+El rail lanza **un** job `/specrails:batch-implement` que recorre todas las specs asignadas. Monitorízalo como cualquier otro job en la página Jobs — es un único job que cubre el conjunto entero, no un job por spec.
+
+Esto importa por la **cola de un job por proyecto**. Como un proyecto solo ejecuta un job de rail a la vez, el modo Batch es también la forma más limpia de *encadenar* una lista de specs sin tener que hacer malabares con varios rails y esperar a que cada uno se vacíe.
+
+### Implement vs Batch — ¿qué modo?
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| Comando | `/specrails:implement` | `/specrails:batch-implement` |
+| Specs por job | Todas las del rail, tratadas como una sola unidad de trabajo | Todas las del rail, trabajadas **secuencialmente** |
+| Mejor para | Un cambio fuertemente acoplado | Varias funcionalidades distintas que quieres despachar en orden |
+| Ordenación | n/a | Oleadas según dependencias (mira más abajo) |
+
+Si las specs son de verdad un único cambio, usa **Implement**. Si son una lista de funcionalidades independientes, usa **Batch** y deja que las secuencie.
+
+## Oleadas por dependencias
+
+El modo Batch no se limita a ejecutar las specs de arriba a abajo — calcula un **orden de ejecución según dependencias** y agrupa las specs en *oleadas*. El orquestador (`/specrails:batch-implement`) averigua qué specs dependen de cuáles y luego las planifica de modo que nada se ejecute antes que el trabajo sobre el que se construye.
+
+Conceptualmente:
+
+```
+Oleada 1:  #2 (modelo de datos)     ← sin dependencias, se ejecuta primero
+Oleada 2:  #4 (API sobre el modelo) ← espera a #2
+           #5 (CLI sobre el modelo) ← espera a #2
+Oleada 3:  #7 (docs de todo)        ← espera a #4 y #5
+```
+
+Dentro del job, las specs de cada oleada se implementan antes de que empiece la siguiente. Esto no lo configuras a mano — el orquestador deriva las oleadas de las propias specs. Velo desplegarse en la [vista de detalle del job](the-job-detail-view): el log en streaming va narrando en qué spec está el batch, y la cabecera de tickets muestra todas las specs que tocó el job.
+
+## Aislamiento por worktree
+
+Cuando se implementan varias specs en una misma ejecución, el pipeline mantiene cada unidad de trabajo aislada para que los cambios concurrentes o secuenciales no se pisen los archivos. El orquestador de batch ejecuta la implementación de cada spec en su propio contexto de trabajo limpio y después integra los resultados — así una spec a medias nunca deja tu árbol en un estado intermedio roto que la siguiente pudiera ver.
+
+En la práctica esto significa:
+
+- Cada spec recibe un lienzo en blanco contra el que implementar, en vez de heredar a mitad de camino las ediciones en vuelo de la spec anterior.
+- Las revisiones y los pasos de ship operan sobre una instantánea coherente, no sobre un objetivo en movimiento.
+- Un fallo en una oleada queda contenido — no corrompe en silencio las specs que ya se entregaron.
+
+La app registra, por cada job, exactamente qué archivos se tocaron y qué ticket los tocó (lo verás aflorar como chips de procedencia en la sección **Code** y como una lista de "Archivos tocados por este ticket" en el modal de detalle de cada spec). Esa atribución es lo que te permite confiar en una ejecución multi-spec: siempre puedes rastrear un cambio de archivo hasta la spec que lo causó.
+
+## Multifuncionalidad entre proyectos
+
+Si quieres paralelismo de verdad — dos funcionalidades grandes construyéndose al mismo tiempo — repártelas **entre proyectos**, no entre rails de un mismo proyecto. Cada proyecto tiene su propia cola independiente, así que:
+
+```
+Proyecto A   ▶ Rail ejecutando la funcionalidad X   ┐
+                                                    ├─ se ejecutan a la vez
+Proyecto B   ▶ Rail ejecutando la funcionalidad Y   ┘
+```
+
+No hay límite global de concurrencia ni contención entre proyectos. Abre los dos, lanza un rail en cada uno y avanzarán juntos. El único freno compartido es tu tope de presupuesto, que pausa las colas por proyecto o de toda la app en cuanto el gasto del día llega al límite.
+
+## Consejos para batches grandes
+
+- **Agrupa specs relacionadas en un mismo rail** antes de pasar a Batch — las oleadas por dependencias solo ven lo que hay en ese rail.
+- **Fija un presupuesto diario** antes de un batch grande para que una ejecución inesperadamente cara se pause sola en vez de desbocarse. Configúralo en [Presupuesto](../settings/customizing).
+- **Usa el botón Comparar** en la página Jobs después para enfrentar dos ejecuciones de batch lado a lado.
+- **Exporta un diagnóstico** (si la telemetría estaba activada) para obtener la instantánea exacta de perfil + plugins de todo el batch.
+
+## A dónde ir después
+
+- [Rails y jobs](rails-and-jobs) — el modelo de cola en profundidad.
+- [La vista de detalle del job](the-job-detail-view) — mira un batch ejecutarse en vivo.
+- [Elegir un motor por rail](picking-an-engine-per-rail) — ten en cuenta que Batch corre en cualquier proveedor; Ultra es solo de Claude.

package/docs/guide/es/pipeline/4-picking-an-engine-per-rail.md

@@ -0,0 +1,60 @@
+# Elegir un motor por rail
+
+Specrails desktop trata **Claude Code**, **Codex CLI** y **Gemini CLI** como motores de primera clase. Un proyecto puede tener uno, dos o los tres instalados — y cuando hay más de uno, eliges qué motor ejecuta cada rail. Esta página cubre el selector de motor por rail y cuándo recurrir a cada uno.
+
+## Cuándo aparece el selector
+
+El **selector de motor** vive en la cabecera del rail, justo al lado del control de modo. Solo se muestra cuando el proyecto tiene **más de un** proveedor instalado.
+
+> **Los proyectos de un solo proveedor se comportan de forma byte-idéntica.** Si un proyecto tiene un único motor, no se muestra ningún selector y nada cambia respecto a la selección de proveedor — sencillamente se ejecuta en ese motor. El selector es exclusivo para proyectos multiproveedor.
+
+Cuando sí aparece, tu elección es **por rail y por lanzamiento** — distintos rails pueden ejecutar distintos motores, y tu elección se recuerda por proyecto (con el motor principal del proyecto como valor por defecto).
+
+## Cómo elegir un motor
+
+1. Asegúrate de que el selector de motor del rail está visible (el proyecto tiene 2 o más proveedores).
+2. Púlsalo y elige **Claude**, **Codex** o **Gemini**.
+3. Lanza el rail con **▶ Play**.
+
+El motor seleccionado ejecuta cada fase del pipeline de ese rail. Si la CLI del motor elegido no está instalada, el lanzamiento falla rápido — no se arranca nada. Instala la CLI que falta y vuelve a intentarlo.
+
+## En qué destaca cada motor
+
+Los tres ejecutan los pipelines estándar **Implement** y **Batch**. Aquí tienes una guía práctica para elegir:
+
+| Motor | Recurre a él cuando… | Notas |
+|--------|--------------------|-------|
+| **Claude** | Quieres el conjunto completo de funciones: perfiles de agentes, Ultracode, reporte de coste nativo, el soporte de herramientas más rico. El predeterminado para la mayoría del trabajo. | El único motor que admite **perfiles de agentes**, **Ultracode** y algunas funciones de spec exclusivas de Claude (Contract Layer, SMASH). |
+| **Codex** | Prefieres la CLI de OpenAI Codex o quieres comparar implementaciones entre proveedores. | `codex` ≥ 0.128.0. Sin reporte de coste nativo — la app rellena el coste desde su tarifario. Los perfiles no aplican. |
+| **Gemini** | Quieres la CLI de Gemini de Google, telemetría nativa o una ejecución más barata para specs rutinarias. | `gemini` ≥ 0.11.0 (define `GEMINI_API_KEY`). Telemetría OTLP nativa. Los perfiles no aplican. |
+
+### Las funciones exclusivas de Claude
+
+Algunas cosas solo funcionan en rails de Claude — elige Claude si las necesitas:
+
+- **Perfiles de agentes** — enrutamiento de modelo por agente. En rails de Codex o Gemini la ejecución siempre usa el modo legacy y cualquier perfil seleccionado se **ignora**. El selector de perfil se oculta para los motores que no son Claude.
+- **Ultracode (modo `Ultra`)** — el modo autónomo que se salta el pipeline. El segmento `Ultra` y su selector de modelo Haiku/Sonnet/Opus solo aparecen cuando el motor del rail es Claude.
+- **Contract Layer y SMASH** — funciones de refinamiento de spec exclusivas de Claude (son opciones de Add-Spec, no de rail, pero aplica la misma restricción).
+
+Si un proyecto mezcla motores, la barra lateral derecha solo muestra las secciones que **todos** los proveedores instalados admiten — así, la sección **Agents** desaparece por completo en un proyecto que incluya cualquier proveedor que no sea Claude, porque los perfiles son específicos de Claude.
+
+## Un flujo de trabajo práctico
+
+Los proyectos multiproveedor brillan cuando quieres **comparar** o **afinar costes**:
+
+- **Comparar implementaciones.** Pon la misma spec en dos rails, configura uno con Claude y otro con Codex, lánzalos los dos (entre proyectos, o uno tras otro en la cola del mismo proyecto) y luego usa el botón **Comparar** en la página Jobs para enfrentar los resultados.
+- **Afinar costes por spec.** Ejecuta las specs de alto riesgo en Claude con un perfil `max`; ejecuta las specs rutinarias de limpieza en Gemini para ahorrar gasto. Filtra `/analytics` por motor para ver el desglose.
+- **Pon un valor por defecto con cabeza.** Configura el motor que más usas como principal del proyecto para que los rails lo adopten por defecto, y cambia por rail solo cuando una spec concreta quiera uno distinto.
+
+## Cosas a tener en cuenta
+
+- **La selección de proveedor es inmutable tras crear el proyecto** (v1). Eliges los proveedores instalados al añadir el proyecto; no hay un interruptor en Ajustes para añadir o quitar uno después.
+- **El coste siempre se registra**, incluso para los motores sin reporte de coste nativo — la app recurre a un tarifario para que las ejecuciones de Codex y Gemini también aparezcan en [analíticas](../analytics/tracking-cost).
+- **El botón "Abrir CLI de IA" del terminal** también ofrece un selector de proveedor en proyectos multiproveedor, por si prefieres manejar una CLI a mano.
+
+## A dónde ir después
+
+- [Usar Codex](../integrations/using-codex) — instalar e iniciar sesión.
+- [Usar Gemini](../integrations/using-gemini) — instalar, `GEMINI_API_KEY`, telemetría.
+- [Rails y jobs](rails-and-jobs) — la cola y el flujo de lanzamiento.
+- [Seguimiento de costes](../analytics/tracking-cost) — desglose de coste por motor.

package/docs/guide/es/settings/1-themes.md

@@ -0,0 +1,37 @@
+# Temas
+
+Haz que Specrails luzca justo como a ti te gusta. La app trae cinco temas cuidados a mano que puedes alternar al instante: sin reiniciar, sin reconstruir nada, sin configuración de por medio.
+
+## Los cinco temas integrados
+
+| Tema | Sensación |
+| --- | --- |
+| **Specrails** | El de serie. Equilibrado, sereno y fiel a la marca. |
+| **Dracula** | El clásico oscuro en tonos púrpura. Cómodo para la vista de noche. |
+| **Aurora Light** | Un tema claro, luminoso y aireado para trabajar de día. |
+| **Obsidian Dark** | Modo oscuro profundo y de alto contraste. |
+| **Matrix** | Verde sobre negro, para cuando quieres sentir que estás dentro del mainframe. |
+
+## Cómo cambiarlo
+
+1. Abre **Ajustes** (el modal de ajustes de toda la app).
+2. Ve a la sección **Apariencia**.
+3. Elige un tema. Se aplica de inmediato en toda la app.
+
+Eso es todo. El cambio surte efecto en el momento en que haces clic: la interfaz se reviste en vivo.
+
+## Dónde se aplica
+
+Tu elección de tema es **para toda la app**, no por proyecto. Cada proyecto, cada página y cada panel siguen el mismo tema. Y también llega a sitios que quizá no esperarías:
+
+- **El panel de terminal** se recolorea en vivo, manteniendo intacto tu historial de desplazamiento y cualquier sesión de shell en marcha.
+- **Las gráficas** de la página de Analytics se retiñen para combinar.
+- **El resaltado de sintaxis del código** en el visor de Código también sigue el tema.
+
+## Recuerda tu elección
+
+Tu selección se guarda junto con la app, así que se mantiene entre reinicios. Para evitar ese breve destello de colores equivocados cuando la app arranca, Specrails aplica el tema que tenías guardado antes incluso de que la interfaz termine de cargar, de modo que lo que ves es correcto desde el primerísimo fotograma.
+
+## Una nota para los curiosos
+
+Los temas se construyen sobre un pequeño conjunto de roles de color semánticos (un color de "acento", un color de "superficie", etc.) en lugar de tonos fijos. Por eso añadir el siguiente tema es fácil y por eso cada tema se mantiene coherente por dentro: cada uno simplemente reasigna esos roles. No necesitas pensar en nada de esto para usarlo; es, sencillamente, el motivo de que personalizar el aspecto resulte tan natural.

package/docs/guide/es/settings/2-language.md

@@ -0,0 +1,39 @@
+# Idioma
+
+Specrails habla tu idioma. La interfaz está completamente traducida a ocho idiomas y, por defecto, sigue el idioma que tengas configurado en tu ordenador, así que para la mayoría de la gente aparece en el idioma correcto desde el primer arranque.
+
+## Idiomas disponibles
+
+- English
+- Español (Spanish)
+- Français (French)
+- Deutsch (German)
+- Português (Portuguese)
+- Italiano (Italian)
+- 中文 (Chinese)
+- 日本語 (Japanese)
+
+## Arranca en el idioma de tu sistema operativo
+
+La primera vez que abres Specrails, mira las preferencias de idioma de tu sistema operativo y las hace coincidir con el idioma compatible más parecido. Si tu Mac o tu PC está en español, lo verás en español. Y si está en una variante regional (como `es-ES` o `zh-Hans-CN`), Specrails la asigna automáticamente al idioma base correcto.
+
+No tienes que hacer nada y, mientras no toques el ajuste de idioma, Specrails seguirá fielmente al de tu sistema. Cambia más adelante el idioma de tu ordenador y Specrails te acompañará.
+
+## Elegir un idioma tú mismo
+
+¿Quieres algo distinto al idioma por defecto de tu sistema? Selecciónalo de forma explícita:
+
+1. Abre **Ajustes**.
+2. Ve a la sección **Idioma**.
+3. Elige tu idioma.
+
+El cambio es **instantáneo**: toda la interfaz se vuelve a renderizar en el nuevo idioma sin reiniciar. Una vez que haces una elección explícita, Specrails la recuerda y deja de seguir al sistema, de modo que tu elección se respeta cada vez que abres la app.
+
+## Qué se traduce
+
+Todo lo que lees en la interfaz: botones, etiquetas, mensajes de estado, títulos de página, diálogos. Las fechas también se adaptan al idioma que elijas, así que se formatean tal y como ese idioma espera.
+
+## Bueno saberlo
+
+- **El inglés es el idioma de origen.** Si una función recién estrenada llega antes de que su traducción esté lista, puede que veas alguna etiqueta en inglés por aquí o por allá; se traducirá en una actualización posterior.
+- Tu elección de idioma es **para toda la app**, la misma en todos tus proyectos.

package/docs/guide/es/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -0,0 +1,46 @@
+# Telemetría del pipeline y diagnósticos
+
+Cuando un job del pipeline no sale como esperabas, la telemetría te ofrece un registro detallado, entre bambalinas, de lo que el CLI de IA hizo en realidad. Está **desactivada por defecto** y es totalmente opcional, por proyecto: actívala solo cuando la quieras.
+
+## Qué es
+
+La telemetría captura señales de diagnóstico estructuradas (trazas, métricas y logs) que el CLI de IA emite mientras ejecuta un job del pipeline. Piénsalo como la caja negra de tus ejecuciones del pipeline: tiempos, uso de tokens y actividad paso a paso, capturados en local para que puedas inspeccionar un job después de los hechos.
+
+Está construida sobre **OpenTelemetry**, un formato abierto y estándar, así que los datos no quedan encerrados en una caja propietaria.
+
+## Cómo activarla
+
+La telemetría se configura **por proyecto**:
+
+1. Abre la página de **Ajustes** del proyecto (la ruta de ajustes específica del proyecto).
+2. Localiza el interruptor de **Telemetría del pipeline**.
+3. Actívalo.
+
+A partir de ese momento, los jobs del pipeline de ese proyecto registran telemetría. Los demás proyectos no se ven afectados: cada proyecto decide por sí mismo.
+
+### Qué se cubre
+
+La telemetría se aplica a los **jobs del pipeline** (las ejecuciones de rail en cola Architect → Developer → Reviewer → Ship). Las sesiones interactivas, como el chat y el asistente de configuración, se dejan fuera a propósito: la telemetría está pensada para las ejecuciones del pipeline, repetibles e inspeccionables, no para conversaciones puntuales.
+
+## Dónde viven los datos
+
+Todo se queda en tu máquina, dentro de tu directorio personal (`~/.specrails/`), nunca en tu repo. Las grabaciones en bruto se guardan comprimidas junto a su job, y las más antiguas se condensan automáticamente en resúmenes compactos al cabo de una semana para mantenerlo todo ordenado. No tienes que gestionar nada de esto a mano.
+
+## Exportar un paquete de diagnóstico
+
+Lo más útil que la telemetría desbloquea es la **exportación de diagnóstico**: un único ZIP que empaqueta todo lo relativo a un job para resolver problemas o compartirlo.
+
+Cuando un job tiene telemetría registrada, aparece un **botón de exportación** en su tarjeta de job. Pulsa para descargar un ZIP que contiene:
+
+- **`job-metadata.json`** — la identidad y los parámetros del job
+- **`telemetry.ndjson`** — las señales registradas en bruto
+- **`logs.txt`** — la salida de log capturada
+- **`summary.md`** — un resumen legible de la ejecución
+
+Si el proyecto usa plugins, el paquete también incluye una instantánea de qué plugins estuvieron activos en ese job.
+
+Este es el paquete que conviene tener a mano cuando quieres entender una ejecución espinosa, dejar constancia o pasarle los detalles a alguien que te esté ayudando a depurar.
+
+## Cómo desactivarla
+
+Vuelve a apagar el interruptor cuando quieras. Los nuevos jobs dejan de registrar de inmediato. Lo que ya se capturó se mantiene en disco hasta que se compacta o eliminas el proyecto: nada se envía a ninguna parte ni se pierde a tus espaldas.

package/docs/guide/es/settings/4-where-your-data-lives.md

@@ -0,0 +1,48 @@
+# Dónde viven tus datos
+
+La versión corta: **Specrails mantiene tus repositorios impecables.** Cuando apuntas la app a uno de tus proyectos, no se instala dentro, no esparce archivos de configuración por todas partes ni reescribe nada que no le hayas pedido. Tu código sigue siendo tuyo, y limpio.
+
+## Tu repo se mantiene limpio
+
+Los archivos propios de Specrails —sus bases de datos, el estado por proyecto, las definiciones de agentes, los ajustes, la telemetría, los resúmenes y todo lo demás que necesita para funcionar— viven en un único hogar bien ordenado, dentro de tu directorio personal:
+
+```
+~/.specrails/
+```
+
+Esa carpeta es el espacio de trabajo privado de la app. Es donde residen el registro de proyectos, las bases de datos por proyecto, las herramientas empaquetadas y todas las piezas operativas. Tus repositorios de código reales nunca se usan como vertedero para nada de esto.
+
+Esto significa que:
+
+- El `.gitignore` de tu repo **no** lo reescribe la app.
+- Tu repo no se llena de configuración de herramientas ni de directorios de estado ocultos.
+- Eliminar un proyecto de Specrails no deja ningún desorden detrás en tu código.
+
+Si has usado antes herramientas que añadían carpetas y archivos sin avisar por todo tu proyecto, esto es un cambio deliberado de rumbo. Specrails está hecho para que apuntarlo a un repo sea un **no-evento** para el historial de git de ese repo.
+
+## Lo único que *sí* se commitea, por diseño
+
+Hay exactamente una excepción intencionada, y es la razón de ser de la herramienta: **tus specs de OpenSpec.**
+
+Las specs viven en tu repositorio, dentro de:
+
+```
+openspec/
+```
+
+Esto es a propósito. Tus specs son un **entregable**: un registro versionado y revisable de qué decidiste construir y por qué. Su sitio está junto a tu código, bajo seguimiento en git, visibles en los pull requests, compartidas con tu equipo. Ese es el valor: las specs no son estado desechable de borrador, son parte de la historia de tu proyecto.
+
+Así que la regla es simple y honesta:
+
+- **`openspec/`** → vive en tu repo, commiteado, por diseño.
+- **Todo lo demás que Specrails necesita** → vive en `~/.specrails/`, fuera de tu camino.
+
+## Por qué funciona así
+
+Specrails ejecuta las herramientas de IA desde su propio espacio de trabajo privado (en `~/.specrails/`) y solo se asoma a tu repositorio real para lo que de verdad necesita tocarlo: leer tu código y escribir las specs que pediste. Las herramientas, las definiciones del framework y la contabilidad interna se quedan todas en la carpeta hogar de la app.
+
+Lo que ganas tú: puedes añadir un proyecto, ejecutar pipelines, explorar specs y probar cosas con la confianza de que el árbol de trabajo y el historial de git de tu repositorio solo cambian de las maneras que esperarías: tus specs commiteadas y el código que escriben tus pipelines. Nada más se cuela.
+
+## Eliminar un proyecto
+
+Cuando eliminas un proyecto de Specrails, la app limpia su propio estado por proyecto en `~/.specrails/`. Las specs que ya estaban commiteadas en tu repo se quedan donde les corresponde —en tu repo— porque son tuyas.

package/docs/guide/es/specs/1-specs-and-the-backlog.md

@@ -0,0 +1,52 @@
+# Specs y el backlog
+
+Una **spec** es la unidad de trabajo que implementa el pipeline de IA. Piénsala como un ticket: un título, una descripción de lo que quieres conseguir, una prioridad y, opcionalmente, etiquetas. Cuando lanzas el pipeline, los agentes de IA leen la spec y actúan en consecuencia, así que una spec clara es la pieza más importante para obtener un buen resultado.
+
+A veces a las specs se las llama **tickets** en la app: las dos palabras significan lo mismo.
+
+## El tablero
+
+Cada proyecto se abre en su **Dashboard**, que muestra el **SpecsBoard**: la lista de todas las specs del proyecto. Este es tu backlog. Desde aquí creas specs nuevas, defines su prioridad, las arrastras a un rail para implementarlas y ves cómo cambia su estado a medida que avanza el trabajo.
+
+El tablero tiene dos modos de vista, que se cambian con un botón de la barra de herramientas y se recuerdan por proyecto:
+
+- **Vista post-it** (la predeterminada): tarjetas con resúmenes breves.
+- **Vista de lista**: filas compactas de una sola línea.
+
+También puedes filtrar por **estado** (Todos / Por hacer / Hechos) y por **etiqueta**, y ordenar por **Por defecto**, **Ticket #** o **Prioridad** (cada uno con un interruptor ascendente/descendente).
+
+## Estados
+
+Una spec recorre un pequeño conjunto de estados. El tablero le da a cada uno una señal visual coherente para que puedas leer el estado de tu backlog de un vistazo:
+
+| Estado | Qué significa |
+|--------|---------------|
+| **Borrador** | Una idea en curso guardada desde una conversación de Explore. Todavía no está lista para implementar; puedes volver y seguir dándole forma. Muestra una píldora `Draft`. |
+| **Por hacer** | Lista para retomarse. Aquí es donde aterriza una spec terminada cuando la creas. |
+| **En curso** | El pipeline está trabajando en ella ahora mismo (un punto azul pulsante). |
+| **Hecho** | Completada por el pipeline (una marca de verificación verde). |
+| **Cancelado** | Abandonada (una X roja). |
+
+Los borradores viven en el mismo grupo activo que las specs Por hacer (no hay una columna separada para ellos), pero llevan un borde con un tinte sutil y una píldora `Draft` para que se distingan fácilmente. Consulta [Borradores y la Contract Layer](drafts-and-contract-layer.md) para conocer todos los detalles sobre los borradores.
+
+## Prioridades
+
+Toda spec que no sea un borrador tiene una prioridad: **Crítica**, **Alta**, **Media** o **Baja**. La prioridad es puramente una herramienta de organización: te ayuda a decidir qué implementar a continuación y te permite ordenar el tablero. La defines al crear una spec y puedes cambiarla en cualquier momento haciendo clic derecho en la tarjeta de la spec y eligiendo **Set priority**.
+
+Los borradores son la única excepción: un borrador puede *no* tener ninguna prioridad, porque todavía es una idea en curso. La prioridad queda fijada cuando confirmas el borrador como una spec real.
+
+## Crear una spec
+
+Para crear una spec, haz clic en **Añadir** (el botón Más de la barra de herramientas del SpecsBoard). Se abre el diálogo **Añadir spec** con varias formas de trabajar:
+
+- **Modo Quick**: describes lo que quieres y la IA escribe la spec completa de una sola vez. Consulta [Añadir spec — Modo Quick](add-spec-quick-mode.md).
+- **Modo Explore**: conversas con la IA y esta te ayuda a dar forma a la spec turno a turno. Consulta [Añadir spec — Modo Explore](add-spec-explore-mode.md).
+- **Modo Raw**: lo que escribas se guarda tal cual como una spec, sin intervención de la IA. Úsalo cuando ya tengas el texto de la spec escrito.
+
+A cuál recurrir depende de lo clara que tengas ya la idea. ¿Sabes exactamente lo que quieres? Quick. ¿Todavía le estás dando vueltas? Explore. ¿Ya tienes el texto? Raw.
+
+## Adónde ir después
+
+- [Añadir spec — Modo Quick](add-spec-quick-mode.md): la forma más rápida de convertir una idea en una spec.
+- [Añadir spec — Modo Explore](add-spec-explore-mode.md): da forma a una spec conversando.
+- [Borradores y la Contract Layer](drafts-and-contract-layer.md): guarda el trabajo en curso y enriquece las specs para el pipeline.