specrails-desktop 2.8.0 → 2.9.0

package/docs/internals/global-artifacts-relocation-evaluation.md

@@ -0,0 +1,294 @@
+# Evaluación arquitectónica: reubicar TODOS los artefactos fuera de los repos importados
+
+> Documento de decisión técnica. Audiencia: arquitectos de `specrails-core` + `specrails-desktop`.
+> Objetivo evaluado: que `specrails-core` instale y que `specrails-desktop` lea **todos** los
+> artefactos de Specrails desde `$HOME/.specrails`, y todos los artefactos de los CLIs
+> (claude/gemini/codex) desde `$HOME/.claude`, `$HOME/.gemini`, `$HOME/.codex`, de modo que
+> **los repos importados NUNCA se modifiquen** (cero `.specrails/.claude/.codex/.gemini` en el repo,
+> cero mutaciones de `.gitignore`, cero archivos de instrucciones).
+
+---
+
+## 1. Resumen ejecutivo
+
+El objetivo es **parcialmente alcanzable, no plenamente**, y la frontera entre lo alcanzable y lo irreductible es nítida y está bien fundamentada en la evidencia. La pieza maestra es un hecho confirmado en código y en los CLIs vivos: **los tres CLIs (claude, codex, gemini) anclan su "project scope" — agentes, comandos, skills, settings, archivo de instrucciones, `.mcp.json` — al directorio de trabajo (CWD), no al repo de git.** No existe ningún `--project-dir` en ninguno de los tres. Por tanto, si cada spawn se ejecuta desde un directorio anclado en `$HOME` (con el repo accesible mediante un symlink hijo `./project`), ese directorio pasa a ser el "proyecto" para el CLI y **cero archivos de config aterrizan en el repo**. Este patrón ya está probado y en producción en `server/explore-cwd-manager.ts`.
+
+La recomendación es **adoptar el "workspace gestionado por la app" (Opción 1) como modelo arquitectónico de destino**, porque convierte la inmunidad a colisiones en una **propiedad estructural** (no en supresión por-flag), pero **ejecutarlo por fases empezando por el alcance de la Opción 3 (Híbrido Pragmático)** para los flujos de lectura/interactivos, que ya son relocalizables hoy con cambios solo en desktop y cero cambios en contratos congelados. El panel de jueces se reparte de forma honesta: **la lente de feasibilidad CLI y la de goal-fit/UX eligen la Opción 1** (es la única que usa el único mecanismo universal, CWD-relocation, sin depender de flags que el CLI no soporta); **la lente de blast-radius/contratos elige la Opción 3** (menor superficie de cambio, cero contratos en riesgo).
+
+El techo honesto es **"repo git-limpio", no "repo file-limpio"** para proyectos que ejecutan rails de `implement`: dos artefactos son irreductiblemente repo-bound — `openspec/changes/` (entregable versionado, escrito por el binario externo `@fission-ai/openspec`, leído como working tree repo-relativo por los agentes) y los git worktrees de aislamiento (`.claude/worktrees/`, deben compartir el `.git`/object-store del repo para el merge-back). Ningún flag de ningún CLI los reubica. Para proyectos de **solo lectura** (Explore, quick-spec, chat, ai-edit) el objetivo literal de "cero archivos en el repo" **sí se cumple por completo**.
+
+---
+
+## 2. El problema hoy
+
+Cuando `specrails-desktop` importa un repo, su setup wizard ejecuta `npx specrails-core` (tier `quick`), que corre `scaffoldInstallation()` con `repoRoot = project.path` (la ruta del repo del usuario). Esto **escribe directamente dentro del repo del usuario** a través de cuatro raíces de destino, y además **muta archivos preexistentes del usuario**. El daño concreto, según el inventario de evidencia:
+
+- **Pollution de directorios completos en el repo**: `.specrails/**` (manifest, version pin, `setup-templates/` staging, `install-config.yaml`, opcionalmente `profiles/`) y `<providerDir>/**` donde `providerDir` es `.claude` / `.codex` / `.gemini` según el provider (`scaffold.ts:251-275`, ~40 callsites con `path.join(input.repoRoot, providerDir, ...)`).
+
+- **Mutación de `.gitignore` del usuario**: `ensureGitignore` añade un bloque `# specrails` con `.claude/agent-memory/` y `.specrails/` (y `.gemini/agent-memory/` en gemini) — `scaffold.ts:277-280, 1226-1242`.
+
+- **Mutación quirúrgica de archivos de instrucciones preexistentes**: para codex, `AGENTS.md` raíz por sentinel-block upsert; para gemini, `GEMINI.md` raíz por sentinel + `.gemini/settings.json` por `deepMergeJson`. Preservan contenido fuera del bloque gestionado, pero **escriben en un archivo que el usuario ya tenía** (`scaffold.ts:1038-1071, 723-757`). (Nota: para claude NO se escribe `CLAUDE.md` en el flujo de desktop; eso es tarea del pass de IA `/specrails:enrich`, que el desktop nunca ejecuta en tier quick.)
+
+- **Sobrescritura DESTRUCTIVA de archivos propios del usuario**: `placeQuickTierArtefacts()` escribe `sr-architect.md` / `sr-developer.md` / `sr-reviewer.md` con `writeFileLf` **sin guarda de existencia** (`scaffold.ts:951-956`). Si el usuario ya tenía un `.claude/agents/sr-architect.md` propio, **se clobberea**. El contrato `RESERVED_PATHS` solo protege dos prefijos (`.specrails/profiles/`, `.claude/agents/custom-`) — no protege los `sr-*`, ni el `CLAUDE.md`/`AGENTS.md`/`GEMINI.md` del usuario, ni `.mcp.json`, ni `openspec/`.
+
+- **Escritura delegada fuera del control de core**: `npx @fission-ai/openspec init --tools <provider> <repoRoot>` escribe `openspec/**` y dirs de comandos de provider (`.claude/commands/opsx`) en el repo, con su propia lógica (`init.ts:128, 202-218`).
+
+- **Borrados dentro del repo en cada run**: `pruneLegacyArtifacts()` hace `rmSync` recursivo de varias rutas repo-relativas en cada init (`scaffold.ts:784-814`).
+
+El dolor: ruido de git, riesgo de clobber de config propia del usuario, mutaciones de `.gitignore`/`AGENTS.md`/`GEMINI.md` que el usuario no pidió, y una violación del principio "el repo importado es del usuario, no nuestro". El único precedente sano ya existente es que gemini escribe su índice de acknowledgments **fuera del repo** en `~/.gemini/acknowledgments/agents.json` (`scaffold.ts:676-699`) — la prueba de concepto del patrón `$HOME`.
+
+---
+
+## 3. Inventario completo de artefactos
+
+| Grupo de artefacto | Dónde se escribe HOY | Quién lo escribe | ¿Committed o gitignored? | ¿Reubicable a `$HOME` y cómo? |
+|---|---|---|---|---|
+| `specrails-manifest.json` + `specrails-version` | `<repo>/.specrails/` | core | gitignored (`.specrails/`) | **Sí** vía nuevo `--workspace-dir`/`artifactRoot` en core. Nombres FROZEN (desktop los regex-matchea); solo cambia la ruta base. |
+| `setup-templates/**` (staging de templates) | `<repo>/.specrails/setup-templates/` | core | gitignored | **Sí**, requiere param base-dir en core + subdir por-proyecto (colisionaría entre proyectos si fuera `$HOME` plano). |
+| `install-config.yaml` | `<repo>/.specrails/` | TUI bin / desktop | gitignored | **Sí (moderado)**: core ya acepta `--from-config <path>`; desktop **ya** copia a `tmpdir` para el spawn (`setup-manager.ts:122,754`). El pin en `integration-contract.json` es nominal. |
+| `profiles/*.json` + `.user-preferred.json` | `<repo>/.specrails/profiles/` | desktop / usuario | **committed (team asset)** | **Sí pero**: app-owned, desktop controla todas las lecturas. Mover a `$HOME` **pierde la propiedad "committable team asset"** — decisión de producto, no solo de ruta. |
+| `plugins/state.json` + `snapshots/` | `<repo>/.specrails/plugins/` | desktop | gitignored | **Sí (moderado)**: app-owned; el snapshot `$HOME/.../jobs/<jobId>/plugins.json` ya existe. |
+| `file-summaries/<hash>.json` | `<repo>/.specrails/file-summaries/` | desktop | gitignored (línea auto-añadida) | **Sí (moderado)**: app-owned. Quita el append a `.gitignore` y la propiedad de team-share. |
+| `local-tickets.json` (spec store canónico) | `<repo>/.specrails/` | desktop (RW) + core (R) | gitignored | **BLOQUEADO sin cambio de core**: contrato de lectura congelado; core + cada persona de agente referencian la ruta repo-relativa; el contrato Jira "zero core changes" lo asume repo-relativo. |
+| `backlog-config.json` (switch read-only de Jira) | `<repo>/.specrails/` | desktop | gitignored | **BLOQUEADO**: core lo lee en ruta fija para entrar en su rama read-only. |
+| `.claude/{agents,commands,skills,rules}` + `agent-memory/` | `<repo>/.claude/` | core | parcialmente gitignored (`agent-memory/`) | **Sí vía CWD-relocation** (CLI auto-discover desde CWD). Bloqueado si CWD debe ser el repo. |
+| `.codex/{config.toml,skills}` + `AGENTS.md` raíz | `<repo>/.codex/`, `<repo>/AGENTS.md` | core | committed / git-noise | **Sí**: `CODEX_HOME` (ya usado per-project) cubre config.toml+MCP+skills+AGENTS.md global, **o** CWD-relocation. |
+| `.gemini/{settings.json,agents,commands}` + `GEMINI.md` raíz | `<repo>/.gemini/`, `<repo>/GEMINI.md` | core | committed / git-noise | **Sí**: CWD-relocation (project scope cwd-anchored), `GEMINI_SYSTEM_MD` para instrucciones, user-scope settings para MCP. |
+| `.mcp.json` (entradas MCP de plugins) | `<repo>/.mcp.json` | desktop (merge quirúrgico) | committed | **Sí (moderado)**: `--mcp-config <abs>` (mecanismo ya usado para `user-mcp.json`) **o** CWD-relocation. |
+| `custom-<plugin>.md` fragmentos | `<repo>/.claude/agents/` | desktop | committed | **Sí vía CWD-relocation** (misma constraint de discovery). |
+| `CLAUDE.md` raíz | NO escrito por desktop quick-tier (solo full-tier enrich) | core (full-tier) | committed | **Trivial**: nada lo escribe en el path de desktop; Explore ya lo evita vía explore-cwd. |
+| `agent-memory/` (explanations, failures) | `<repo>/.claude/agent-memory/` | core (runtime, prompt MD) | gitignored | **Sí pero requiere NUEVO soporte de core** (`SPECRAILS_STATE_DIR` en templates de prompt). |
+| `pipeline-state/`, `health-history/`, `compat-snapshots/`, `.dry-run/`, `backlog-cache.json` | `<repo>/.claude/...` | core (runtime, prompt MD) | gitignored | **Sí pero requiere NUEVO soporte de core** (mismo `SPECRAILS_STATE_DIR`). |
+| `openspec/changes/**` (entregable de spec) | `<repo>/openspec/` | `@fission-ai/openspec` (delegado) | **git-TRACKED (committed, el producto)** | **BLOQUEADO**: binario externo, working tree repo-relativo, entregable versionado por diseño. |
+| `.claude/worktrees/agent-<id>/` (git worktrees) | `<repo>/.claude/worktrees/` | Claude Code Task `isolation:worktree` | gitignored | **BLOQUEADO**: worktree real, debe compartir `.git`/object-store del repo para merge-back. |
+| `~/.gemini/acknowledgments/agents.json` | `$HOME/.gemini/` (ya global) | core | n/a (global) | **Trivial (ya global)**: merge-safe, keyed por `repoRoot`. Re-keying si `.gemini/agents` se mueve. |
+| `~/.specrails/doctor.log` | `$HOME/.specrails/` (ya global) | core (doctor) | n/a | **Trivial (ya global)**. |
+| `.gitignore` (bloque `# specrails`) | `<repo>/.gitignore` | core | n/a | **Trivial de eliminar**: si los artefactos salen del repo, `ensureGitignore` es un no-op. |
+
+**Precedente `$HOME` ya existente y amplio** (la base de la relocalización): desktop ya guarda `jobs.sqlite`, `jobs/<jobId>/{profile,plugins}.json`, telemetry, terminals shims, `explore-cwd`, `codex-home`, `browser-profile`, `attachments`, `user-mcp.json`, todo bajo `$HOME/.specrails/projects/<slug>/`. El snapshot `SPECRAILS_PROFILE_PATH` y `SPECRAILS_PLUGINS_*` ya apuntan a `$HOME`.
+
+---
+
+## 4. La restricción dura: cómo resuelven la config los CLIs
+
+Esta es la sección make-or-break. El hallazgo maestro, confirmado por la evidencia y los CLIs vivos: **ninguno de los tres CLIs permite apuntar agents/commands de project-scope a un directorio arbitrario SIN mover el CWD. No existe `--project-dir`.** De ahí se deriva todo.
+
+### 4.1 Claude
+
+- **Project scope (`.claude/settings.json`, `.claude/agents`, `.claude/commands`, `CLAUDE.md`, `.mcp.json`) está ESTRICTAMENTE anclado al CWD.** No hay flag/env para cargarlo desde un directorio no-CWD arbitrario (docs oficiales; feature-requests abiertas #25762 y #28808 piden exactamente esto, confirmando que no existe).
+- **`CLAUDE_CONFIG_DIR` reubica SOLO el user-scope `~/.claude` (global a todos los proyectos), NO el `.claude` por-proyecto.**
+- **Escape hatches por-invocación (sin archivo en el repo):** `--settings <file-or-json>` (ruta arbitraria), `--mcp-config <files...>` (+ `--strict-mcp-config` para ignorar el `.mcp.json` del repo), `--agents <json>` (agentes inline), `--add-dir`, `--system-prompt`/`--append-system-prompt`, `--plugin-dir`/`--plugin-url`.
+- **`--setting-sources` es enum-only `{user, project, local}`** — selecciona qué scopes cargar, no dónde viven.
+- **PARED dura (solo si CWD debe ser el repo):** no hay forma de cargar agents/commands/settings/`CLAUDE.md` de project-scope desde un directorio arbitrario manteniendo CWD en el repo. **`--add-dir` está documentado como "(CLAUDE.md dirs)"** — carga `CLAUDE.md`/memory desde un dir añadido pero **NO registra los subagentes `sr-*` de project-scope** que el snapshot de profile referencia. Esta es la falla fatal de la inyección de framework en rails de la Opción 3. Tampoco hay `--commands-dir`: los `/specrails:*` requieren `--plugin-dir` o `CLAUDE_CONFIG_DIR/commands`.
+- **Esta pared se DISUELVE en el momento en que el CWD se reubica** a un dir `$HOME`: entonces `.claude/agents`, `.claude/commands`, `CLAUDE.md`, `.mcp.json` cargan nativamente desde ese CWD, sin flags.
+
+### 4.2 Codex
+
+- **`AGENTS.md` se resuelve en DOS scopes:** project (walk de git-root→cwd) Y global `CODEX_HOME/AGENTS.md` (con precedencia `AGENTS.override.md`). Un `AGENTS.md` no-repo está nativamente soportado vía `CODEX_HOME` — **sin truco de CWD para las instrucciones**.
+- **`CODEX_HOME` reubica `config.toml` (model/sandbox/approval), definiciones MCP, auth Y skills/custom-prompts a un dir por-proyecto.** Desktop ya usa `CODEX_HOME` por-proyecto para MCP.
+- **Project config (`.codex/config.toml`, `.codex/skills`) se descubre caminando desde el CWD hasta el project root** (marker por defecto `.git`); `project_root_markers` (settable a `[]`) controla esto.
+- **PARED suave:** no hay env/flag para apuntar `AGENTS.md` a un FILE arbitrario más allá de project `.codex`, `CODEX_HOME` o `project_doc_fallback_filenames`. Pero `CODEX_HOME` cubre el caso completo. `-c key=value` override per-invocación, `-p profile`, `--ignore-user-config`, `-C/--cd`.
+- **Riesgo de re-discovery:** con CWD=repo, codex **camina git-root→cwd buscando `AGENTS.md` y NO hay flag para deshabilitar ese walk** (confirmado ausente en codex 0.139.0 `--help`). Un `AGENTS.md` preexistente del usuario se concatena aditivamente. Solo "limpio" para repos vírgenes. Con CWD-relocation fuera del repo, el walk no encuentra nada del repo.
+
+### 4.3 Gemini
+
+- **`settings.json` carga de system, user (`~/.gemini/settings.json`) y project (`.gemini/settings.json` en CWD).** Project scope estrictamente cwd-anchored. `mcpServers` viven en `settings.json` en cualquier scope — un CWD `$HOME` o user-scope settings proveen MCP sin archivo en el repo.
+- **`GEMINI_SYSTEM_MD` reemplaza el system prompt built-in con un archivo en ruta arbitraria** (abs/rel, `~` expandido) — escape hatch de instrucciones totalmente no-repo, independiente del discovery de `GEMINI.md`.
+- **`GEMINI_CLI_HOME` reubica el dir user-level (`~/.gemini`, global). NINGÚN env reubica el `.gemini` de PROJECT** a ruta arbitraria — debe estar en CWD. `XDG_CONFIG_HOME` no se honra.
+- **El walk de `GEMINI.md` para en el TRUSTED ROOT (frontera del workspace), no en git-root.** Un CWD `$HOME` que no sea ancestro del repo no re-descubre un `GEMINI.md` repo-side. `GEMINI_CLI_TRUST_WORKSPACE=true` (ya inyectado hoy) ancla el trusted root al workspace.
+- **`--include-directories` + `context.loadMemoryFromIncludeDirectories=true`** carga sus `GEMINI.md`. `--policy`/`--admin-policy` cargan policy de rutas arbitrarias.
+- **PARED suave:** project commands/agents son cwd-bound; necesitan CWD-relocation para salir del repo. MCP, instrucciones y policy tienen hatches no-CWD.
+
+### 4.4 Síntesis de la restricción
+
+| Tipo de artefacto | claude | codex | gemini |
+|---|---|---|---|
+| Instrucciones (`CLAUDE/AGENTS/GEMINI.md`) | `--append-system-prompt` / CWD | `CODEX_HOME/AGENTS.md` / CWD | `GEMINI_SYSTEM_MD` / CWD |
+| MCP (`.mcp.json` / settings) | `--mcp-config` + `--strict-mcp-config` / CWD | `CODEX_HOME` config.toml | user-scope settings / CWD |
+| Settings | `--settings` / CWD | `-c` + `CODEX_HOME` / CWD | `GEMINI_CLI_HOME` (user) / CWD (project) |
+| **Agents (project-scope)** | **solo CWD** (o `--agents` inline) | **solo CWD/`CODEX_HOME`** (sin file flag) | **solo CWD** (sin env por-project) |
+| **Commands (project-scope)** | **solo CWD** (o `--plugin-dir`; **NO hay `--commands-dir`**) | `CODEX_HOME/skills` / CWD | **solo CWD** |
+
+**La conclusión que decide la arquitectura:** las paredes duras (agents/commands de project-scope) **solo existen si se insiste en mantener CWD=repo**. **Todas se disuelven con CWD-relocation** — el único mecanismo universal a los tres CLIs, ya probado en `explore-cwd-manager.ts`.
+
+---
+
+## 5. Opciones de arquitectura
+
+### Opción 1 — Workspace gestionado por la app (generalizar explore-cwd)
+
+CWD = `$HOME/.specrails/projects/<slug>/workspace/` para **todos** los spawns (excepto terminales). El workspace contiene TODOS los artefactos (`.claude/.codex/.gemini`, instrucciones, `.mcp.json`, `.specrails/`); el repo se alcanza vía symlink `./project`. Core gana un único `--workspace-dir`/`SPECRAILS_WORKSPACE_DIR` que separa `artifactRoot` de `codeRoot` (default unset ⇒ `artifactRoot=codeRoot`, legacy byte-idéntico). Runtime state vía nuevo `SPECRAILS_STATE_DIR`; worktrees repo-bound vía nuevo `SPECRAILS_REPO_DIR`.
+
+- **Trade-offs:** inmunidad a colisiones **estructural** (no per-flag); claude carga agents/commands/`CLAUDE.md`/`.mcp.json` nativamente sin flags frágiles. **Coste:** XL, el grueso en core (~40 callsites de scaffold + 7+ templates de prompt); rails corren CWD=workspace (no el repo), así que toda ruta relativa de edición/git/openspec debe re-apuntar al repo real vía `SPECRAILS_REPO_DIR`/symlink — riesgo de corrección amplio. Requiere release lockstep de dos repos + core-version gate.
+- **Scores del panel:** Feasibilidad CLI **8** (top pick), Goal-fit/UX **8** (top pick), Blast-radius/contratos **4**.
+
+### Opción 2 — Globales `$HOME` reales + inyección por-invocación (CWD=repo)
+
+Los artefactos viven en dirs `$HOME` reales por-proyecto; los spawns mantienen CWD=repo y alcanzan la config solo vía env vars + flags. claude: `CLAUDE_CONFIG_DIR` + `--setting-sources user` + `--strict-mcp-config` + `--mcp-config` + `--agents`/`--plugin-dir` + `--append-system-prompt`. codex: `CODEX_HOME`. gemini: `GEMINI_CLI_HOME` + `GEMINI_SYSTEM_MD` + `--include-directories`.
+
+- **Trade-offs:** CWD=repo resuelve git/rutas relativas nativamente (única ventaja). **Pero** se sitúa exactamente en la configuración que la evidencia marca con MÁS paredes duras. codex/gemini project skills/agents **no tienen loader no-CWD** ⇒ "user-scope enmascarando project-scope". codex concatena aditivamente cualquier `AGENTS.md` preexistente del usuario (**sin flag para deshabilitar el walk**). claude no tiene `--commands-dir` ⇒ `/specrails:*` requieren ensamblaje `--plugin-dir` por-proyecto (maquinaria nueva no verificada). Además relocaliza `local-tickets.json`, el read-cache FROZEN de core (contrato Jira "zero core changes") — **el peor riesgo de contrato** para un resultado aún PARCIAL.
+- **Scores del panel:** Feasibilidad CLI **4**, Goal-fit/UX **4**, Blast-radius/contratos **3** (el peor en las tres lentes).
+
+### Opción 3 — Híbrido Pragmático (CWD-relocation para lectura, `--add-dir` para rails, gitignore el residuo)
+
+Flujos de lectura/interactivos (Explore, quick-spec, contract-refine, sidebar chat, agent-refine, terminal "Open AI CLI") → CWD-relocation a `$HOME/.../cli-cwd/` (reusando/generalizando `ensureExploreCwd`): **cero archivos en el repo, hoy mismo**. Rail/implement → CWD=repo (inevitable), inyectando framework vía `--add-dir`/`--include-directories`/`CODEX_HOME` + `--strict-mcp-config`, y dejando el residuo irreductible (openspec/changes, worktrees, runtime state) **git-limpio** (ya está en el bloque gitignore de core).
+
+- **Trade-offs:** **menor blast radius** (Medium, ~70% desktop, core OPCIONAL/cero); **cero contratos congelados tocados**; reusa el patrón explore-cwd ya en producción. **Pero** el rail-path es el punto débil honesto: `--add-dir` está documentado como "(CLAUDE.md dirs)" y **puede NO registrar los subagentes `sr-*`** ⇒ fallback a `--agents` inline regenerado por-spawn, con riesgo de drift respecto al snapshot de profile. No alcanza "cero archivos" para proyectos que corren rails (solo git-limpio).
+- **Scores del panel:** Feasibilidad CLI **5**, Goal-fit/UX **6**, Blast-radius/contratos **8** (top pick).
+
+---
+
+## 6. Recomendación
+
+**Adoptar la Opción 1 (workspace) como modelo de destino, implementada por fases empezando con el alcance de la Opción 3 para los flujos de lectura.** Esto es un **graft** deliberado:
+
+1. **Fase A (alcance Opción 3, solo desktop, cero cambios de core, cero contratos en riesgo):** generalizar `explore-cwd-manager.ts` en un `CliCwdManager` compartido y enrutar **todos los flujos de lectura/interactivos** (Explore, quick-spec, contract-refine, agent-refine, sidebar chat, terminal "Open AI CLI") a CWD = `$HOME/.../cli-cwd/`. Para estos flujos, el objetivo "cero archivos en el repo" **se cumple por completo, hoy**, con la inmunidad-a-colisiones estructural de la Opción 1. Repointar los sitios app-owned (`ticket-store`, `profile-manager`, `plugins/paths`, `file-summary`, `jira-backlog-config`, `context-scope`) a `$HOME` donde sea seguro.
+
+2. **Fase B (alcance Opción 1, cambio de core, release lockstep):** introducir `--workspace-dir`/`SPECRAILS_WORKSPACE_DIR` + `SPECRAILS_STATE_DIR` + `SPECRAILS_REPO_DIR` en core, y mover **el flujo de rails** al workspace, con worktrees/openspec como las excepciones repo-bound documentadas. Gate por core-version (espejo del gate `>= 4.1.0` de profiles).
+
+**Por qué este graft y no Opción 2/3 puras:** las dos lentes que importan para "que funcione de verdad" (feasibilidad CLI y goal-fit) eligen la Opción 1 porque es la única que descansa **exclusivamente** en CWD-relocation — el único mecanismo universal y no-mágico. La Opción 2 muere en las paredes duras (codex sin loader no-CWD + leak de `AGENTS.md` no suprimible + relocación de `local-tickets.json` que toca un contrato congelado). La Opción 3 hereda la inmunidad de la Opción 1 en lectura pero su rail-path descansa en `--add-dir`, que `claude --help` documenta como "(CLAUDE.md dirs)" — **no registra subagentes de project-scope**. El graft captura lo mejor de ambas: la Opción 3 entrega valor real e inmediato con riesgo mínimo, y la Opción 1 completa el objetivo donde más importa (rails) con la garantía arquitectónica.
+
+### Layout de destino bajo `$HOME`
+
+```
+~/.specrails/projects/<slug>/
+  workspace/                              # CWD universal (generaliza explore-cwd) — Fase B
+    CLAUDE.md | AGENTS.md | GEMINI.md     # instrucciones app/core-owned (por provider)
+    .mcp.json                             # entradas MCP de plugins (+ opcional project MCP)
+    .claude/{agents,commands,skills,rules,agent-memory}/
+    .codex/{config.toml,skills}/          # codex (también cubierto por CODEX_HOME)
+    .gemini/{settings.json,agents,commands,agent-memory}/
+    .specrails/
+      specrails-manifest.json  specrails-version   # nombres FROZEN, ahora aquí
+      install-config.yaml
+      setup-templates/{agents,commands,skills,rules,personas,claude-md,settings}/
+      profiles/*.json  .user-preferred.json        # app-owned (pierde "committable")
+      plugins/{state.json,snapshots/}
+      file-summaries/<hash>.json
+      local-tickets.json                            # read-cache de specs (vía core env pointer)
+      backlog-config.json                           # switch read-only de Jira
+    pipeline-state/ health-history/ compat-snapshots/ dry-run/ agent-memory/ backlog-cache.json
+      # ^ runtime state, redirigido vía SPECRAILS_STATE_DIR (nuevo env de core)
+    project -> <project.path>             # symlink/junction (project-path.txt fallback)
+  cli-cwd/                                # CWD para flujos de lectura — Fase A (ya existe como explore-cwd)
+  jobs.sqlite  codex-home/  telemetry/  terminals/  user-mcp.json  attachments/  ...   # ya en $HOME
+```
+
+Lo único que permanece en el repo: `workspace/project` (symlink), `openspec/changes/` (entregable versionado, intencional) y los worktrees git-bound (gitignored).
+
+### Receta de spawn por provider (Fase B, CWD = workspace)
+
+- **claude** (rails, chat, agent-refine, quick-spec, contract-refine): `cwd=<workspace>`. Auto-descubre `.claude/{agents,commands,skills}`, `CLAUDE.md`, `.mcp.json` desde el CWD — **sin flags nuevos en el happy path**. `--add-dir <workspace>/project` para que las tools alcancen archivos del repo por ruta absoluta. `--mcp-config <$HOME user-mcp.json>` para user-MCP sin cambios. `--setting-sources project,local` para aislar de globales del usuario.
+- **codex**: `cwd=<workspace>` + mantener `CODEX_HOME=$HOME/.specrails/projects/<slug>/codex-home`. `-c project_root_markers=[]` (defensivo) para que trate el workspace como root y no camine ancestros. `AGENTS.md` en `<workspace>/AGENTS.md` o `CODEX_HOME/AGENTS.md`.
+- **gemini**: `cwd=<workspace>`. Project `.gemini/{settings.json,agents,commands}` + `GEMINI.md` cwd-discovered. `GEMINI_CLI_TRUST_WORKSPACE=true` (ya inyectado) ancla el trusted root al workspace ⇒ ningún `GEMINI.md` repo-side se re-descubre. Opcional `GEMINI_SYSTEM_MD=<workspace>/GEMINI.md`. Re-keying del writer `~/.gemini/acknowledgments/agents.json` de `project.path` al workspace, hasheando `<workspace>/.gemini/agents/*.md`.
+
+Para los tres, el env `$HOME` ya existente (`SPECRAILS_PROFILE_PATH`, `SPECRAILS_PLUGINS_*`, `OTEL_*`/`CLAUDE_CODE_ENABLE_TELEMETRY`) no cambia. **Terminales mantienen `cwd=project.path`** — el usuario espera una shell en su repo real. **Git provenance mantiene `cwd=project.path`** — git es repo-bound.
+
+---
+
+## 7. Plan de migración
+
+### Proyectos ya importados
+
+Migración **no-destructiva por diseño** (honra "no modificar el repo"): al cargar el registry (o en el primer job tras el upgrade), `migrateProjectArtifactsToHome(slug)`:
+
+1. Detecta `.specrails/`, `.claude/`, `.codex/`, `.gemini/`, `AGENTS.md`/`GEMINI.md`/`CLAUDE.md` raíz, `.mcp.json` repo-residentes.
+2. **Copia (no mueve — deja el repo intacto)** el subconjunto app-owned al nuevo `cli-cwd`/`workspace`: `local-tickets.json`, `profiles/`, `plugins/state.json`, `file-summaries/`, `install-config.yaml`, los `sr-*` agents/commands.
+3. Para el workspace (Fase B), re-ejecuta `npx specrails-core init --root-dir <project.path> --workspace-dir <workspace>` para regenerar artefactos canónicos en `$HOME`.
+4. Setea un flag en `desktop-db` para que las lecturas siguientes usen `$HOME`.
+5. Los archivos repo-residentes de instalaciones previas se **dejan en disco** (no se borran automáticamente) e inertes; se ofrece una affordance manual "limpiar archivos antiguos de Specrails" — que el usuario ejecuta explícitamente (eso sí modifica el repo, nunca automático).
+
+### Cambios en `init`/`update` de core
+
+- **Fase A:** **cero cambios de core.** Desktop ya pasa `--from-config <abs tmpdir path>` (`setup-manager.ts:754`), así que el pin `configSchema.file` es nominal. Se ejecuta `init` con `cwd` = el dir staging `$HOME` (no `project.path`).
+- **Fase B:** nuevo `--workspace-dir`/`SPECRAILS_WORKSPACE_DIR` que resuelve `artifactRoot = workspaceDir ?? repoRoot`. Threading de `artifactRoot` a través de ~40 callsites de `scaffold.ts`. `ensureGitignore()` y `pruneLegacyArtifacts()` operan sobre `artifactRoot` (no-op/seguro cuando `artifactRoot !== codeRoot`). Delegado openspec recibe el workspace como target (verificar PoC). Runtime: `SPECRAILS_STATE_DIR` honrado por `implement.md`/`retry.md`/`health-check.md`/`compat-check.md`/`sr-*.md`/`why.md`/`memory-inspect.md` (default unset ⇒ `.claude/...`, legacy). Worktrees repo-bound vía `SPECRAILS_REPO_DIR`. Sentinels `init complete`/`update complete` y nombres de manifest **byte-estables**.
+
+### Backward-compat y kill-switch / rollback
+
+- **Default unset ⇒ legacy byte-idéntico:** todo `npx specrails-core init` standalone (no-desktop) se comporta exactamente igual; `--workspace-dir` solo lo pasa desktop.
+- **Core-version gate** (espejo del `>= 4.1.0` de profiles): un desktop nuevo contra un core viejo (sin `--workspace-dir`) **caería de vuelta al comportamiento in-repo** en lugar de mis-targetear silenciosamente. **Este gate es load-bearing** — sin él, un desktop nuevo + core viejo vuelca artefactos en el repo.
+- **Rollback:** desactivar el flag de workspace por-proyecto en `desktop-db` revierte a CWD=repo. Los archivos `$HOME` permanecen (limpiables manualmente). Ningún dato se pierde.
+
+---
+
+## 8. Esfuerzo e impacto por repo
+
+### specrails-core
+
+- **Fase A:** **cero cambios.**
+- **Fase B (esfuerzo: el grueso, XL del total):**
+  - `init.ts`/`update.ts`/`doctor.ts`: nuevo flag `--workspace-dir` + env, resolver `artifactRoot`.
+  - `scaffold.ts`: split de `artifactRoot`/`codeRoot` en ~40 callsites de `path.join(input.repoRoot, providerDir, ...)`. **Mecánico pero debe ser exhaustivo** — un solo literal `.claude/...` perdido aterriza en el repo y viola el requisito en silencio.
+  - `ensureGitignore()` no-op cuando `artifactRoot !== codeRoot`; `pruneLegacyArtifacts()` sobre `artifactRoot`.
+  - Templates de prompt runtime: `SPECRAILS_STATE_DIR` en ~7-8 archivos MD, default `.claude/...`.
+  - Worktrees: `SPECRAILS_REPO_DIR` para ops git/worktree distintas del CWD.
+  - `integration-contract.json`: bump de `schemaVersion`; documentar el contrato workspace-dir.
+
+### specrails-desktop
+
+- **Fase A (esfuerzo: Medium, ~70% del trabajo de Fase A):**
+  - Generalizar `explore-cwd-manager.ts` → `CliCwdManager` compartido (reusar symlink + `project-path.txt` fallback + cleanup que ya existen).
+  - Repointar `chat-manager`, `contract-refine-runner`, `agent-refine-manager`, `project-router-tickets` (quick-spec, ai-edit) a `cli-cwd`.
+  - `setup-manager`: ejecutar `init` con `cwd` = dir staging `$HOME`.
+  - Repointar `ticket-store.resolveTicketStoragePath`, `profile-manager.profilesDir`, `plugins/paths.*`, `file-summary-manager.SUMMARIES_REL`, `jira-backlog-config`, `context-scope` readers a `$HOME`.
+  - Re-keying de `gemini-agent-ack`.
+- **Fase B (esfuerzo: Medium-Large):**
+  - `queue-manager`: cambiar rail-job `cwd` a workspace; inyectar `SPECRAILS_STATE_DIR=<workspace>` + `SPECRAILS_REPO_DIR=<project.path>`. Provenance mantiene `cwd=project.path`.
+  - `terminal-manager`: **mantener `cwd=project.path`** (intencional).
+  - Migración + core-version gate.
+
+### Riesgos para contratos congelados
+
+| Contrato congelado | ¿En riesgo? | Notas |
+|---|---|---|
+| Mobile wire (`specrailshub`, `hub.*`, `hubInstanceId`, `hub_daily_budget_exceeded`) | **No** | Strings de identidad/wire, ortogonales a ubicación de archivos. |
+| Bundle id `sh.specrails.hub` | **No** | Identidad de app-data/updater; sin relación con repo-vs-HOME. |
+| core↔desktop schema identity (`$id`) | **No** | `profile.v1.json` de desktop ya es derivativo con su propio `$id` (línea 3). Mover profiles a `$HOME` no cambia el `$id`. |
+| `RESERVED_PATHS` (`.specrails/profiles/`, `.claude/agents/custom-`) | **No** (semántica), **Sí** producto | Semántica preservada relativa a `artifactRoot`. Mover profiles a `$HOME` pierde "committable team asset" — decisión de producto. |
+| Sentinels `init complete`/`update complete` | **No** (si byte-estables) | Deben permanecer byte-idénticos; solo cambia su ruta base. |
+| `integration-contract.json` `configSchema.file='.specrails/install-config.yaml'` | **Bajo** | Pin nominal; desktop ya pasa `--from-config <abs>`. Fase B puede bumpear `schemaVersion`. |
+| Coverage gates (80% server, 80% client, 70% global) | **No** (alcanzables) | Path funcs puras + symlink manager + DB reads en el harness `:memory:` existente son altamente testeables. Requiere volumen de tests nuevo, no bajar thresholds. |
+
+---
+
+## 9. Riesgos y preguntas abiertas
+
+1. **[SPIKE OBLIGATORIO ANTES DE FASE B] ¿`--add-dir` registra subagentes de project-scope?** `claude --help` documenta `--add-dir` como "(CLAUDE.md dirs)". Si la Opción 1 funciona (CWD=workspace, los agents viven en `<workspace>/.claude/agents` y cargan nativamente desde el CWD) esto **no es problema para la Fase B**. Pero **es la falla fatal de cualquier rail-path con CWD=repo** (Opción 3 pura). Validar que con CWD=workspace los `sr-*` se registran nativamente — es la suposición load-bearing de la recomendación.
+
+2. **[SPIKE OBLIGATORIO] ¿`@fission-ai/openspec init` acepta un target out-of-repo / sin `.git`?** Si lo exige, `openspec/changes/` debe quedar como la **única** excepción repo-residente y "cero archivos" es PARCIAL para rails. Probar: init de openspec contra el workspace sin `.git`; si falla, evaluar inicializar un `.git` throwaway en el workspace o aceptar openspec como excepción documentada.
+
+3. **[SPIKE] Worktrees repo-bound desde CWD=workspace.** Los worktrees deben compartir el `.git`/object-store del repo y mergear de vuelta. Validar que `SPECRAILS_REPO_DIR` + `git -C <repo>` worktree-add funcionan cuando el CWD del proceso es el workspace. Un error aquí **corrompe o falla merges de multi-feature rails silenciosamente**.
+
+4. **Exhaustividad de los ~40 callsites de scaffold + ~8 templates de prompt.** Un solo literal `.claude/...`/`path.join(repoRoot,...)` perdido aterriza en el repo sin error. Mitigación: test que asserta el working tree del repo **byte-inalterado** tras un ciclo completo setup+job.
+
+5. **codex/gemini ancestor-walk re-discovery.** Si el workspace se coloca dentro del repo (o el symlink se sigue durante discovery), un `AGENTS.md`/`GEMINI.md` repo-side se filtra. Mitigación: workspace estrictamente fuera del repo + `project_root_markers=[]`/`TRUST_WORKSPACE`. Verificar por versión de CLI.
+
+6. **Disciplina de rutas en rails (CWD=workspace).** Toda ruta relativa que deba resolver en el REPO debe ir por `SPECRAILS_REPO_DIR`/symlink. Si una tool resuelve relativa al CWD, escribe en el workspace por error. Mitigación: `--add-dir <workspace>/project` + disciplina auditada en prompts.
+
+7. **Profiles/file-summaries pierden "committable team asset".** Regresión de producto, no solo de ruta. Posible affordance opt-in "exportar profiles al repo" / "commit profiles".
+
+8. **`--strict-mcp-config` en rails** deshabilita el `.mcp.json` committed del repo — puede romper a un usuario que dependa legítimamente de un MCP server repo-committed fuera del sistema de plugins. Necesita escape hatch por-proyecto.
+
+9. **GAP ortogonal (no causado por esta migración, pero a corregir/flag en la rework de spawn-env):** `gemini-adapter` declara `nativeOtelEnv:true` pero `buildTelemetryEnv` no emite vars `GEMINI_TELEMETRY_*`; si gemini honra los `OTEL_*` genéricos está sin verificar.
+
+10. **Release lockstep de dos repos.** Un desktop con `--workspace-dir` contra un core sin el flag vuelca artefactos en el repo. El core-version gate es load-bearing.
+
+---
+
+## 10. Veredicto final
+
+**GO-WITH-CAVEATS.**
+
+- **Para flujos de lectura/interactivos (Explore, quick-spec, contract-refine, chat, ai-edit): GO inmediato.** Fase A es solo-desktop, cero cambios de core, cero contratos congelados en riesgo, y reusa el patrón explore-cwd ya en producción. El objetivo literal "cero archivos en el repo" **se cumple por completo** para estos flujos. Entrega valor real con riesgo mínimo.
+
+- **Para el flujo de rails/implement: GO con la advertencia honesta de que el techo es "repo git-limpio", no "repo file-limpio".** `openspec/changes/` (entregable versionado intencional) y los git worktrees (deben compartir el `.git` del repo) son **irreductiblemente repo-bound en las tres opciones** — ningún flag de ningún CLI los reubica. Todo lo demás (framework dirs, instrucciones, `.mcp.json`, manifest, version, profiles, plugins, file-summaries, runtime state) se mueve limpiamente al workspace dado el flag de core + `SPECRAILS_STATE_DIR`.
+
+- **NO-GO para la Opción 2 (globales `$HOME` con CWD=repo):** es la peor en las tres lentes del panel; choca con paredes duras no suprimibles (codex sin loader no-CWD, leak de `AGENTS.md`, sin `--commands-dir`) y pone en riesgo el contrato congelado `local-tickets.json` para un resultado aún parcial.
+
+### Lo más importante a validar PRIMERO
+
+**Un PoC que confirme la doble suposición load-bearing de la Fase B antes de comprometer el cambio de core:**
+
+> Con CWD = un workspace `$HOME` fuera del repo, conteniendo `<workspace>/.claude/agents/sr-*.md` + `.mcp.json` + `CLAUDE.md`, y el repo en `<workspace>/project` (symlink): **(a)** ¿claude **registra y ejecuta** los subagentes `sr-*` de project-scope nativamente desde el CWD?, y **(b)** ¿el agente developer puede **editar source, correr tests y manejar git** en el repo real vía `--add-dir <workspace>/project` / `SPECRAILS_REPO_DIR` sin que ninguna tool escriba por error en el workspace?
+
+Si (a) y (b) pasan, la Opción 1 es sólida y el resto es ingeniería exhaustiva. Si (a) falla (claude no registra agents desde el CWD del workspace cuando hay un symlink de por medio, o el discovery se confunde), la arquitectura de rails necesita repensarse antes de tocar core — y ese es exactamente el riesgo que hunde la inyección por-flag de las otras opciones.

package/docs/internals/operations-runbook.md

@@ -14,7 +14,7 @@ specrails-desktop start
 specrails-desktop --port 5000 start
 ```
 
-`start` writes the server PID to `~/.specrails/manager.pid` and appends the server's stdout/stderr to `~/.specrails/desktop.log`. The default port is `4200`.
+`start` daemonizes the server, which then writes its own PID to `~/.specrails/manager.pid` and appends its stdout/stderr to `~/.specrails/desktop.log`. The default port is `4200`.
 
 ## Stopping the app
 
@@ -35,14 +35,16 @@ specrails-desktop status
 # Same, against a custom port
 specrails-desktop --port 5000 status
 
-# One-line manager status (also usable as a script-friendly probe)
+# Terser manager status (script-friendly probe)
 specrails-desktop --status
 ```
 
-`status` prints `server: running (pid <n>) on http://127.0.0.1:<port>`, the project count, and each project name. It exits non-zero when the app is not running.
+The two forms print different output. The `status` **subcommand** prints `server: running (pid <n>) on http://127.0.0.1:<port>`, the project count, and each project name. The `--status` **flag** prints a shorter `manager: running (v<version>)` / `mode: super` / `projects: <count>` block (no PID, no project names) — handy as a scripted up/down probe. Both exit non-zero when the app is not running.
 
 > `specrails-desktop --jobs` is **not** functional against the running server — the server does not expose a cross-project `/api/jobs` route, so the command prints a message that jobs history requires a manager with SQLite persistence and exits `1`. Browse job history per project in the app's **Jobs** page instead.
 
+> **Offline CLI fallback.** When you run a command and no manager is up, the CLI prints `manager not running — invoking claude directly` and spawns a local `claude` process to handle it. This fallback **always uses `claude`** — it never spawns `codex` or `gemini`, regardless of a project's primary provider — and it writes **nothing** to Analytics (no `ai_invocations` row; cost/tokens are only echoed to your terminal). Start the manager (`specrails-desktop start`) to route through your project's real provider and capture the run.
+
 ## App data location
 
 All app data lives under `~/.specrails/` (the path is hardcoded to your home directory — there is no override env var):
@@ -60,7 +62,7 @@ All app data lives under `~/.specrails/` (the path is hardcoded to your home dir
 
 See [Configuration](configuration.md#specrails-directory-structure) for the complete per-project subtree (telemetry blobs, explore-cwd, terminals, attachments, etc.) and how the `<slug>` is derived.
 
-> **Auth token caveat.** `~/.specrails/desktop.token` gates every `/api/*` request and WebSocket upgrade. Deleting it (or doing a full `rm -rf ~/.specrails`) regenerates a fresh token on the next start, which can leave an already-open browser tab or CLI on the old token — reload the app after a token reset. See [Configuration → Authentication](configuration.md#authentication).
+> **Auth token caveat.** `~/.specrails/desktop.token` gates every `/api/*` request and WebSocket upgrade, except the two public bootstrap routes (`GET /api/health` and `GET /api/token`) that `requireAuth` is mounted after, so the local client can fetch its token. Deleting the token file (or doing a full `rm -rf ~/.specrails`) regenerates a fresh token on the next start, which can leave an already-open browser tab or CLI on the old token — reload the app after a token reset. See [Configuration → Authentication](configuration.md#authentication).
 
 ## Log files
 
@@ -121,7 +123,7 @@ specrails-desktop start
 # Back up first, then reset
 cp ~/.specrails/desktop.sqlite ~/.specrails/desktop.sqlite.bak
 specrails-desktop stop
-rm -f ~/.specrails/desktop.sqlite*   # the glob also clears the WAL/SHM sidecars
+rm -f ~/.specrails/desktop.sqlite*   # the * also removes the write-ahead-log sidecar files (desktop.sqlite-wal, desktop.sqlite-shm)
 specrails-desktop start              # re-creates an empty registry
 
 # Re-register each project
@@ -129,6 +131,15 @@ specrails-desktop add /path/to/project-a
 specrails-desktop add /path/to/project-b
 ```
 
+### Disable a misbehaving provider or feature (recovery levers)
+
+If a single provider or feature is breaking the app, you can turn it off with an environment variable and restart — no reinstall, no data loss. Set the var in the environment the server starts in, then `specrails-desktop stop && specrails-desktop start`.
+
+- **Disable a provider** (it disappears from Add Project / engine pickers): `SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0`. Both are enabled by default and only the **exact string `0`** disables them (`1` / `true` / unset all keep the provider on).
+- **Disable a spec-enrichment feature**: `SPECRAILS_EXPLORE_CONTRACT_REFINE` (Contract Refine) and `SPECRAILS_SMASH` (SMASH) are kill switches that turn off on `0`, `false`, or `off`.
+
+These are the most common ops escape hatches; see [Configuration → Environment variables](configuration.md#environment-variables) for the complete list of gates and flags.
+
 ### Per-project reset (keeps the registration)
 
 To clear one project's job history, invocations, and telemetry pointers while keeping it registered, delete just that project's `jobs.sqlite` with the app stopped:

package/docs/internals/profiles.md

@@ -19,7 +19,8 @@ From any project, click **Agents** in the right sidebar (next to
 Dashboard/Jobs/Analytics/Settings).
 
 - **Profiles** tab — create and edit profiles.
-- **Usage** tab — see which profiles are actually being used.
+- **Usage** tab — see which profiles are actually being used (backed by
+  the `/analytics` endpoint covered in section 8).
 - **Catalog** tab — read the upstream `sr-*` agents or author custom
   `custom-*` ones via the Studio.
 
@@ -30,7 +31,13 @@ points:
   `.claude/agents/` frontmatter models and creates a `default` profile
   mirroring today's behavior (zero-loss). It requires the baseline trio
   `sr-architect`, `sr-developer`, and `sr-reviewer` to be present — the
-  server rejects the migration if any is missing.
+  server rejects the migration if any is missing. On a project whose
+  primary provider is **not** Claude (Codex or Gemini), the frontmatter
+  model aliases aren't in that provider's catalog, so the migration stamps
+  the project's `provider` onto the profile and substitutes that provider's
+  default model — the resulting `default` profile still validates and is
+  ready to edit (though it only takes effect on Claude rails — see
+  [Multi-provider rails](#multi-provider-rails-claude-codex-and-gemini)).
 - **Blank profile** — start from scratch.
 
 ## 2. Saved profiles vs selection
@@ -64,13 +71,28 @@ wizard. Each rail header has a compact profile dropdown
 The "No profile" option is always available — use it to run a
 rail exactly as it did pre-4.1.0.
 
-### Codex / multi-provider
+### Multi-provider rails (Claude, Codex, and Gemini)
 
-Agent profiles are a **Claude-only** feature. When a rail's AI engine is
-Codex, the app force-nulls the profile and runs the rail in legacy mode —
-Codex has no agent-profile concept. The profile selector is hidden for
-Codex rails, so a profile picked on one engine never silently applies to
-the other.
+**Profiles apply only to Claude rails.** specrails-desktop supports three
+interchangeable AI providers — Claude, Codex, and Gemini — but agent
+profiles are a Claude-only concept (Codex and Gemini have no equivalent).
+
+When a rail's AI engine is **anything other than Claude** (Codex or
+Gemini), the app force-nulls the profile and runs the rail in legacy mode.
+The rails router enforces this server-side for *any* non-Claude engine, so
+no profile env var is ever injected on a Codex or Gemini rail regardless of
+what the UI shows.
+
+> **Known UI limitation.** The client currently only hides the profile
+> selector for **Codex** rails. On a **Gemini** rail the selector can still
+> appear — but the server ignores any profile you pick there (it always
+> falls back to legacy mode). Picking a profile on a Gemini rail therefore
+> has no effect; treat it as a no-op until the selector is hidden for all
+> non-Claude engines.
+
+Provider availability itself is gated separately (both default-enabled): set
+`SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0` to disable a provider
+app-wide. See [../codex.md](../codex.md) and [../gemini.md](../gemini.md).
 
 ## 4. Author a custom agent (Agent Studio)
 
@@ -96,15 +118,17 @@ see output, token count, and duration inline.
 
 - A **profile badge** (themed with the `accent-primary` color) appears on
   each job row showing which profile it ran under.
-- The **Usage** tab shows usage per profile for the last 7/30/90 days:
-  jobs, success rate, avg duration, avg tokens, and avg cost.
+- The **Usage** tab (the same `/analytics` data from section 8) shows
+  usage per profile for the last 7/30/90 days: jobs, success rate, avg
+  duration, avg tokens, and avg cost.
 - The **diagnostic ZIP export** on a job includes `profile.json` with
   the exact snapshot that rail used.
 
 ## 6. Troubleshooting
 
-- **Upgrade banner on Agents page** — `npx specrails-core@latest update`
-  in the project to bring it to ≥ 4.1.0.
+- **Upgrade banner on Agents page** — run
+  `npx specrails-core@^4.8.0 update` in the project to bring it up to date
+  (profiles need ≥ 4.1.0; the version the app installs is `^4.8.0`).
 - **Save disabled with "N issues to resolve"** — the live validator
   enforces the baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`)
   and routing ordering. Among the rules: a `default: true` routing rule (if
@@ -115,7 +139,8 @@ see output, token count, and duration inline.
 - **The whole Agents section is missing** — it can be disabled server-side
   with `SPECRAILS_AGENTS_SECTION=false`, which 404s the entire
   `/profiles` router. Unset it (or leave it at its default) to restore the
-  section.
+  section. This flag is read **once at server startup**, so changing it
+  takes effect only after a server restart.
 
 ## 7. Reserved paths
 
@@ -136,7 +161,10 @@ A few internals worth knowing if you're working on this surface:
   `projectSupportsProfiles()` (`server/queue-manager.ts`), which reads the
   project's `.specrails/specrails-version` and requires
   `specrails-core >= 4.1.0`. Below that, the rail spawns in legacy mode and
-  no profile env var is injected.
+  no profile env var is injected. The same is true on any non-Claude rail:
+  the rails router force-nulls the profile for Codex/Gemini engines, so the
+  `SPECRAILS_PROFILE_PATH` injection below only ever takes effect on a
+  Claude rail.
 - **Snapshot per job.** When a rail launches with a profile, the resolved
   profile is written to
   `~/.specrails/projects/<slug>/jobs/<jobId>/profile.json` (chmod `400`, so

package/docs/platforms/macos.md

@@ -43,9 +43,19 @@ You only need this once per build. It does not apply to the notarized installers
 When you add a project, the app checks for the tools it needs and surfaces them in a **prerequisites panel** (in the `Add Project` dialog and the setup wizard). It checks:
 
 - **Bundled tools** — `node`, `npm`, `npx`, `git`.
-- **Provider CLIs** — **Claude Code** and **Codex**. These are always probed via your system `PATH` (never bundled). **At least one provider must be installed and working** before Add Project is enabled — if neither is usable the panel blocks the dialog.
+- **Provider CLIs** — **Claude Code**, **Codex**, and **Gemini CLI**. All three are always probed via your system `PATH` (never bundled). **At least one of the three must be installed and working** before Add Project is enabled — if none is usable the panel blocks the dialog.
 
-When everything is in order, the panel collapses to a single line: **All required tools detected** (no per-tool rows, no version numbers). The detailed per-tool list — with versions, and including the Claude/Codex provider rows — only renders when something is **missing**, below its minimum version, or broken.
+You don't need all three providers. Install whichever you prefer:
+
+| Provider | Install | Minimum CLI | Auth |
+|---|---|---|---|
+| **Claude Code** | from [claude.com/download](https://claude.com/download) | none pinned | `claude login` |
+| **Codex** | `brew install codex` | `0.128.0` | `codex login` |
+| **Gemini CLI** | `npm i -g @google/gemini-cli` | `0.11.0` | set `GEMINI_API_KEY` (a paid key from Google AI Studio) |
+
+After installing a provider CLI, quit and relaunch Specrails so the new `PATH` is picked up (see [Verifying manually](#verifying-manually)). For full provider setup, see the [Codex guide](../codex.md) and the [Gemini guide](../gemini.md).
+
+When everything is in order, the panel collapses to a single line: **All required tools detected** (no per-tool rows, no version numbers). The detailed per-tool list — with versions, and including the Claude / Codex / Gemini provider rows (one row per provider you've installed) — only renders when something is **missing**, below its minimum version, or broken.
 
 ## PATH resolution
 
@@ -53,13 +63,13 @@ GUI apps on macOS inherit a minimal `PATH` from launchd when launched from Finde
 
 ### Desktop app (the default for `.dmg` users)
 
-The shipped desktop app bundles its own Node and Git runtimes. When those bundled binaries are present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SPECRAILS_BUNDLED_RUNTIMES_PATH` before spawning the embedded server (`src-tauri/src/lib.rs`). In that mode `resolveStartupPath()` (in `server/path-resolver.ts`):
+The shipped desktop app bundles its own Node and Git runtimes. When **both** the bundled `node` and `git` bin directories are present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SPECRAILS_BUNDLED_RUNTIMES_PATH` before spawning the embedded server (`src-tauri/src/lib.rs`). In that mode `resolveStartupPath()` (in `server/path-resolver.ts`):
 
 - Prepends the **bundled** `node` and `git` bin directories to the front of `process.env.PATH`. A system Homebrew or nvm-managed `node`/`git` can never shadow them.
 - **Skips** the Homebrew fast-path prepend entirely.
 - **Skips** the login-shell merge — `augmentPathFromLoginShell()` is a no-op so it cannot reorder system tools ahead of the bundled ones (`loginShellStatus: "skipped"`).
 
-If a build ships **without** the bundled runtimes (or has a partial/botched extraction), the desktop app does **not** dead-end: it falls through to the same system discovery described below, so a system-installed `node`/`git` still satisfies the requirement.
+If a build ships **without** the bundled runtimes — or has only a partial bundle (just one of the two directories present, or a botched extraction) — the desktop app does **not** dead-end: it falls through to the same system discovery described below, so a system-installed `node`/`git` still satisfies the requirement.
 
 ### Server / non-bundled fallback
 
@@ -88,7 +98,7 @@ This points you at the actual fix (remove the stale link) instead of sending you
 
 ## Diagnostic endpoint
 
-`GET /api/setup-prerequisites?diagnostic=1` returns the standard payload plus a `diagnostic` block. Example (illustrative — real payloads also carry `pathSources: "bundled"` segments in desktop mode):
+`GET /api/setup-prerequisites?diagnostic=1` returns the standard payload plus a `diagnostic` block. The example below is a **non-desktop / server run** (e.g. `npm run dev:server`), where `PATH` is reconstructed via the fast path + inherited entries:
 
 ```jsonc
 {
@@ -102,7 +112,8 @@ This points you at the actual fix (remove the stale link) instead of sending you
       "npx": "/opt/homebrew/bin/npx",
       "git": "/usr/bin/git",
       "claude": "/opt/homebrew/bin/claude",
-      "codex": null
+      "codex": null,
+      "gemini": null
     },
     "nodeEnv": "production",
     "platform": "darwin"
@@ -110,7 +121,15 @@ This points you at the actual fix (remove the stale link) instead of sending you
 }
 ```
 
-`whichResults` is keyed by command name for **every** prerequisite the panel checks, so it includes `claude`/`codex` (and `uv` when probed) on top of the four bundled tools.
+In the **shipped desktop app** the first segments come from the bundled runtimes instead, so the leading `pathSources` entries read `"bundled"` and `loginShellStatus` is `"skipped"`:
+
+```jsonc
+"pathSegments": ["/Applications/Specrails.app/.../runtimes/node/bin", "/Applications/Specrails.app/.../runtimes/git/bin", "..."],
+"pathSources": ["bundled", "bundled", "..."],
+"loginShellStatus": "skipped"
+```
+
+`whichResults` is keyed by command name for **every** prerequisite the panel checks, so it includes `claude`/`codex`/`gemini` (and `uv` when probed) on top of the four bundled tools. A `null` value means that command was not found on `PATH` — in the example above, only Claude Code is installed.
 
 The install-instructions modal exposes a **Copy diagnostics** button that fetches this endpoint and copies the JSON to the clipboard for bug reports. The base endpoint (no `?diagnostic=1`) omits the `diagnostic` field, keeping the regular UI poll small.
 
@@ -125,6 +144,6 @@ After installing or reinstalling Node (or a provider CLI):
 
 ## Known limitations
 
-- **Provider requirement**: at least one of Claude Code or Codex must be installed and on `PATH`; otherwise Add Project stays disabled.
+- **Provider requirement**: at least one provider CLI — Claude Code, Codex, or Gemini — must be installed and on `PATH`; otherwise Add Project stays disabled. (Gemini is enabled by default; to disable it set `SPECRAILS_GEMINI_BETA=0`.)
 - **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket; if another process holds the port, the server cannot start.
 - **Terminal panel**: the bottom terminal panel spawns `$SHELL -l -i`, so your `.zshrc` / `.bashrc` loads as it would in a normal login shell. Per-session shell selection is not yet exposed in the UI — set `SHELL` to override the default.