specrails-desktop 2.6.0 → 2.7.0

package/docs/gemini-cli-provider-study.md

@@ -0,0 +1,301 @@
+# Estudio de implementación — Gemini CLI como tercer proveedor de specrails-desktop
+
+> Documento de planificación (no contrato final). Generado 2026-06-16 mediante auditoría multi-agente del código real + investigación de fuentes primarias de `github.com/google-gemini/gemini-cli` (HEAD `5624a3b`, v0.48.0-nightly). Listón de referencia: el adapter de Codex (no-nativo con puentes). Las citas `file:line` provienen de la auditoría del código; las flags/campos de Gemini en `verbatim` de la investigación. Lo marcado `[UNCERTAIN]` se señala con su plan de resolución.
+
+---
+
+## 1. Resumen ejecutivo y alcance
+
+**Veredicto: viable y de bajo riesgo arquitectónico.** El core de spawn/detect/cost/registry ya está generalizado por id de proveedor (`server/providers/registry.ts` es un `Map<ProviderId,adapter>`, `core-compat.ts` recorre `listAdapters()`, `pricing.ts` usa claves `'<id>:<model>'`, `result-event.ts` `finaliseInvocationResult` y `provider-selection.ts` son membership-based). El contrato promete *"un fichero + una entrada de registro"* y eso se cumple para el camino de compilación mínimo. El resto del trabajo es **ensanchar uniones literales `'claude'|'codex'`** y **rellenar branches `=== 'codex'` que no tienen hermano gemini**.
+
+Gemini supera a Codex en dos capacidades clave verificadas:
+- **OTEL nativo** (`[confirmed]`): emite OTLP por env (`GEMINI_TELEMETRY_*`), igual que claude → `nativeOtelEnv: true`, **no necesita bridge sintético**.
+- **System-prompt nativo** (`[confirmed]`): `GEMINI_SYSTEM_MD=<path>` reemplaza el system prompt por env de proceso → soporte de system-prompt (con matiz, ver §3).
+
+**Entra en v1 (PR-B beta-gated):** jobs/rails básicos, Explore Spec multi-turno (spawn-per-turn con `--resume`), Quick spec, Analytics/coste vía rate-card, OTEL nativo, terminal CLI launch, detección + prerequisitos, selección de modelo, multi-provider per project.
+
+**NO entra en v1 (paridad Codex, se ocultan por intersección de capacidades):** Agent Profiles, SMASH, Contract Refine, Ultracode (+interactivo), plugins/Serena, persistent-stdin de Explore. Gemini se comporta byte-idéntico a Codex en estas superficies **siempre que declare las capacidades correctas y se ensanchen los tipos** — cero código nuevo en esas superficies.
+
+**Diferido a follow-up explícito (decisiones tomadas, no implementadas en v1):** generalizar `provider-capabilities.ts` para *otorgar* a Gemini features hoy claude-only; bridge Windows multi-line argv; traducción slash-command para rails funcionales en Gemini (esto último es **bloqueante para rails reales**, ver §6).
+
+---
+
+## 2. Modelos a ofrecer
+
+Decisión: **pinear ids GA concretos, no alias ni ids preview**, porque los ids `gemini-3-*-preview` rotan (la API ya movió Pro a `gemini-3.1-pro-preview`) y el CLI acepta ids inválidos sin validar (`issue #21391`). `ai_invocations.model` y la clave de pricing necesitan un id concreto y estable → el `modelCatalog()` ofrece ids GA concretos como `value`, que son los que se pasan a `--model` y se almacenan; se evita el churn de los preview.
+
+**Catálogo curado (4 entradas):**
+
+| value (`--model` / `ai_invocations.model`) | label | default |
+|---|---|---|
+| `gemini-2.5-pro` | Gemini 2.5 Pro | **sí** |
+| `gemini-2.5-flash` | Gemini 2.5 Flash | no |
+| `gemini-2.5-flash-lite` | Gemini 2.5 Flash Lite | no |
+| `gemini-3.1-pro-preview` | Gemini 3 Pro (preview) | no |
+
+- **Default = `gemini-2.5-pro`**: GA, no-preview, es el `DEFAULT_GEMINI_MODEL` hardcoded del propio CLI, pricing estable. Evita anclar el producto a un id preview que rotará.
+- **Se ofrece `gemini-3.1-pro-preview`** como cuarta opción de calidad (el único Pro de Gemini-3 *con precio publicado*; `gemini-3-pro` no existe como modelo con precio). Etiquetado "preview" para señalar volatilidad.
+- **Se omiten `gemini-3-flash-preview` / `gemini-3.5-flash` / `gemini-3.1-flash-lite`**: preview de precio movible; con `flash`/`flash-lite` 2.5 ya cubrimos el tier rápido/barato con GA estable. Añadirlos luego es trivial (solo filas de pricing + catálogo).
+- **Se omite pasar alias `auto`/`pro`/`flash`**: el routing `auto` impide stampear un id concreto en `ai_invocations.model`, rompiendo la atribución de coste. Pinneamos ids.
+
+`[UNCERTAIN]`: el mapping alias→id-concreto no está byte-documentado; se resuelve NO usando alias.
+
+**Filas para `server/pricing.ts` (clave `'gemini:<model>'`, USD por 1M tokens, Standard paid tier):**
+
+```ts
+// Gemini (Google). Ref: ai.google.dev/gemini-api/docs/pricing (fetched 2026-06-16).
+// nativeCostUsd:false → estas tarifas son la ÚNICA fuente de coste.
+'gemini:gemini-2.5-pro':         { inputPer1M: 1.25, outputPer1M: 10.00, cacheReadPer1M: 0.125, lastReviewedAt: '2026-06-16' },
+'gemini:gemini-2.5-flash':       { inputPer1M: 0.30, outputPer1M: 2.50,  cacheReadPer1M: 0.03,  lastReviewedAt: '2026-06-16' },
+'gemini:gemini-2.5-flash-lite':  { inputPer1M: 0.10, outputPer1M: 0.40,  cacheReadPer1M: 0.01,  lastReviewedAt: '2026-06-16' },
+'gemini:gemini-3.1-pro-preview': { inputPer1M: 2.00, outputPer1M: 12.00, cacheReadPer1M: 0.20,  lastReviewedAt: '2026-06-16' },
+```
+
+Notas de tiering y caché (decisiones explícitas):
+- **`gemini-2.5-pro` y `gemini-3.1-pro-preview` son context-tiered** (>200k tokens duplica precio: pro $2.50/$15.00; 3.1-pro $4.00/$18.00). `PriceEntry` no soporta tiering por tamaño de prompt. **Decisión v1: usar el tier ≤200k** (la mayoría de jobs caen ahí). El coste de prompts >200k se **infra-estima** — aceptable y honesto (Analytics ya marca `estimated=true`). Fidelidad = follow-up que ensancha `PriceEntry` con tiering (toca también codex pro). No bloqueante.
+- **Free tier**: existe (OAuth 60 RPM/1000 RPD; API key free 10 RPM/250 RPD, solo Flash). **No se modela en pricing** — el rate-card es para coste estimado, no para gating de cuota (coherente con codex).
+- **Caché**: `cacheReadPer1M` asume (como OpenAI/codex) que los cached tokens son un *subconjunto* de `tokens_in`. Gemini reporta `cachedContentTokenCount` separado → `[UNCERTAIN]` **resolución**: en `extractResult` mapear `cached` a `tokens_cache_read` y NO restarlo de `tokens_in` (mismo patrón que codex `cached_input_tokens`); el test de pricing fija el contrato.
+
+---
+
+## 3. El adapter `server/providers/gemini-adapter.ts`
+
+Estructura espejo de `codex-adapter.ts`. Constantes `GEMINI_MODELS`, `GEMINI_MIN_VERSION`, helper `fold()` (igual que codex-adapter.ts:49-52), `WHICH_CMD`, `compareSemver`.
+
+### Propiedades readonly
+
+| Miembro | Valor Gemini | Razón |
+|---|---|---|
+| `id` | `'gemini'` | clave de registro; igual a `projects.providers[]` y al param `aiEngine`. |
+| `displayName` | `'Gemini CLI'` | etiqueta UI pura. |
+| `binary` | `'gemini'` | ejecutable en PATH. |
+| `minCliVersion` | `'0.11.0'` | piso donde stream-json (PR #10883) + resume están validados. <0.6 no tiene `--output-format`; <0.11 no tiene stream-json. |
+| `projectDirName` | `'.gemini'` | dir de settings del CLI (`.gemini/settings.json`). |
+| `instructionsFilename` | `'GEMINI.md'` | el CLI lee GEMINI.md por defecto; plugin/explore-cwd escriben aquí. **Mejor que codex**: nativo, sin config extra. |
+| `mcpRegistration` | `'project-json'` | Gemini registra MCP en `.gemini/settings.json` `mcpServers`. `gemini mcp add -s project` escribe al settings.json. |
+
+### `capabilities` (8 campos)
+
+| Campo | Valor | Por qué |
+|---|---|---|
+| `nativeResume` | `true` | `--resume <uuid\|index\|latest>` headless wired en non-interactive (`nonInteractiveCli.ts:236-242`, `resumeChat`). El host pre-asigna UUID con `--session-id` y resume con `--resume <uuid>`. |
+| `nativeStreamJson` | `true` | `--output-format stream-json` emite NDJSON (`init/message/tool_use/tool_result/error/result`). |
+| `nativeCostUsd` | `false` | NO hay campo cost/usd en ningún evento (grep confirmado). → rate-card en pricing.ts (igual codex). |
+| `nativeOtelEnv` | `true` | **MEJOR que codex**: emite OTLP nativo por `GEMINI_TELEMETRY_*` env. No necesita bridge sintético (ver §4). |
+| `profileEnvSupport` | `true` (vestigial) | Igual que codex: rails fuerzan profile=null para non-claude (`rails-router.ts:250`); valor irrelevante funcionalmente; `true` por paridad. |
+| `systemPromptArg` | `false` (v1) | **Matiz**: Gemini SÍ soporta override de system-prompt, pero por **env `GEMINI_SYSTEM_MD=<path>`**, NO por flag de argv. El contrato `systemPromptArg` significa "¿hay un *flag* `--system-prompt`?" → no lo hay. **v1: `false`** y foldear systemPrompt en el prompt (como codex, fold()). El path env es follow-up. |
+| `persistentStdin` | omitido (`false`) | El CLI requiere el follow-up prompt vía `-p`/`--prompt` en resume headless (issue #14180), no soporta stdin stream-json long-lived documentado. → Explore cae al spawn-per-turn legacy (sin pérdida vs default, que es OFF). |
+
+**Nota sobre `systemPromptArg=false` pese a soporte nativo**: el contrato solo modela "flag de argv". Como Gemini usa env (`GEMINI_SYSTEM_MD`), la vía limpia v1 es foldear (codex-parity). Un follow-up puede inyectar `GEMINI_SYSTEM_MD` en el env de spawn — pero eso es un reemplazo *completo* del system prompt (no merge), y los managers asumen append; foldear es más seguro en v1.
+
+### `buildArgs(action, opts)` — switch de los 9 SpawnActions
+
+Flags base: `--output-format stream-json`, `--model <opts.model>`. Headless se dispara con `-p <prompt>`. Jobs autónomos: `--approval-mode yolo`. Acciones read-only de spec/explore: `--approval-mode plan`. `opts.extraArgs` siempre se appendea verbatim.
+
+```
+chat-turn (Explore):     gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json --session-id <hostUUID>
+chat-resume:             gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json --resume <opts.sessionId>
+                         // throw si !opts.sessionId  (igual codex)
+chat-stream:             throw  // persistentStdin no soportado (igual codex)
+rail-job:                gemini -p <command> --model <m> --output-format stream-json --approval-mode yolo --session-id <hostUUID>
+                         // NB: el command slash /specrails:X NO lo entiende Gemini → §6 (bloqueante rails reales)
+spec-gen:                gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json --approval-mode plan
+agent-refine:            gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json --approval-mode yolo
+setup-enrich:            gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json
+setup-enrich-resume:     gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json --resume <opts.sessionId>
+                         // throw si !opts.sessionId
+auto-title:              gemini -p <fold(sys,prompt)> --model <m> --output-format stream-json
+```
+
+Detalles:
+- **`--session-id <hostUUID>` en turno 1** (chat-turn, rail-job): el host mintea un UUID propio y lo pre-asigna, así no depende de parsear `init.session_id` (que es post-2025-12-04). Resume luego con `--resume <eseUUID>`. Robustez de versión.
+- **Resume requiere prompt vía `-p`** (no stdin/positional) — issue #14180, workaround estable documentado.
+- **`opts.maxTurns`**: Gemini lo mapea a `maxSessionTurns` (settings.json, default 100), NO hay flag `--max-turns`. Ignorar `maxTurns` en buildArgs (como codex); el cap sale por exit code 53.
+- **cwd**: todos los spawns desde `project.path` (o explore-cwd) — el resume está scopeado por hash de cwd (`getProjectHash(process.cwd())`). El host ya fija `cwd=project.path` por manager.
+
+### `parseStreamLine(line)` — mapeo evento-gemini → AdapterEvent[]
+
+`JSON.parse` por línea; `null` en línea vacía o parse-fail (igual codex):
+
+| Evento Gemini | AdapterEvent | Mapeo |
+|---|---|---|
+| `init` `{session_id,model}` | `session-started{sessionId: e.session_id}` | **session_id sale del evento `init`** (único sitio). |
+| `message` `{role:'assistant',content,delta}` | `text-delta{text: e.content}` | acumular chunks con `role==='assistant'`. `role:'user'` (echo) → ignorar. |
+| `tool_use` `{tool_name,tool_id,parameters}` | `tool-use{name: e.tool_name, inputPreview: ...slice(0,200)}` | preview 200 chars (igual codex). |
+| `tool_result` `{tool_id,status,output,error}` | `other{type:'tool_result',raw}` | no hay variant dedicado; codex tampoco lo usa. |
+| `result` `{status,stats}` | `result{payload: e}` | terminal; `stats` queda en payload para `extractResult`. |
+| `error` `{severity,message}` | `other{type:'error',raw}` | no-fatal; los fatales van a stderr+exit. |
+| desconocido | `other{type,raw}` | |
+
+**session_id**: del evento `init.session_id`. Como además pre-asignamos `--session-id`, el host ya lo conoce sin parsear (doble seguridad).
+
+### `extractResult(events)` — suma de tokens
+
+Lee el último `result.payload.stats` (StreamStats, flat):
+- `tokens_in ← stats.input_tokens`
+- `tokens_out ← stats.output_tokens` (Gemini stream-json **descarta** `thoughts`/`tool` tokens; no hay reasoning separado que foldear)
+- `tokens_cache_read ← stats.cached`
+- `tokens_cache_create ← undefined`
+- `num_turns ←` contar eventos `result` (1 por turno)
+- `session_id ←` último `session-started.sessionId`
+- `total_cost_usd ← undefined` → `finaliseInvocationResult` (`result-event.ts:48-89`) aplica `estimateCostUsd('gemini', model, usage)` contra `pricing.ts`. Sin filas → coste NULL + warn (`result-event.ts:81`).
+
+### `detectInstalled()` — espejo exacto de codex (contrato cap 3s, types.ts:131-132)
+
+`which/where gemini` → si ausente `{installed:false,executable:false}`. Si presente: `gemini --version` con `timeout:3000`, regex `\d+\.\d+\.\d+`, `compareSemver` vs `GEMINI_MIN_VERSION='0.11.0'` → `meetsMinimum` + string de error/upgrade. Fallo del probe → `{installed:true,executable:false}`. Corre al startup y en `/setup-prerequisites`.
+
+### `baselineAgents()` → `['sr-architect','sr-developer','sr-reviewer']` (vestigial — rails fuerzan profile=null).
+
+### `registration` (`server/providers/index.ts:11-14,17`)
+```ts
+import { geminiAdapter } from './gemini-adapter'
+register(geminiAdapter)
+export { claudeAdapter, codexAdapter, geminiAdapter }
+```
+
+---
+
+## 4. OTEL: nativo (NO bridge)
+
+**Decisión: `nativeOtelEnv: true` — Gemini va por el path de claude (env-injection), NO por el bridge sintético de codex.** Evidencia `[confirmed]`: `packages/core/src/telemetry/config.ts` (PR #9113) lee de `process.env` con precedencia env>settings, emitiendo OTLP nativo de traces+metrics+logs.
+
+**Cómo se inyecta** — en `server/queue-manager.ts`, con `nativeOtelEnv:true` el bloque del bridge (`queue-manager.ts:1197-1205`, gated `!adapter.capabilities.nativeOtelEnv`) **se salta automáticamente**, y Gemini fluye por `buildTelemetryEnv` (`queue-manager.ts:1042,1105`). El adapter/queue inyecta:
+```
+GEMINI_TELEMETRY_ENABLED=true
+GEMINI_TELEMETRY_TARGET=local
+GEMINI_TELEMETRY_OTLP_ENDPOINT=<app OTLP receiver>
+GEMINI_TELEMETRY_OTLP_PROTOCOL=grpc           # grpc:4317, evita el bug OTLP/HTTP #15581
+GEMINI_TELEMETRY_TRACES_ENABLED=true          # spans (off por defecto)
+```
+
+**Qué cambia respecto a claude en queue-manager**: `buildTelemetryEnv` hardcodea `CLAUDE_CODE_ENABLE_TELEMETRY:'1'` (`queue-manager.ts:52-60`), claude-específico. Gemini necesita SU enable-flag. **Cambio requerido (solo si telemetry está ON para un job gemini)**: parametrizar el enable-var por adapter — p.ej. `adapter.nativeOtelEnvVars()` que devuelva `{CLAUDE_CODE_ENABLE_TELEMETRY:'1'}` para claude y el bloque `GEMINI_TELEMETRY_*` para gemini. Los `OTEL_EXPORTER_OTLP_*` estándar siguen neutrales. **No bloqueante** salvo que se active telemetry.
+
+**Caveat de correlación `[UNCERTAIN]`**: el receptor OTLP del app rutea por `specrails.job_id` + `specrails.project_id` en `resource.attributes`. Gemini emite sus propios `session.id`/`installation.id`, NO los de specrails. Si Gemini honra `OTEL_RESOURCE_ATTRIBUTES` (estándar OTEL SDK, **no documentado en telemetry.md**), inyectar `OTEL_RESOURCE_ATTRIBUTES=specrails.job_id=<id>,specrails.project_id=<id>` resuelve la correlación. **Resolución**: probar empíricamente antes de confiar; fallback = correlacionar por `session.id` de spawn-time (lo conocemos vía `--session-id`). Telemetry es opt-in OFF por defecto → no bloquea v1.
+
+**El bridge `codex-otel-bridge.ts` NO se toca** para Gemini (se bypassa por capability).
+
+---
+
+## 5. Change-list exacto por fichero (dos PRs)
+
+### PR-A — Generalización previa (ensanchar tipos, desramificar; sin Gemini todavía)
+
+Mergeable independiente, no cambia comportamiento observable.
+
+| Fichero:línea | Cambio | Bloq |
+|---|---|---|
+| `server/desktop-db.ts:10,50,167,268,388` | `CliProvider = 'claude'\|'codex'` → ensanchar a incluir `'gemini'` (o alias a `ProviderId`/string). Tipo DB central; todos heredan. `DEFAULT 'claude'` se mantiene. | **sí** |
+| `server/spec-models.ts:1-37` | `SpecProvider` union + reemplazar ternario `provider==='codex'?CODEX:CLAUDE` en `getModelsForProvider` por **lookup `Record<provider, SpecModelOption[]>`** (fallback `adapter.defaultModel()`/`[]`). `PROVIDER_DEFAULT_MODEL` → record extensible. | **sí** |
+| `server/desktop-router.ts:158-168` (`GET /available-providers`) | Dejar de destructurar `{claude,codex}` fijo; `detectAvailableCLIs()` ya devuelve `Record<string,boolean>` → **devolver el map entero (spread)**. `if(providers.claude\|\|providers.codex)` → `Object.values(providers).some(Boolean)`. | **sí** |
+| `server/desktop-router.ts:265-266` | casts `as 'claude'\|'codex'` en addProject → ensanchar (registry valida con `hasAdapter`). | **sí** |
+| `server/project-registry.ts:116` | `AddProjectInput.providers?: ('claude'\|'codex')[]` → `ProviderId[]`/`string[]`. | **sí** |
+| `client/src/hooks/useDesktop.tsx:29,35,48,172` | 4 anotaciones `('claude'\|'codex')[]` → `string[]`/`ProviderId`. | **sí** |
+| `client/src/lib/provider-capabilities.ts:11` | `ProviderId = 'claude'\|'codex'` → añadir `'gemini'`/string. | **sí** |
+| `client/src/components/ModelSelector.tsx:20-55,80` | ternario `provider==='claude'?CLAUDE:CODEX` → map por id; `PRESET_DEFAULTS`/`MAX_OVERRIDES` literal → `Record<string,string>`; ensanchar prop union. **Bloqueante funcional**: sin esto Gemini mostraría modelos de Codex. | **sí** |
+| `client/src/components/ChatInput.tsx:7-18,25` | selección por id-keyed map; ensanchar `provider?: 'claude'\|'codex'`. | **sí** |
+| `client/src/components/AddProjectDialog.tsx:28,31,37,41,67-79,96,141,235-236` | `availableProviders` de `{claude;codex}` fijo → `Record<string,boolean>` iterado sobre `/available-providers`; `!claude && !codex` → iterar keys. | **sí** |
+| `client/src/components/{AiEngineSelector:40,53, RailEngineSelector:33,38, CliLaunchMenu:52,55, explore-spec/SpecModelPicker:23,81, SetupWizard:563}` | casts inline `as 'claude'\|'codex'` → ensanchar union. Listas data-driven, Gemini aparece solo. | **sí** |
+| `server/util/cli-prompt.ts:178-191` | `spawnAiCli` ya cae a `spawnCli` genérico para binarios desconocidos → **POSIX funciona sin cambio**. Windows multi-line argv (`transformClaudeArgsForWindows`/`transformCodexArgsForWindows`) NO cubre gemini. | cosmético (POSIX) / bloq Windows |
+
+### PR-B — El adapter Gemini + branches y catálogos
+
+| Fichero:línea | Cambio | Bloq |
+|---|---|---|
+| `server/providers/gemini-adapter.ts` (nuevo) | El adapter completo (§3). | **sí** |
+| `server/providers/index.ts:11-14,17` | import + `register(geminiAdapter)` + re-export. | **sí** |
+| `server/pricing.ts:44-50` | 4 filas `'gemini:<model>'` (§2). Sin ellas coste=NULL. | **sí** |
+| `server/project-router-tickets.ts:1540-1556` (ai-edit) | dispatch hardcoded `if(provider==='codex'){binary='codex'...} else {binary='claude'...}` → **un proyecto gemini spawnearía 'claude' (binario equivocado)**. Reemplazar por `adapter.binary` + `adapter.buildArgs` (patrón ya usado en quick-spec línea 341). | **sí** |
+| `server/project-router-tickets.ts:420,610,1022,1148` | bloques `if(provider==='codex')` sin hermano gemini → generalizar o añadir arm gemini. | **sí** |
+| `server/setup-manager.ts:697-700,1306-1307` | regex allow-list `m[1]==='claude'\|\|m[1]==='codex'` **descarta 'gemini' silenciosamente** → install-config cae a claude. Añadir `'gemini'`. **Fallo silencioso de alto riesgo.** | **sí** |
+| `server/setup-manager.ts:495-503` | `computeSummary` branch codex → hermano gemini si el summary difiere. | menor |
+| `server/setup-prerequisites.ts:405-423` | switch de install-hint: añadir `case 'gemini':` (URL/comando install Gemini CLI). | menor |
+| `server/agent-refine-manager.ts:73,79` | ensanchar `provider?: 'claude'\|'codex'`. (validateAgentBody ya skip non-claude). | **sí** (compile) |
+| `server/chat-manager.ts:124,132,332` | ensanchar `provider?: 'claude'\|'codex'` ctor + cast persistido. Gates `adapter.id==='claude'` (scope/userMcp) ya rutean gemini como codex (OK). | **sí** (compile) |
+| `server/result-event.ts:98-117` | `normaliseResultEvent` legacy shim: gemini cae al branch codex `else` (mis-parsea usage). **Preferir `adapter.extractResult`** (path moderno). Ensanchar union por si se usa. | menor |
+| `client/src/types/context-scope.ts:62-67` | añadir filas de coste gemini (cliente). | menor |
+| `client/src/components/analytics/ProviderBreakdownCard.tsx:9-17` | `PROVIDER_LABEL`/`PROVIDER_ACCENT`: añadir `gemini` (label + accent, p.ej. `bg-accent-success`). | menor |
+| `client/src/components/Navbar.tsx:26-43` | badge: añadir `=== 'gemini'` (label/color), sino cae a 'no CLI' rojo. | menor |
+| `client/src/components/SetupWizard.tsx:63-76` | heurísticas modelId sonnet/haiku/opus son claude-specific → branch gemini si el configure debe mostrar modelo. | menor |
+| `server/desktop-router.ts:28-35,155-157,229-234` | gate beta: añadir `SPECRAILS_GEMINI_BETA` paralelo a `SPECRAILS_CODEX_BETA`. Generalizar el refuse hardcoded `providers.includes('codex')` (línea 229). | menor (necesario para el gate) |
+| `docs/adding-a-provider.md` (**no existe en disco**) | **Crearlo** — CLAUDE.md lo referencia pero falta. Documentar el patrón "un fichero + una entrada" usando gemini como ejemplo. | menor |
+
+**NO tocar (verificado, evitar over-edit):** `core-compat.ts` (registry-driven), `provider-selection.ts` (membership; solo necesita `CliProvider` ensanchado), `spawn-lifecycle.ts` (adapter-driven, cero literales), `result-event.ts` `finaliseInvocationResult` (id-driven), `registry.ts`, `queue-manager._resolveJobAdapter`, `COALESCE(provider,'claude')` en ai-invocations/spending/db (solo backfill de NULLs legacy), `contract-refine-runner.ts`/`smash-runner.ts` (claude-only intencional).
+
+---
+
+## 6. Matriz de feature-parity
+
+| Feature | ¿Gemini lo soporta? | Qué haría falta para paridad |
+|---|---|---|
+| **Jobs/rails (compila + corre)** | **Degradado/Bloqueado** | Compila vía adapter. **BLOQUEANTE para rails reales**: `queue-manager.ts:976-981` pasa el slash `/specrails:implement #N` crudo a Gemini en el `else` final — Gemini NO entiende slash-commands de Claude (Codex los traduce a `$skill`). Paridad: branch gemini que mapee slash→forma que entiendan las skills de specrails-core en Gemini. |
+| **Explore Spec (multi-turno)** | **Nativo (degradado)** | `--resume` headless + `--session-id` pre-asignado funcionan. Spawn-per-turn con `-p`. Sin pérdida básica. |
+| **— persistent-stdin Explore** | **Bloqueado** | `persistentStdin:false` → spawn-per-turn (default OFF de todas formas). Requiere stdin stream-json long-lived que Gemini no documenta. |
+| **— tool-gating (Explore/Quick scope)** | **Degradado (default-safe)** | Gates `adapter.id==='claude'` → gemini recibe args vacíos (sin restricción; usa su propio `--approval-mode plan/yolo`). Paridad: branch gemini en `toolFlagsForScope` (`context-scope.ts`) mapeando ContextScope → flags Gemini. |
+| **— MCP per-spec (`.mcp.json`)** | **Degradado** | Gemini usa `.gemini/settings.json` `mcpServers`, NO el `.mcp.json` de claude ni `--mcp-config` inline. Paridad: escribir `.gemini/settings.json` en la cwd o `--allowed-mcp-server-names`. |
+| **— user-MCP (My approved MCPs)** | **Degradado (default-safe)** | `buildUserMcpArgs` devuelve `[]` para non-claude. Gemini lee su MCP global desde `~/.gemini/settings.json` (como codex con `~/.codex`) → no-op correcto, sin pérdida. |
+| **Quick spec** | **Nativo** | spawn one-shot vía adapter; coste por rate-card. |
+| **Agent profiles** | **Bloqueado (paridad codex)** | `CLAUDE_ONLY_SECTIONS=['agents']`, `profileEnvSupport` vestigial. Oculto por intersección. Paridad: soporte por sección en `provider-capabilities.ts:44-71` + `projectSupportsProfiles` por-provider. |
+| **Integrations/plugins (MCP/Serena)** | **Bloqueado (paridad codex)** | Manifest Serena omite `providerSupport` → claude-only. Paridad: añadir `'gemini'` a `providerSupport` + entry MCP bajo `.gemini/settings.json`. |
+| **SMASH** | **Bloqueado (paridad codex)** | `isSmashCapable→'claude'`. `smash-runner.ts` spawnea `claude` directo sin adapter. Paridad: reescribir runner sobre `getAdapter()` + prompt/parser Gemini + flip del gate. |
+| **Contract Refine** | **Bloqueado (inherentemente anthropic en su forma actual)** | `--resume` a sesión Claude + slash `/specrails:contract-refine`. Paridad parcial vía el path no-resume (re-seed por system prompt, como `runContractRefineForQuick`) + de-hardcodear `getAdapter('claude')`. |
+| **Ultracode interactivo** | **Bloqueado (paridad codex)** | `mode==='ultracode' && provider!=='claude'→400`; `isUltracode=adapter.id==='claude'`. Paridad: quitar el 400 para gemini, generalizar el branch ultracode-prompt, `persistentStdin:true` para el interactivo. Mecanismo no-anthropic; factible. |
+| **Analytics/coste** | **Nativo (estimado)** | `nativeCostUsd:false` + filas pricing → coste estimado, `estimated=true`. Filtros engine ya data-driven. |
+| **OTEL/telemetry** | **Nativo (MEJOR que codex)** | `nativeOtelEnv:true` → env-injection (no bridge). Solo parametrizar el enable-var en `buildTelemetryEnv`. Caveat correlación (§4). |
+| **Terminal CLI launch** | **Nativo** | `CliLaunchMenu` itera providers; aparece tras ensanchar union + wiring binario. |
+
+**Problema de la intersección binaria `=== 'claude'`**: `sectionVisibleForProviders` **oculta una sección si CUALQUIER proveedor instalado no la soporta**. En un proyecto mixto claude+gemini, Agents/SMASH/etc. desaparecen porque gemini no las declara — igual que codex hoy. **Si se generalizara `provider-capabilities.ts`** (soporte por-sección por-proveedor en vez del `Set` claude-only), Gemini *ganaría*: Agent Profiles (solo env `SPECRAILS_PROFILE_PATH`, agnóstico), tool-gating, user-MCP, file-summary cheap-model — todas mecanismo-dependientes. Solo Contract Refine es inherentemente anthropic. **Decisión v1**: paridad-codex (ocultar), generalización diferida a follow-up.
+
+---
+
+## 7. Riesgos y mitigaciones
+
+| Riesgo | Mitigación |
+|---|---|
+| **Pin de versión pre-1.0** (cambia a diario; nightly 0.48) | `minCliVersion='0.11.0'` (piso validado de stream-json). `detectInstalled` surface meetsMinimum + upgrade hint. Documentar que los ids preview rotan. |
+| **Drift del stream-json** (bugs #9281/#11184/#9009) | Esos bugs son del `--output-format json` (single-object `response`), **NO del stream-json** (usa message deltas, sin `response`). #9009 (flag desconocida) cerrado, afecta <0.6 — el pin 0.11 lo evita. **Golden-snapshot test**: fixtures NDJSON bajo `__fixtures__/` verbatim del `stream-json-formatter.test.ts` upstream, aserción `toEqual` sobre el AdapterEvent[]. |
+| **Scope por cwd-hash en resume** | Sesiones scopeadas por `getProjectHash(cwd)`. **Siempre spawn desde `project.path`** (ya lo hace el host). Resume cross-cwd no encuentra la sesión → host-controllable. Pre-asignar `--session-id <UUID>` para no depender de parsear init en builds <2025-12-04. |
+| **Exit code 53** (turn limit, no quota) | Mapear 53 = "cap de turnos `maxSessionTurns`" distinto de error general. 42 = bad input/args. Resto non-zero → tratar como exit 1 (general/API). Quota/429/403 colapsan a exit 1. |
+| **Auth headless** | **Presetear `GEMINI_API_KEY`** en el env de spawn → `getAuthTypeFromEnv()` devuelve `USE_GEMINI`, `validateAuthMethod` pasa, sin browser. Alt CI: `GOOGLE_GENAI_USE_VERTEXAI=true`+`GOOGLE_CLOUD_PROJECT`+`GOOGLE_CLOUD_LOCATION`+`GOOGLE_APPLICATION_CREDENTIALS`. **No setear `security.auth.enforcedType`** conflictivo. Sin var de auth → `process.exit(FATAL_AUTHENTICATION_ERROR)` (no browser). El host necesita un flujo para que el usuario provea la API key (Settings/AddProject). |
+| **Drift OTEL** (correlación `session.id` vs `specrails.job_id`) | Telemetry OFF por defecto → no bloquea v1. Al activar: validar si Gemini propaga `OTEL_RESOURCE_ATTRIBUTES`; fallback correlación por `--session-id` de spawn-time. |
+| **Bug OTLP/HTTP #15581** (POST a `/` no `/v1/{signal}`) | Usar `GEMINI_TELEMETRY_OTLP_PROTOCOL=grpc` (default :4317, well-tested), evitar HTTP. |
+| **Coste >200k tokens infra-estimado** | Aceptado en v1 (tier ≤200k). Analytics marca `estimated`. Follow-up: tiering en `PriceEntry`. |
+
+---
+
+## 8. Plan de tests + coverage
+
+CI exige **80% server** (lines/functions/statements, 70% branches) y **80% client** (lines/statements, 70% functions). Cada fichero tocado debe llegar.
+
+**Tests nuevos server:**
+- `server/providers/gemini-adapter.test.ts` (espejo de `codex-adapter.test.ts`):
+  - `capabilities` exactos (8 campos).
+  - `buildArgs` por cada uno de los 9 SpawnActions (línea exacta; resume throw si `!sessionId`; chat-stream throw; fold cuando `systemPromptArg=false`; `extraArgs` appendeado).
+  - `parseStreamLine`: fixtures NDJSON bajo `server/providers/__fixtures__/gemini-*.ndjson` (init/message/tool_use/tool_result/error/result/línea-vacía/parse-fail), aserción del AdapterEvent[].
+  - `extractResult`: stats → tokens_in/out/cache_read, num_turns, session_id, `total_cost_usd` undefined.
+  - `detectInstalled`: mock de `execSync` (no instalado / version OK / version < min / probe-fail / timeout >3s → installed:false).
+- `server/pricing.test.ts`: 4 filas `gemini:*`, `estimateCostUsd('gemini',model,usage)` correcto; clave ausente → null; semántica cached (no doble-conteo).
+- `server/provider-selection.test.ts`: `isProviderEnabled`/`resolveProvider`/`validateRequestedProvider` aceptan `'gemini'`; multi-provider claude+gemini.
+- `server/providers/registry.test.ts`: `getAdapter('gemini')`/`hasAdapter`/`listAdapters` incluye gemini tras import de index.
+
+**Tests nuevos client:**
+- `ModelSelector`/`ChatInput`: provider `'gemini'` muestra `GEMINI_MODELS` (no Codex).
+- `AddProjectDialog`: checkbox gemini cuando `/available-providers` lo devuelve; `noProviderAvailable` iterado.
+- `provider-capabilities.test.ts`: `providerLabel('gemini')`, `sectionVisibleForProviders` oculta Agents/SMASH en proyecto con gemini (paridad codex).
+- `ProviderBreakdownCard`/`Navbar`: label+accent gemini.
+
+**Gate `SPECRAILS_GEMINI_BETA`**: test en `desktop-router.test.ts` — con `=0`, `/available-providers` devuelve `gemini:false` y `POST /projects` con `providers:['gemini']` se rechaza; default/`1` → habilitado. Espejo de `SPECRAILS_CODEX_BETA`.
+
+**Cumplir 80%**: el adapter es lógica pura (sin I/O salvo `detectInstalled` mockeado) → fácil 100%. Cubrir los 9 cases de `buildArgs` garantiza branch coverage. Las filas pricing y los branches `=== 'codex'` generalizados necesitan un test que ejercite el path gemini (ai-edit con provider gemini → `adapter.binary='gemini'`). Excluir solo lo Tauri-only inalcanzable en jsdom, documentando inline; **nunca para enmascarar tests faltantes**.
+
+---
+
+## 9. Rollout por fases
+
+1. **PR-A (generalización previa)** — ensanchar `CliProvider`/`ProviderId`/las ~12 uniones `('claude'|'codex')[]`, desramificar `/available-providers` y `spec-models.ts`/`ModelSelector`/`ChatInput` a lookups por id. **Sin Gemini todavía**; comportamiento idéntico. Mergeable y testeable solo. Reduce el blast-radius del PR-B.
+2. **PR-B (el adapter)** — `gemini-adapter.ts` + `register` + filas pricing + branches gemini (ai-edit dispatch, setup-manager regex, install-hint) + labels/accents + `SPECRAILS_GEMINI_BETA`. **Gemini detrás del gate beta**, default ON con kill-switch.
+3. **Beta-gated validation** — probar end-to-end: detect, add-project con gemini, Quick spec, Explore multi-turno (resume), Analytics coste, terminal launch. Validar exit 53/42, auth `GEMINI_API_KEY`. **NO** habilitar rails reales hasta resolver la traducción slash-command (§6, bloqueante) — gemini sirve para spec/explore/quick en esta fase.
+4. **Docs** — crear `docs/adding-a-provider.md` (falta) con gemini como ejemplo, y `docs/gemini.md` (espejo de `docs/codex.md`) con setup de API key.
+
+**Primer commit recomendado:** PR-A paso atómico — ensanchar `server/desktop-db.ts:10` `CliProvider` para incluir `'gemini'` y convertir el ternario de `server/spec-models.ts:1-37` `getModelsForProvider` en lookup `Record<provider, SpecModelOption[]>`. Desbloquea la cadena de tipos sin tocar comportamiento y deja la base lista para registrar el adapter.
+
+**Puntos `[UNCERTAIN]` pendientes (no inventados):** (a) `OTEL_RESOURCE_ATTRIBUTES` propagation en Gemini — validar empíricamente antes de confiar para correlación job/project; (b) semántica de `cachedContentTokenCount` como subconjunto de input — fijar por test de pricing; (c) `mcpRegistration` exacto en la versión bundleada — verificado que escribe a settings.json (`project-json`), confirmar en build. Ninguno bloquea v1 (spec/explore/quick); todos tienen fallback.

package/docs/gemini-core-support-evaluation.md

@@ -0,0 +1,160 @@
+> Documento de planificación. Generado 2026-06-17 mediante auditoría multi-agente del repo real `/Users/javi/repos/specrails-core` + verificación de fuentes primarias de gemini-cli. Complementa `docs/gemini-cli-provider-study.md` (desktop) — esta evalúa el trabajo en **specrails-core** para habilitar rails/implement en Gemini.
+
+---
+
+# Evaluación: ¿Hay que tocar specrails-core para Gemini CLI?
+
+> **Veredicto en una línea:** Sí, **obligatoriamente hay que tocar core** para que `implement`/`batch-implement` (rails) funcionen en Gemini. El desktop por sí solo (PR-A/PR-B + `gemini-adapter.ts`) cubre **solo** spec/explore/quick. El pipeline architect→developer→reviewer **es expresable sin rediseño de fases** en el modelo plano de Gemini, pero **sin un target gemini en core no hay agentes ni comandos ni skills que ejecutar**, así que los rails en gemini hoy son inejecutables.
+
+---
+
+## 1. Respuesta directa: ¿hay que tocar core?
+
+**Sí, para los rails. No, para spec/explore/quick.** El corte es exacto y limpio:
+
+### Ya funciona HOY sin tocar core (solo desktop adapter)
+El desktop tiene `server/providers/gemini-adapter.ts` registrado (`server/providers/index.ts:12,16`), con `projectDirName: '.gemini'`, `instructionsFilename: 'GEMINI.md'`, `nativeCostUsd: false` (gemini-adapter.ts:225-235). Esto cubre las superficies que **NO dependen de artefactos instalados en el repo**:
+- **Explore Spec** — spawnea gemini desde `explore-cwd/` con un `CLAUDE.md`/system-prompt embebido por el desktop; no lee `.gemini/*`.
+- **Quick spec** (`POST /tickets/generate-spec`) — turno suelto, system prompt inyectado por el desktop.
+- **Sidebar chat** — idem.
+
+Estas tres superficies inyectan su propio prompt y no resuelven slash-commands ni subagentes del proyecto. Por eso el adapter desktop basta.
+
+### EXIGE core (sin esto, los rails en gemini no arrancan)
+`implement` y `batch-implement` **no son prompts** que el desktop inyecte: son **artefactos instalados en el repo** que el orquestador resuelve nativamente. El desktop solo pasa el comando resuelto al binario (`queue-manager.ts` `buildArgs('rail-job', …)`), y el binario espera encontrar en disco:
+1. **Comandos** `implement` / `batch-implement` (en formato gemini: `.gemini/commands/*.toml`).
+2. **Agentes** `sr-architect`/`sr-developer`/`sr-reviewer` (en `.gemini/agents/*.md` con frontmatter).
+3. **Skills/comandos OpenSpec** (`opsx:*`) instalados por `openspec init --tools gemini`.
+4. **`GEMINI.md`** (instrucciones de proyecto) + settings.
+
+**Core no emite NADA de esto para gemini** — verificado: `grep -rni gemini` sobre `src/`, `templates/`, `integration-contract.json` devuelve **0 matches**. El tipo `Provider` es un set cerrado `'claude' | 'codex'` que **rechaza** cualquier otro valor en `install-config.ts:96` (`unsupported provider '...'`). Por tanto, hoy un proyecto gemini no puede ni siquiera instalarse: el handshake desktop→core (desktop escribe `provider:` en `install-config.yaml`, `setup-manager.ts:906`; core valida en `install-config.ts:96` e `init.ts:86`) **falla en duro** con "unsupported provider 'gemini'".
+
+**Conclusión inequívoca:** spec/explore/quick = solo desktop, ya hecho. Rails (implement/batch-implement + agentes + skills + OpenSpec) = **bloqueado en core**, requiere un target gemini.
+
+---
+
+## 2. Cómo emite core hoy por proveedor
+
+El flujo real de instalación: `init.ts` → `provider-detect.derivedPaths(provider)` → `scaffold.scaffoldInstallation` → `installOpenSpecProject`.
+
+### Detección/selección de proveedor (todo cerrado a 2 literales)
+- **Tipo:** `Provider = 'claude' | 'codex'` declarado en DOS sitios que deben coincidir: `provider-detect.ts:15` e `install-config.ts:13`.
+- **Detección:** `detectAvailability()` solo sondea claude/codex en PATH — verificado verbatim:
+  ```ts
+  const [claude, codex] = await Promise.all([commandExists('claude'), commandExists('codex')])
+  return { claude, codex }
+  ```
+  (`provider-detect.ts:33-36`).
+- **Validación dura:** `install-config.ts:96` rechaza ≠ claude/codex; `init.ts:86` rechaza el flag `--provider`; `bin/tui-installer.mjs:114/118`.
+
+### Dónde divergen claude vs codex
+Toda la divergencia es **imperativa, `if (input.provider === 'codex')`**, no hay registry/adapter (contraste con el `ProviderAdapter` del desktop). Sitios clave en `scaffold.ts`:
+- **Convención de paths** centralizada en `derivedPaths` — verificado verbatim: codex → `{ '.codex', 'AGENTS.md' }`, else → `{ '.claude', 'CLAUDE.md' }` (`provider-detect.ts:87-92`).
+- Esqueleto de directorios (`scaffold.ts:174-184`): claude `.claude/commands/specrails` + `.claude/skills`; codex `.codex/skills/{enrich,doctor,rails}`.
+- Colocación de comandos (`copyBundledCommands`, `scaffold.ts:278-311`): claude copia `.md` verbatim; codex porta cada comando a `.codex/skills/<name>/SKILL.md` vía `writeCodexSkillFromCommand` (rewrite `.claude/`→`.codex/`, `/specrails:x`→`$x`) salvo que exista override en `templates/codex-skills/<name>/`.
+- Agentes (`scaffold.ts:493-648`): claude coloca `.claude/agents/sr-*.md` + memory dirs; codex **salta agentes** y usa rail-skills en `.codex/skills/rails/`.
+- Skills (`placeSkills`, `scaffold.ts:762-830`): claude **genera** `sr-*` skills desde el cuerpo del comando (`SKILL_FROM_COMMAND`, `scaffold.ts:46-82` + `writeClaudeSkillFromCommand`); codex copia `templates/codex-skills/rails/`.
+- Settings (`scaffold.ts:244-250`): codex-only `applyCodexSettings` escribe `.codex/config.toml` + `AGENTS.md` con bloque sentinel-managed (`renderInitialAgentsMd`, `scaffold.ts:666-747`). Claude **no** tiene settings-writer aquí (su `CLAUDE.md` no lo escribe el instalador, solo lo chequea `doctor.ts:91`).
+
+### Cómo se instala OpenSpec (esto SÍ es ya per-provider)
+`installOpenSpecProject(repoRoot, provider)` (llamado solo en `init.ts:128`, **no** en update) shellea — verificado verbatim:
+```ts
+args: ['--yes', '-p', `@fission-ai/openspec@${pinnedVersion}`, '--',
+       'openspec', 'init', '--tools', provider, repoRoot]
+```
+(`init.ts:204-218`, pin `1.3.1` desde `pinned-versions.json:3`). **Pasa `provider` DIRECTO a `--tools`.** Esto significa que la capa OpenSpec **no es el bloqueante**: `openspec init --tools gemini` es nativamente soportado por openspec 1.3.1 (genera `.gemini/commands/opsx` + `.gemini/skills/openspec-*` + el dir agnóstico `openspec/{specs,changes}`). En cuanto core propague el literal `gemini` a esta llamada (pasos 1+3 abajo), OpenSpec hace lo correcto **sin cambios de código**.
+
+---
+
+## 3. El target gemini en core: qué emitir, transform vs autoría nueva, additividad
+
+### Qué debe emitir
+| Artefacto | Formato gemini | Origen |
+|---|---|---|
+| `implement`, `batch-implement` (+ resto comandos) | `.gemini/commands/specrails/*.toml` — **solo `prompt` + `description`**, sin `tools`/`model` | **Transform** de `templates/commands/specrails/*.md` (reusar el cuerpo, re-envolver en TOML) |
+| `sr-architect/developer/reviewer` (+ opcionales) | `.gemini/agents/sr-*.md` con **YAML frontmatter** que SÍ lleva `model` + `tools` | **Transform** de `templates/agents/sr-*.md` (markdown ya compatible; ajustar frontmatter + `MEMORY_PATH`→`.gemini/agent-memory/`) |
+| `GEMINI.md` + settings | `GEMINI.md` con bloque sentinel + `.gemini/settings.json` (con `experimental.enableAgents`) | **Autoría nueva** — clon de `applyCodexSettings`/`renderInitialAgentsMd` (`scaffold.ts:666-747`) |
+| OpenSpec (`opsx:*`) | `.gemini/commands/opsx/*` + `.gemini/skills/openspec-*` | **Sin cambios** — lo emite `openspec init --tools gemini` |
+
+### Transform vs autoría — la asimetría es **decisiva** y la dicta el formato gemini
+El veredicto verificado fija la regla: **commands TOML solo aceptan `prompt`+`description`** (sin `tools`/`model` por comando), pero **subagents `.md` SÍ aceptan `tools`+`model` en frontmatter**. Consecuencia de arquitectura para el scaffold:
+
+> El **model-routing y el tool-gating** que hoy viven embebidos en `implement.md` (bloque ORCHESTRATOR_MODEL ~líneas 160-171 + overrides por agente) **deben migrar al frontmatter de los `.gemini/agents/sr-*.md`**, NO al comando TOML.
+
+Mapeo correcto: orquestador → `.gemini/commands/specrails/{implement,batch-implement}.toml` (solo prompt+description); roles → `.gemini/agents/sr-*.md` (con `model:`, `tools:`). Esto **espeja el split de codex** (comando-vs-skill) pero con el primitivo de subagente nativo de gemini en vez de `spawn_agent`.
+
+**Neto:** es una **mezcla** — cuerpos de comandos y agentes son **transforms mecánicos** de los templates claude existentes; el **emisor TOML** (`writeGeminiCommandFromCommand`, análogo a `writeCodexSkillFromCommand`), el **escritor `GEMINI.md`/settings**, y el **plumbing de tipo/detección** son **autoría nueva**. Lo más limpio: añadir `templates/gemini-skills/` (o `templates/gemini-*`) como dir de override para lo que el transform mecánico produzca mal, igual que `templates/codex-skills/`.
+
+### Cómo se añade de forma aditiva sin romper claude/codex
+Es aditivo en **semántica** (cada branch es `=== 'codex'` / else-claude; añadir un brazo `=== 'gemini'` deja los paths existentes byte-idénticos; el allow-list de validación solo se ensancha, nunca rechaza configs previas válidas), pero **NO aditivo en código** (no hay abstracción → hay que editar cada sitio). Cambios concretos (~7 archivos + nuevo árbol de templates):
+1. Ensanchar `Provider` en `provider-detect.ts:15` **y** `install-config.ts:13` (deben quedar idénticos); relajar validadores `init.ts:86`, `install-config.ts:96`, `bin/tui-installer.mjs:114/118`.
+2. `detectAvailability` (`provider-detect.ts:33-36`): añadir `commandExists('gemini')`; extender `resolveProvider` (61-80) + el mensaje de error que hoy solo nombra Claude+Codex.
+3. `derivedPaths` (`provider-detect.ts:87-92`): brazo gemini → `{ '.gemini', 'GEMINI.md' }`.
+4. `scaffold.ts`: brazos gemini en cada `=== 'codex'` (dir skeleton 174-184, colocación comandos 278-325, quick-tier 493-648, `placeSkills` 762-830, prune 454-462) + `applyGeminiSettings` clon de `applyCodexSettings`.
+5. `prereqs.ts:91-104`: gatear el bloque claude-only o dar a gemini un path mínimo (sin auth-assert, como codex).
+6. `doctor.ts:96/160/167` + `update.ts:196-210` (`resolveExistingProvider` probe `.gemini`).
+7. `integration-contract.json:3-26`: bloque `providers.gemini` (la superficie casi-declarativa que lee el desktop; la de menor fricción).
+8. OpenSpec: **cero cambios de código** más allá de propagar `gemini` (pasos 1+3 → ya llega a `init.ts:215`).
+
+---
+
+## 4. El bloqueante de orquestación: ¿plano de gemini lo soporta?
+
+**Veredicto honesto (verificado contra fuentes Google primarias): el pipeline ES expresable en el modelo plano de gemini SIN rediseño de fases.** No es un blocker de capacidad; es trabajo imperativo en core.
+
+Razonamiento (todo confirmado):
+- El pipeline es **recursivo pero SHALLOW**: el orquestador spawnea architect→developer→reviewer a **profundidad 1**; las hojas **nunca re-spawnean** (un developer no llama a un reviewer; lo único "hacia abajo" es un `Skill("opsx:ff/apply/archive")` **in-context**, que shellea al CLI `openspec`, **no es un subagente**). Contrato verbatim: `implement.md:5` "delegate to the agents"; `implement.md:547` spawn de sr-architect; codex `implement/SKILL.md:24` "Each phase MUST be a real spawn_agent call".
+- El modelo de gemini es exactamente eso: orquestador delega depth-1, subagentes **FLAT** (`docs/core/subagents.md` verbatim: "subagents cannot call other subagents"). La restricción plana (las hojas no spawnean) **nunca se viola** porque todo el spawning requerido ocurre en el orquestador a depth-1.
+- **El único rediseño** es `batch-implement`, que conceptualmente anida (batch→implement→roles = depth 2), ilegal en plano. **Pero el proyecto YA lo resolvió para codex**: `codex-skills/batch-implement/SKILL.md:5` "Drives architect/developer/reviewer spawns at the ROOT agent level — does NOT spawn a nested $implement sub-agent per ticket". El batch-implement gemini **reutiliza esa misma disciplina de aplanamiento ya probada**.
+
+**Por tanto: NO hay rediseño del pipeline de fases. La viabilidad de rails en gemini está gateada por el trabajo imperativo en core, no por un gap de capacidad de gemini.**
+
+Matiz honesto (no inventado): subagents en gemini son **experimentales** (namespace `experimental.enableAgents`, PR #14371, públicos desde v0.38.1 — ahora habilitados por defecto pero aún bajo `experimental.*`). Y queda un **unknown externo** que estos repos no pueden resolver: si el orquestador gemini puede **iniciar** spawns en headless/non-interactivo o si la delegación `@name` está garantizada sin TTY (ver riesgos §6).
+
+---
+
+## 5. Esfuerzo + secuenciación + versión + reutilización agy/Antigravity
+
+**Tamaño del trabajo en core:** moderado, no trivial. ~7 archivos editados (`provider-detect`, `install-config`, `scaffold`, `prereqs`, `doctor`, `init`, `update`, `bin/tui-installer.mjs`) + `integration-contract.json` + **un árbol nuevo `templates/gemini-skills/`** (o `gemini-*`) + tests (incluido el contrato `reserved-paths.test.ts`, que debe seguir verde para init+update gemini). La falta de abstracción installer-side significa **N ediciones inline, no un descriptor**. La mayor parte del esfuerzo de autoría es: el emisor TOML, el escritor `GEMINI.md`/settings, y **validar empíricamente** que la orquestación plana de gemini ejecuta las fases en headless.
+
+**Secuenciación con el beta desktop:**
+1. **PR-A #396** (generaliza tipos) y **PR-B #397** (adapter beta-gated) habilitan spec/explore/quick en gemini — **independientes de core**, se mergean primero.
+2. El target gemini en core es **secuencialmente posterior** y desbloquea rails. Mientras tanto, el desktop debería **ocultar rails/implement para gemini** (capability-intersection: igual que codex fuerza `profile=null` y oculta Agents/Integrations) hasta que core publique el target.
+
+**Versión de core:** feature aditiva → conventional-commit `feat:` → release-please **MINOR**. Desde 4.7.1 actual → **4.8.0**. El profile-gate `>= 4.1.0` (`queue-manager.ts:77`, `profiles-router.ts:233`) **no se toca**: proyectos gemini en 4.8.0 ya lo satisfacen. Que gemini **participe** en profiles es una decisión de política del desktop (probablemente como codex: `profile=null`), no un cambio de gate.
+
+**¿Puramente aditivo?** En contrato/runtime: **sí** (no rompe claude/codex). En código: **no** (cada branch imperativo gana un brazo gemini). Reserved-paths sin cambios.
+
+**Reutilización agy/Antigravity (no es trabajo tirado):** Antigravity comparte el harness `~/.gemini` (mismas convenciones `.gemini/commands/*.toml`, `.gemini/agents/*.md`, `GEMINI.md`). Un target gemini en core que emita en formato `.gemini/*` **sirve de base directa para agy** más adelante — el scaffold gemini es reutilizable casi tal cual. Esto sube el ROI del trabajo de core.
+
+---
+
+## 6. Recomendación
+
+### Decisión: **HACER, pero DESPUÉS del beta desktop de spec/explore/quick (no en paralelo, no bloqueante del beta).**
+
+Justificación: el beta desktop (PR-A/PR-B) entrega valor real de gemini (spec/explore/quick) **sin tocar core** y sin riesgo. Los rails en gemini son un trabajo de core mayor, con un unknown empírico (headless), y **no deben retrasar el beta**. El desktop oculta rails para gemini mientras tanto.
+
+### Ownership
+- **Desktop owna:** el adapter gemini (ya hecho), capability-intersection para ocultar rails/Agents/Integrations en gemini hasta que core publique, command-syntax translation en `queue-manager` (hoy claude=verbatim, codex=`/x`→`$x`; gemini necesita su forma), y `profile=null` para rails gemini.
+- **Core owna:** el target de instalación gemini completo (tipos/detección, `.gemini/commands/*.toml`, `.gemini/agents/sr-*.md`, `GEMINI.md`/settings, `templates/gemini-skills/`, `integration-contract.json` gemini block, propagar `gemini` a `openspec init --tools`), y los tests.
+
+### Primer paso concreto en core
+Un **spike de validación de orquestación**, ANTES de escribir el scaffold completo: instalar manualmente a mano un `.gemini/commands/specrails/implement.toml` (prompt mínimo) + `.gemini/agents/sr-{architect,developer,reviewer}.md` (frontmatter con `model`/`tools`) + `enableAgents`, correr `openspec init --tools gemini`, y ejecutar el binario `gemini` en modo headless/exec (como lo spawnearía el desktop) para **confirmar empíricamente** que el orquestador inicia los spawns depth-1 y completa architect→developer→reviewer sin TTY. Si pasa, se procede al scaffold; si no, el riesgo se materializa antes de invertir en los 7 archivos.
+
+### Riesgos honestos
+1. **TOML sin `tools`/`model` por comando** — confirmado: los `.gemini/commands/*.toml` no pueden restringir tools ni fijar modelo. El routing/gating **debe** vivir en el frontmatter de los `.gemini/agents/*.md`. Si algún comando dependía de gating a nivel comando, hay que re-arquitecturarlo a nivel agente.
+2. **Subagentes experimentales** — `experimental.enableAgents`; comportamiento puede cambiar entre versiones de gemini-cli. Pinear/probar contra una versión concreta.
+3. **Shell-injection con confirm interactivo en headless** — los agentes shellean al CLI `openspec` vía Skill in-context; si gemini exige confirmación interactiva de tool-calls de shell y el desktop lo spawnea sin TTY, las fases podrían colgarse. **Riesgo no verificado, alto impacto** — es lo que el spike del primer paso debe descartar.
+4. **`@`-routing headless no garantizado** — la delegación forzada `@sr-architect` puede no funcionar sin interactividad; quizás haya que apoyarse en auto-delegación, menos determinista para un pipeline que exige las tres fases.
+5. **OpenSpec install adaptado a gemini** — `openspec init --tools gemini` está confirmado nativo en 1.3.1, pero **no verifiqué empíricamente en esta sesión** que los `.gemini/skills/openspec-*` que genera sean **invocables** por el orquestador gemini en el flujo real (solo que el `--tools` lo acepta). Validar en el spike.
+
+### Lo que NO está cierto (declarado explícitamente)
+- Si el orquestador gemini puede **iniciar** spawns en headless/exec, o si solo el harness puede pre-definir un set fijo de agentes. Si fuera lo segundo, el orquestador `implement` habría que re-expresarlo como agentes paralelos definidos por harness en vez de spawns iniciados por el orquestador — **lift mayor**. Esto **decide la viabilidad real** y no es deducible de estos repos.
+- El comportamiento exacto de confirm de shell-calls de gemini en headless (riesgo #3).
+
+**Archivos clave (absolutos):**
+- Core gap: `/Users/javi/repos/specrails-core/src/installer/phases/provider-detect.ts` (15, 33-36, 87-92), `/Users/javi/repos/specrails-core/src/installer/phases/install-config.ts` (13, 96), `/Users/javi/repos/specrails-core/src/installer/phases/scaffold.ts` (174-184, 244-250, 278-311, 666-747, 762-830), `/Users/javi/repos/specrails-core/src/installer/commands/init.ts` (86, 128, 204-218), `/Users/javi/repos/specrails-core/integration-contract.json` (3-26), `/Users/javi/repos/specrails-core/pinned-versions.json` (3).
+- Templates a transformar: `/Users/javi/repos/specrails-core/templates/commands/specrails/implement.md`, `/Users/javi/repos/specrails-core/templates/commands/specrails/batch-implement.md`, `/Users/javi/repos/specrails-core/templates/agents/sr-{architect,developer,reviewer}.md`.
+- Precedente de aplanamiento codex: `/Users/javi/repos/specrails-core/templates/codex-skills/batch-implement/SKILL.md` (5, 19-32), `/Users/javi/repos/specrails-core/templates/codex-skills/implement/SKILL.md` (24).
+- Desktop (ya hecho): `/Users/javi/repos/specrails-desktop/server/providers/gemini-adapter.ts` (225-235), `/Users/javi/repos/specrails-desktop/server/providers/index.ts` (12, 16); a tocar: `/Users/javi/repos/specrails-desktop/server/queue-manager.ts` (command translation, `profile=null`), `/Users/javi/repos/specrails-desktop/client/src/lib/provider-capabilities.ts` (ocultar rails gemini).

package/docs/gemini.md

@@ -0,0 +1,106 @@
+# Using Specrails with the Gemini CLI
+
+Specrails supports Google's [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+as a third AI provider alongside Claude Code and the Codex CLI.
+
+> **Beta — opt-in.** Gemini is gated behind `SPECRAILS_GEMINI_BETA` and is **off by
+> default**. Until you set it, Gemini is invisible everywhere (it won't show in Add
+> Project and can't be selected). See [Enabling the beta](#enabling-the-beta).
+>
+> **Scope today.** With the beta on, Gemini powers the *non-pipeline* surfaces —
+> Explore Spec, Quick spec, AI Edit, the terminal launcher, and cost analytics.
+> The full **rails pipeline** (`/specrails:implement`, `batch-implement`) needs a
+> Gemini artifact target in `specrails-core` (`.gemini/commands/*.toml` +
+> `.gemini/agents/sr-*.md`), which ships separately. Rails are hidden for Gemini
+> projects until then.
+
+## Prerequisites
+
+- **Gemini CLI ≥ 0.11.0** on your `PATH` (`npm i -g @google/gemini-cli`; `gemini --version`).
+  Older versions lack `--output-format stream-json` and headless `--resume`.
+- **A Gemini API key.** Specrails spawns Gemini headlessly, so it needs
+  non-interactive auth: set `GEMINI_API_KEY` (a paid Gemini Developer API key from
+  [Google AI Studio](https://aistudio.google.com/apikey)). The free OAuth
+  "Login with Google" tier exists but is being wound down for the CLI and is not a
+  reliable unattended path — use an API key.
+
+## Enabling the beta
+
+Set the env var where the Specrails server runs, then restart the app:
+
+```bash
+SPECRAILS_GEMINI_BETA=1   # or 'true'
+```
+
+With it set, `GET /api/available-providers` reports Gemini's real install status,
+Add Project shows a **Gemini** checkbox, and projects can select it.
+
+## Adding a Gemini project
+
+Add Project → tick **Gemini** (visible once the beta is on and `gemini` is on PATH).
+A project can install Gemini alongside Claude/Codex; the first provider selected is
+the primary/default, and per-invocation engine pickers let you choose per spec/rail.
+
+## What's different vs Claude
+
+- **Cost is estimated, not native.** Gemini does not report a USD cost in its
+  stream, so Specrails estimates it from a rate card (`server/pricing.ts`,
+  keys `gemini:<model>`). Token counts (incl. cached) come straight from the run.
+- **No per-agent profiles / SMASH / Contract Refine.** These are Claude-only; on a
+  mixed project the capability intersection hides them (same as Codex).
+- **System prompt is folded.** Gemini has no `--system-prompt` flag, so for
+  non-Explore actions the system prompt is folded into the user prompt. Explore
+  turns stay user-only and trust the app-managed `GEMINI.md` in the explore cwd.
+- **OTEL is native.** Unlike Codex, Gemini emits OTLP via `GEMINI_TELEMETRY_*`, so
+  pipeline telemetry needs no synthetic bridge.
+
+## Models
+
+Curated catalog (`server/providers/gemini-adapter.ts`): `gemini-2.5-pro` (default),
+`gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-3.1-pro-preview`. Concrete GA
+ids are pinned (preview ids rotate). Free-tier API keys serve Flash; Pro/preview
+need billing.
+
+## Trusted folders (headless)
+
+Gemini's "trusted folders" gate silently overrides `--yolo` back to `default` —
+blocking *every* tool call — in a directory it doesn't trust. Specrails injects
+`GEMINI_CLI_TRUST_WORKSPACE=true` into every Gemini spawn (`server/util/cli-prompt.ts`
+`spawnGemini`) so headless rails/explore can actually run tools. No action needed
+from you.
+
+## Troubleshooting
+
+- **"Gemini" never appears in Add Project** → the beta is off (`SPECRAILS_GEMINI_BETA`
+  unset), or `gemini` isn't on PATH. Check `GET /api/available-providers`.
+- **Tools never run / job does nothing** → almost always auth or trust. Confirm
+  `GEMINI_API_KEY` is set in the server env; the trust var is handled automatically.
+- **`limit: 0` / quota errors on Pro** → free-tier API keys don't serve Pro models;
+  use a Flash model or enable billing.
+- **Cost shows `—`** → no `gemini:<model>` pricing row for the model used; add one to
+  `server/pricing.ts`.
+
+## Emergency rollback
+
+Unset `SPECRAILS_GEMINI_BETA` (or set it to `0`). Gemini disappears from the UI and
+becomes unselectable immediately; existing non-Gemini projects are unaffected. The
+adapter stays registered but dormant.
+
+## Architecture pointers (for specrails-desktop developers)
+
+- Adapter: `server/providers/gemini-adapter.ts` (`nativeCostUsd:false`,
+  `nativeOtelEnv:true`, `systemPromptArg:false`, `instructionsFilename:'GEMINI.md'`,
+  `mcpRegistration:'project-json'`). Registered in `server/providers/index.ts`.
+- Stream schema (validated against gemini 0.46): `init{session_id,model}` /
+  `message{role,content,delta}` / `tool_use{tool_name,tool_id,parameters}` /
+  `tool_result` / `result{stats}`. `stats.input_tokens` includes `stats.cached`.
+- Beta gate + provider list: `server/desktop-router.ts` (`isGeminiBetaEnabled`,
+  `/available-providers`, `POST /projects`).
+- Trust-folder env: `server/util/cli-prompt.ts` `spawnGemini`.
+
+## See also
+
+- [`docs/codex.md`](./codex.md) — the Codex provider (the other non-native provider).
+- [`docs/adding-a-provider.md`](./adding-a-provider.md) — how to add a provider.
+- [`docs/gemini-cli-provider-study.md`](./gemini-cli-provider-study.md) — the design study.
+- [`docs/gemini-core-support-evaluation.md`](./gemini-core-support-evaluation.md) — the rails/core work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/chat-manager.js

@@ -278,7 +278,7 @@ class ChatManager {
                 slug: this._projectSlug,
                 projectPath: this._cwd,
                 projectName: this._projectName,
-                provider: (providerId ?? this._adapter.id),
+                provider: providerId ?? this._adapter.id,
             });
             console.log(`[chat-manager] explore spawn cwd=${cwd} (mcp=off)`);
             return cwd;