specrails-desktop 2.55.0 → 2.56.0

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-BfAZg5DG.js"></script>
+    <script type="module" crossorigin src="/assets/index-Cxb288Rj.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-CNC7AqOf.js">
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-zu2_FqZY.js">
     <link rel="modulepreload" crossorigin href="/assets/react-dom-DiWzBDP9.js">
@@ -225,7 +225,7 @@
     <link rel="modulepreload" crossorigin href="/assets/code-DaZ-ZwCT.js">
     <link rel="modulepreload" crossorigin href="/assets/commands-BAWSYHjQ.js">
     <link rel="modulepreload" crossorigin href="/assets/common-BrlwEnL7.js">
-    <link rel="modulepreload" crossorigin href="/assets/dashboard-DBAP2_SQ.js">
+    <link rel="modulepreload" crossorigin href="/assets/dashboard-BV4vOZkR.js">
     <link rel="modulepreload" crossorigin href="/assets/explore-DgBACn39.js">
     <link rel="modulepreload" crossorigin href="/assets/integrations-mB-7zoyT.js">
     <link rel="modulepreload" crossorigin href="/assets/jira-CKJg3HZd.js">
@@ -234,22 +234,22 @@
     <link rel="modulepreload" crossorigin href="/assets/mcp-CUAN6ORK.js">
     <link rel="modulepreload" crossorigin href="/assets/narration-n3hOA7LY.js">
     <link rel="modulepreload" crossorigin href="/assets/nav-DhPb-Isc.js">
-    <link rel="modulepreload" crossorigin href="/assets/packet-DwPtJoDz.js">
+    <link rel="modulepreload" crossorigin href="/assets/packet-B0H15elv.js">
     <link rel="modulepreload" crossorigin href="/assets/settings-HZSu-K4l.js">
     <link rel="modulepreload" crossorigin href="/assets/setup-DpqzaEEA.js">
     <link rel="modulepreload" crossorigin href="/assets/specs-DfIdoU5L.js">
     <link rel="modulepreload" crossorigin href="/assets/terminal-BAzpHtpY.js">
     <link rel="modulepreload" crossorigin href="/assets/tickets-D41ZMQpf.js">
     <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-Bjbbp_KS.js">
-    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-DcPRKR8R.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-DtWlCJN9.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-CPB4cnwI.js">
+    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-Dz-HI6De.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-DEbgkuAY.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-QogiN0zR.js">
     <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-Vi1ZGvAK.js">
     <link rel="modulepreload" crossorigin href="/assets/save-B6wGWwBR.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-BGmZBX5B.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-T5GM7wpn.js">
     <link rel="modulepreload" crossorigin href="/assets/sparkles-DrY8hb0X.js">
     <link rel="modulepreload" crossorigin href="/assets/x-CBMI9ejn.js">
-    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-BGtEjWsc.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-D3QzgV0B.js">
     <link rel="modulepreload" crossorigin href="/assets/zap-CUOlvtT1.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-x-CMYsN4ZH.js">
     <link rel="modulepreload" crossorigin href="/assets/download-CFHyyHcw.js">
@@ -269,18 +269,18 @@
     <link rel="modulepreload" crossorigin href="/assets/utils-BC4DHlz2.js">
     <link rel="modulepreload" crossorigin href="/assets/dialog-xXB2q5HJ.js">
     <link rel="modulepreload" crossorigin href="/assets/lib-CGdyxIWg.js">
-    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-BAhW5E6V.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-DYmvOA3R.js">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-BHm2U-w1.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-Cc2u5FwQ.js">
     <link rel="modulepreload" crossorigin href="/assets/button-Ccc9Dc-D.js">
-    <link rel="modulepreload" crossorigin href="/assets/jira-api-B27Za5FP.js">
-    <link rel="modulepreload" crossorigin href="/assets/project-repositories-DixIZHTA.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-CAGY3xW6.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-C0jQ5yOk.js">
+    <link rel="modulepreload" crossorigin href="/assets/jira-api-DrGxiD9p.js">
+    <link rel="modulepreload" crossorigin href="/assets/project-repositories-9Wzs0coQ.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-hPGZNRBm.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-DAK-NoK6.js">
     <link rel="modulepreload" crossorigin href="/assets/core-B3mKBIh5.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-DrcrxLe0.js">
-    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-DEQ9HdAM.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-Du2UCf1a.js">
+    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-Dqmz9fS9.js">
     <link rel="modulepreload" crossorigin href="/assets/event-Bt7f3wXe.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BAtqmAZR.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-C51x61Bz.css">
   </head>
   <body>
     <div id="specrails-splash" aria-hidden="false" role="status" aria-label="Loading Specrails">

package/docs/codex.md

@@ -149,7 +149,7 @@ A few Codex-specific behaviours worth calling out:
 
 Codex does not report `total_cost_usd` natively. The app computes an
 estimate from the captured `usage` (input / output / cached input
-tokens × the local rate-card in `server/pricing.ts`) and stores it in
+tokens × the local rate-card in `server/modules/accounting/runtime/pricing.ts`) and stores it in
 `ai_invocations.total_cost_usd` with `total_cost_usd_estimated = 1`.
 
 The Analytics page surfaces this in two places:
@@ -168,7 +168,7 @@ The Analytics page surfaces this in two places:
 
 The pricing table is reviewed quarterly. The reference date sits on
 each entry as `lastReviewedAt`. If OpenAI raises prices mid-quarter,
-ship an out-of-band update to `server/pricing.ts`.
+ship an out-of-band update to `server/modules/accounting/runtime/pricing.ts`.
 
 ## Plugins and MCP on codex projects
 
@@ -198,7 +198,7 @@ adapter pins the minimum because earlier versions don't support
 or set `OPENAI_API_KEY`. The app doesn't proxy auth.
 
 **Cost shows as `—` for codex jobs even though tokens are non-zero**
-— the spawned model isn't in `server/pricing.ts` (e.g. a brand-new
+— the spawned model isn't in `server/modules/accounting/runtime/pricing.ts` (e.g. a brand-new
 model OpenAI shipped after our last review). Update the pricing table
 and reload the page.
 
@@ -243,8 +243,8 @@ The codex integration lives in:
 - `server/providers/codex-adapter.ts` — `ProviderAdapter`
   implementation for codex 0.128.0+. Fixtures under
   `server/providers/__fixtures__/codex/0.128.0/`.
-- `server/pricing.ts` — local pricing table + `estimateCostUsd`.
-- `server/codex-otel-bridge.ts` — synthetic OTEL traces / metrics /
+- `server/modules/accounting/runtime/pricing.ts` — local pricing table + `estimateCostUsd`.
+- `server/modules/accounting/runtime/codex-otel-bridge.ts` — synthetic OTEL traces / metrics /
   logs derived from JSONL events.
 - `server/plugins/codex-mcp.ts` — `codex mcp add/remove/list` wrapper
   with per-project `CODEX_HOME`.

package/docs/customizing.md

@@ -27,7 +27,7 @@ There's an inline anti-FOUC script in `client/index.html` so a page refresh neve
 
 The active theme persists to `desktop_settings.ui_theme` on the server and mirrors to `localStorage` so the desktop app and browser stay in sync if you use both.
 
-> Want a sixth theme? It's a small contribution — see `client/src/lib/themes.ts` and [internals/architecture.md](internals/architecture.md) for the contract.
+> Want a sixth theme? It's a small contribution — see `client/src/features/settings/lib/themes.ts` and [internals/architecture.md](internals/architecture.md) for the contract.
 
 ## Sidebars
 

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

@@ -40,7 +40,7 @@ Decisión: **pinear ids GA concretos, no alias ni ids preview**, porque los 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):**
+**Filas para `server/modules/accounting/runtime/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).
@@ -159,7 +159,7 @@ export { claudeAdapter, codexAdapter, geminiAdapter }
 
 **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:
+**Cómo se inyecta** — en `server/modules/execution/runtime/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
@@ -185,15 +185,15 @@ 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/modules/specs/runtime/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/features/providers/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/features/chat/components/ChatInput.tsx:7-18,25` | selección por id-keyed map; ensanchar `provider?: 'claude'\|'codex'`. | **sí** |
+| `client/src/features/projects/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 |
 
@@ -203,17 +203,17 @@ Mergeable independiente, no cambia comportamiento observable.
 |---|---|---|
 | `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/modules/accounting/runtime/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 |
+| `server/modules/agents/runtime/agent-refine-manager.ts:73,79` | ensanchar `provider?: 'claude'\|'codex'`. (validateAgentBody ya skip non-claude). | **sí** (compile) |
+| `server/modules/conversations/runtime/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/modules/accounting/runtime/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/features/chat/types/context-scope.ts:62-67` | añadir filas de coste gemini (cliente). | menor |
+| `client/src/features/analytics/components/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) |
@@ -273,7 +273,7 @@ CI exige **80% server** (lines/functions/statements, 70% branches) y **80% clien
   - `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/modules/accounting/runtime/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.
 
@@ -296,6 +296,6 @@ CI exige **80% server** (lines/functions/statements, 70% branches) y **80% clien
 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.
+**Primer commit recomendado:** PR-A paso atómico — ensanchar `server/desktop-db.ts:10` `CliProvider` para incluir `'gemini'` y convertir el ternario de `server/modules/specs/runtime/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

@@ -157,4 +157,4 @@ Un **spike de validación de orquestación**, ANTES de escribir el scaffold comp
 - 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).
+- 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/modules/execution/runtime/queue-manager.ts` (command translation, `profile=null`), `/Users/javi/repos/specrails-desktop/client/src/features/providers/lib/provider-capabilities.ts` (ocultar rails gemini).

package/docs/gemini.md

@@ -113,7 +113,7 @@ A few of these deserve a fuller explanation:
 
 - **Cost is estimated, not native.** Gemini reports token counts (including
   cached) but no USD cost in its stream, so Specrails estimates the cost from
-  a rate card (`server/pricing.ts`, keys `gemini:<model>`). Estimated rows
+  a rate card (`server/modules/accounting/runtime/pricing.ts`, keys `gemini:<model>`). Estimated rows
   show a `~` prefix on the Analytics page.
 - **OTEL is native.** Like Claude, Gemini honours the standard `OTEL_*`
   telemetry env vars, so QueueManager injects the same telemetry env
@@ -167,7 +167,7 @@ Flash models; Pro/preview need billing.
 
 > A few older ids (`gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-flash-preview`)
 > are **not** selectable models. They survive only as historic pricing rows in
-> `server/pricing.ts` so that already-recorded invocations on those models still
+> `server/modules/accounting/runtime/pricing.ts` so that already-recorded invocations on those models still
 > price correctly.
 
 ## Trusted folders (headless)
@@ -204,7 +204,7 @@ preview models; use a Flash model or enable billing.
 **Cost shows `—`** — there's no `gemini:<model>` pricing row for the model
 that ran (e.g. a brand-new model Google shipped after our last review). Cost
 estimation fails soft (it returns nothing rather than guessing). Add a row to
-`server/pricing.ts` and reload.
+`server/modules/accounting/runtime/pricing.ts` and reload.
 
 ## Emergency rollback
 
@@ -231,7 +231,7 @@ are unaffected; the adapter stays registered but dormant.
   `minCliVersion: '0.11.0'`). Registered in `server/providers/index.ts`.
 - **Headless subagent ack:** `server/providers/gemini-agent-ack.ts`
   (`acknowledgeGeminiProjectAgents`), wired as the adapter's
-  `prepareHeadlessSpawn` and called by `server/queue-manager.ts` before each
+  `prepareHeadlessSpawn` and called by `server/modules/execution/runtime/queue-manager.ts` before each
   rail spawn.
 - **Stream schema** (pinned to the gemini-cli 0.11 contract, locked by the
   fixtures under `server/providers/__fixtures__/gemini-*.ndjson`):
@@ -241,7 +241,7 @@ are unaffected; the adapter stays registered but dormant.
 - **Beta gate + provider list:** `server/desktop-router.ts`
   (`isGeminiBetaDisabled` — returns `true` only when
   `SPECRAILS_GEMINI_BETA === '0'`; `/available-providers`, `POST /projects`).
-- **Pricing / cost estimation:** `server/pricing.ts` (`gemini:<model>` rows +
+- **Pricing / cost estimation:** `server/modules/accounting/runtime/pricing.ts` (`gemini:<model>` rows +
   `estimateCostUsd`, which returns `null` when no row matches).
 - **Trust-folder env:** `server/util/cli-prompt.ts`, `spawnGemini`.
 

package/docs/internals/README.md

@@ -6,9 +6,13 @@ If you're a user looking for **how do I do X?** docs, head back to the [user gui
 
 ## Contents
 
+Start with [the modular architecture decision](modular-architecture.md),
+[the source map](source-map.md) and [the shared contributor/AI guide](../../AGENTS.md).
+
 | Doc | What it covers |
 |-----|----------------|
 | [architecture.md](architecture.md) | Server modules, client layout, WebSocket protocol, process spawning, security model |
+| [source-architecture.md](source-architecture.md) | Persistence boundaries, queue collaborators and unused-source audit |
 | [api-reference.md](api-reference.md) | REST endpoint catalogue under `/api/*` and `/api/projects/:projectId/*` |
 | [configuration.md](configuration.md) | Settings, env vars, kill switches, advanced flags |
 | [operations-runbook.md](operations-runbook.md) | Start/stop, port conflicts, recovery procedures, backups |
@@ -17,7 +21,7 @@ If you're a user looking for **how do I do X?** docs, head back to the [user gui
 | [programmatic-agent-runtime-validation.md](programmatic-agent-runtime-validation.md) | Paired implementation test results, packaging evidence and release limitations |
 | [openspec-workflow.md](openspec-workflow.md) | `opsx:*` change lifecycle — used by the app itself for structured change management |
 | [adding-a-provider.md](adding-a-provider.md) | How to add a new AI CLI: one adapter file plus one entry in the registry |
-| [profiles.md](profiles.md) | Agent profiles quick start: open the Agents section, pick a profile per rail at launch, author custom agents in Agent Studio. For the true file-format and snapshotting internals, read `server/profile-manager.ts` and the profile-manager section of `CLAUDE.md` |
+| [profiles.md](profiles.md) | Agent profiles quick start: open the Agents section, pick a profile per rail at launch, author custom agents in Agent Studio. For the true file-format and snapshotting internals, read `server/modules/agents/runtime/profile-manager.ts` and the profile-manager section of `CLAUDE.md` |
 | [safe-pr-review-flow.md](safe-pr-review-flow.md) | The ask-first PR delivery: the `rail_pr_deliveries` row, decision state machine, the two synced decision surfaces (rail row + agent-chat card), the `on_review` ticket status and its Jira mapping |
 | [interactive-jobs.md](interactive-jobs.md) | Interactive-by-default jobs: the persistent-stdin session model, `finalize` vs `auto` settle modes, loop-step turn routing, accounting reconciliation, kill-switch matrix |
 | [loop-step-log-explorer.md](loop-step-log-explorer.md) | The step-grouped log surface for loop runs: the `loop_graph` / `loop_step` / `loop_step_end` event contract and seq guarantees, grouping + status model (interrupted rule, legacy fallback), follow mode, perf notes |
@@ -31,6 +35,6 @@ status is capability-aware: Kimi pure-output transforms fail closed.
 
 ## Contributing
 
-For coding conventions, file naming, the coverage policy, and how WebSocket handlers are expected to be wired, see [`CLAUDE.md`](../../CLAUDE.md) at the repo root. That file is the authoritative source for project-wide rules.
+For coding conventions, file naming, the coverage policy and WebSocket invariants, see [`AGENTS.md`](../../AGENTS.md). `CLAUDE.md` imports that shared guide; detailed history is kept in [optional reference notes](legacy-implementation-notes.md).
 
 When adding a feature, follow the OpenSpec workflow: `/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive`. The `/opsx:*` invocations resolve to command files under `.claude/commands/opsx/*.md` (the related skills under `.claude/skills/` are named `openspec-*`).

package/docs/internals/adding-a-provider.md

@@ -51,7 +51,7 @@ export const exampleAdapter: ProviderAdapter = {
   capabilities: {
     nativeResume: true,
     nativeStreamJson: true,
-    nativeCostUsd: false,    // if false, add the provider:model entries to server/pricing.ts
+    nativeCostUsd: false,    // if false, add the provider:model entries to server/modules/accounting/runtime/pricing.ts
     nativeOtelEnv: false,    // if false, the app will synthesise OTEL via the bridge
     profileEnvSupport: true,
     systemPromptArg: false,
@@ -130,7 +130,7 @@ accordingly — don't assume null-only-on-empty.
 
 The model catalog is **duplicated** by design: the adapter's `modelCatalog()`
 drives the spawn-time UI, but spec-model validation reads a *second* copy in
-`server/spec-models.ts` (`PROVIDER_MODELS` + `PROVIDER_DEFAULT_MODEL`, both
+`server/modules/specs/runtime/spec-models.ts` (`PROVIDER_MODELS` + `PROVIDER_DEFAULT_MODEL`, both
 `Record<string, …>` keyed by provider id). The file even comments that
 `GEMINI_MODELS` "Mirrors GEMINI_MODELS in server/providers/gemini-adapter.ts".
 If you add the catalog only to the adapter, your models won't validate in the
@@ -163,22 +163,22 @@ provider with zero edits):
   (the only per-id touch on this route is an optional beta gate, below).
 - `POST /api/projects` provider validation (`server/desktop-router.ts`,
   via `hasAdapter` / `listAdapters`).
-- `AddProjectDialog` (`client/src/components/AddProjectDialog.tsx`) — it
+- `AddProjectDialog` (`client/src/features/projects/components/AddProjectDialog.tsx`) — it
   fetches `/available-providers` generically (`Object.entries(data)`) and a
   `providerRenderOrder()` helper appends **any** detected-but-unlisted
   provider after the canonical-ordered known ones, with a neutral chip
   fallback. A new provider appears in the Add Project UI automatically.
 - `setup-prerequisites` provider rows (`server/setup-prerequisites.ts`,
   iterates `listAdapters()`).
-- Analytics `byProvider` (`server/spending.ts`) and the
-  `ProviderBreakdownCard` (`client/src/components/analytics/ProviderBreakdownCard.tsx`).
+- Analytics `byProvider` (`server/modules/accounting/runtime/spending.ts`) and the
+  `ProviderBreakdownCard` (`client/src/features/analytics/components/ProviderBreakdownCard.tsx`).
 
 ### `ProviderId` is `string` — no compile-time blocker
 
 There is **no type-union to widen**. `ProviderId` is `export type ProviderId = string`
 (`server/providers/types.ts`), and every provider-typed seam already aliases it:
-`CliProvider` (`server/desktop-db.ts`), `SpecProvider` (`server/spec-models.ts`),
-`EnqueueOptions.provider` and `_jobProviderSelection` (`server/queue-manager.ts`),
+`CliProvider` (`server/desktop-db.ts`), `SpecProvider` (`server/modules/specs/runtime/spec-models.ts`),
+`EnqueueOptions.provider` and `_jobProviderSelection` (`server/modules/execution/runtime/queue-manager.ts`),
 `ChatManager`, `AgentRefineManager`, and `ProjectRegistry`. Adding a provider is
 **not** a compile-time blocker — the old "widen ~8 unions" step is paid off (Gemini
 is the proof it works). Any remaining `'claude' | 'codex'` literals live in test
@@ -210,16 +210,16 @@ makes it look first-class instead of falling back to a raw id:
 ### 3. (If `nativeCostUsd === false`) add pricing entries
 
 For providers that don't report `total_cost_usd` in their terminal
-event, append the rate card to `server/pricing.ts`:
+event, append the rate card to `server/modules/accounting/runtime/pricing.ts`:
 
 ```ts
 'example:flagship': { inputPer1M: 5.00, outputPer1M: 15.00, cacheReadPer1M: 0.50, lastReviewedAt: '2026-05-18' },
 'example:fast':     { inputPer1M: 0.50, outputPer1M:  1.50, cacheReadPer1M: 0.05, lastReviewedAt: '2026-05-18' },
 ```
 
-The `finaliseInvocationResult` flow in `server/result-event.ts` falls
+The `finaliseInvocationResult` flow in `server/modules/accounting/runtime/result-event.ts` falls
 back to this table automatically and returns an `estimated` flag that
-`recordInvocation` (`server/ai-invocations.ts`) persists as
+`recordInvocation` (`server/modules/accounting/runtime/ai-invocations.ts`) persists as
 `total_cost_usd_estimated = 1` on the `ai_invocations` row, which in
 turn lights up the `~` tilde + Hero footnote on the AnalyticsPage.
 
@@ -233,7 +233,7 @@ Two paths, picked by your `nativeOtelEnv` capability flag:
   is no `GEMINI_TELEMETRY_*` env var — Gemini honours the same `OTEL_*` vars as
   Claude.
 - **`nativeOtelEnv: false`** (Codex, Kimi) ⇒ the synthetic OTEL bridge at
-  `server/codex-otel-bridge.ts` fills the gap. It's provider-neutral despite its
+  `server/modules/accounting/runtime/codex-otel-bridge.ts` fills the gap. It's provider-neutral despite its
   name — it consumes the canonical `AdapterEvent` stream. As long as your
   adapter's `parseStreamLine` emits `text-delta`, `tool-use`, `session-started`,
   and `result` events, the bridge synthesises traces / metrics / logs for free.
@@ -296,7 +296,7 @@ Two distinct version concepts — don't conflate them:
 ## Known gotchas
 
 - **Legacy result path.** `normaliseResultEvent(event, provider)`
-  (`server/result-event.ts`) is still live for any callsite not yet
+  (`server/modules/accounting/runtime/result-event.ts`) is still live for any callsite not yet
   migrated to `finaliseInvocationResult`. It only special-cases
   `provider === 'claude'`; everything else falls into the non-claude
   (codex-shaped) branch. A new provider hitting that path would be
@@ -363,15 +363,15 @@ Most of the old debt is **paid off** — and Gemini's addition is what paid it:
 
 The genuine id-keyed sites that **remain** are:
 
-- **`normaliseResultEvent` legacy branch** (`server/result-event.ts`) — the
+- **`normaliseResultEvent` legacy branch** (`server/modules/accounting/runtime/result-event.ts`) — the
   pre-`finaliseInvocationResult` path that special-cases `provider === 'claude'`.
-- **Codex rail slash-command rewrite** (`server/queue-manager.ts`) —
+- **Codex rail slash-command rewrite** (`server/modules/execution/runtime/queue-manager.ts`) —
   `adapter.id === 'codex'`.
 
 Plus a few cosmetic per-id sites that are *expected* edits, not drift: the
 provider beta-gate env checks (`server/desktop-router.ts`), the install-hint
 `switch` (`server/setup-prerequisites.ts`), the `PROVIDER_ORDER` / `PROVIDER_META`
-chip, and the duplicated model catalog (`server/spec-models.ts`).
+chip, and the duplicated model catalog (`server/modules/specs/runtime/spec-models.ts`).
 
 The long-term goal is to delete the two remaining branches so adding a fourth
 provider really is just the adapter file plus the registry entry. If you find a
@@ -397,3 +397,10 @@ bundled `local-runner` process, which speaks claude-shaped stream-json so the
 spawn contract is unchanged. If you add another endpoint-backed provider, reuse
 that adapter factory + the runner rather than teaching managers a new
 transport. See `docs/internals/local-agent-runner.md`.
+
+### Claude Opus generation
+
+The `opus` catalog value selects Claude Opus 5.5 (`claude-opus-5-5`). Keep the
+Claude adapter pin, selector labels, Core CLI executor and cost estimates aligned
+when advancing this alias. Concrete historical model IDs in usage events retain
+their existing estimates; provider-reported cost remains authoritative.

package/docs/internals/agent-runtime-framework-evaluation.md

@@ -32,7 +32,7 @@ Los tres repositorios ya contienen ejecución programática, con responsabilidad
 | Desktop | Adaptadores, procesos, streaming, colas, loops, SQLite, costes, worktrees, MCP y entrega | Control homogéneo por fase; reanudación durable del grafo; política de proveedor por rol |
 | ai-agent-dev | Pipeline TypeScript con Claude Agent SDK, contexto preparado, JSON de análisis, herramientas y checks | Generalización, proveedores intercambiables, persistencia durable y garantías de ejecución |
 
-En Desktop, el pipeline principal sigue empaquetado en un único paso de IA. Su propio código lo explica: architect → developer → reviewer ocurre dentro de la invocación completa de Core. Eso limita qué puede observar y controlar el host en cada fase. [Grafo de Implement](/Users/javi/repos/specrails-desktop/server/loop-factory.ts:42).
+En Desktop, el pipeline principal sigue empaquetado en un único paso de IA. Su propio código lo explica: architect → developer → reviewer ocurre dentro de la invocación completa de Core. Eso limita qué puede observar y controlar el host en cada fase. [Grafo de Implement](/Users/javi/repos/specrails-desktop/server/modules/loops/runtime/loop-factory.ts:42).
 
 La migración debe conservar los prompts que expresan conocimiento de arquitectura, desarrollo y revisión. Las decisiones mecánicas —routing, siguiente fase, reintento, validación, presupuesto— deben tener una implementación ejecutable única.
 
@@ -70,17 +70,17 @@ Core ya proporciona un contrato valioso: identidad de ejecución, specs congelad
 
 Pero este helper no ejecuta agentes: la coordinación principal sigue en plantillas distintas para Claude, Codex y Gemini; Kimi tiene un runner específico considerable. Existe incluso deriva entre el perfil validado y el prompt: schema/CLI permiten routing vacío o sin default, mientras el prompt Claude exige routing y exactamente un default. Centralizar esa decisión en código elimina una fuente de divergencia. [Operaciones del helper](/Users/javi/repos/specrails-core/src/installer/runtime/pipeline-state.ts:670), [schema](/Users/javi/repos/specrails-core/schemas/profile.v1.json:74), [validador CLI](/Users/javi/repos/specrails-core/bin/specrails-core.mjs:516), [prompt](/Users/javi/repos/specrails-core/templates/commands/specrails/implement.md:93).
 
-Desktop ya tiene contratos de capacidades y eventos para Claude, Codex, Gemini y Kimi. Hay transporte Codex app-server y Claude stream-json, además de ejecución por procesos. No hace falta reemplazar de golpe estos transportes para conseguir control programático. [ProviderAdapter](/Users/javi/repos/specrails-desktop/server/providers/types.ts:213), [ciclo común](/Users/javi/repos/specrails-desktop/server/spawn-lifecycle.ts:94), [sesiones vivas](/Users/javi/repos/specrails-desktop/server/providers/live-session.ts:5).
+Desktop ya tiene contratos de capacidades y eventos para Claude, Codex, Gemini y Kimi. Hay transporte Codex app-server y Claude stream-json, además de ejecución por procesos. No hace falta reemplazar de golpe estos transportes para conseguir control programático. [ProviderAdapter](/Users/javi/repos/specrails-desktop/server/providers/types.ts:213), [ciclo común](/Users/javi/repos/specrails-desktop/server/modules/execution/runtime/spawn-lifecycle.ts:94), [sesiones vivas](/Users/javi/repos/specrails-desktop/server/providers/live-session.ts:5).
 
 Sus límites actuales ayudan a definir el piloto:
 
-- El motor de loops sigue un único sucesor; no implementa fan-out/join interno, aunque sí existe paralelismo entre ejecuciones aisladas. [Validación del grafo](/Users/javi/repos/specrails-desktop/server/loop-graph.ts:208).
-- Al reiniciar, los loops activos o pausados se marcan fallidos. La recuperación contable y del outbox es útil, pero no reanuda la continuación en memoria. [Reconciliación](/Users/javi/repos/specrails-desktop/server/loop-runs-store.ts:545).
-- En loops manda el proveedor/modelo del rail para todos los nodos. Core admite un proveedor global y modelos por agente dentro de él. Permitir proveedor distinto por rol requiere un contrato nuevo explícito. [Política del rail](/Users/javi/repos/specrails-desktop/server/loop-run-manager.ts:1465), [perfil v1](/Users/javi/repos/specrails-core/schemas/profile.v1.json:26).
-- El cap de coste del loop se comprueba entre pasos: puede excederse por un paso completo. Si el paso contiene todo Implement, el control es muy grueso. [Contrato del cap](/Users/javi/repos/specrails-desktop/server/loop-graph.ts:57).
-- El ledger ya diferencia consumo y estimaciones; el desglose por fase es principalmente reconstrucción de eventos Claude. Hay que medir desde cada invocación independiente. [Ledger](/Users/javi/repos/specrails-desktop/server/ai-invocations.ts:37), [desglose](/Users/javi/repos/specrails-desktop/server/job-phase-breakdown.ts:3).
+- El motor de loops sigue un único sucesor; no implementa fan-out/join interno, aunque sí existe paralelismo entre ejecuciones aisladas. [Validación del grafo](/Users/javi/repos/specrails-desktop/server/modules/loops/runtime/loop-graph.ts:208).
+- Al reiniciar, los loops activos o pausados se marcan fallidos. La recuperación contable y del outbox es útil, pero no reanuda la continuación en memoria. [Reconciliación](/Users/javi/repos/specrails-desktop/server/modules/loops/runtime/loop-runs-store.ts:545).
+- En loops manda el proveedor/modelo del rail para todos los nodos. Core admite un proveedor global y modelos por agente dentro de él. Permitir proveedor distinto por rol requiere un contrato nuevo explícito. [Política del rail](/Users/javi/repos/specrails-desktop/server/modules/loops/runtime/loop-run-manager.ts:1465), [perfil v1](/Users/javi/repos/specrails-core/schemas/profile.v1.json:26).
+- El cap de coste del loop se comprueba entre pasos: puede excederse por un paso completo. Si el paso contiene todo Implement, el control es muy grueso. [Contrato del cap](/Users/javi/repos/specrails-desktop/server/modules/loops/runtime/loop-graph.ts:57).
+- El ledger ya diferencia consumo y estimaciones; el desglose por fase es principalmente reconstrucción de eventos Claude. Hay que medir desde cada invocación independiente. [Ledger](/Users/javi/repos/specrails-desktop/server/modules/accounting/runtime/ai-invocations.ts:37), [desglose](/Users/javi/repos/specrails-desktop/server/modules/execution/runtime/job-phase-breakdown.ts:3).
 
-Mantendría worktrees, locks, alcance multirrepo, validación final de Core, MCP y entrega de PRs. [Preparación y finalización](/Users/javi/repos/specrails-desktop/server/core-execution.ts:48), [aislamiento](/Users/javi/repos/specrails-desktop/server/rail-isolation.ts:28), [control de herramientas](/Users/javi/repos/specrails-desktop/server/mcp/tools/types.ts:280).
+Mantendría worktrees, locks, alcance multirrepo, validación final de Core, MCP y entrega de PRs. [Preparación y finalización](/Users/javi/repos/specrails-desktop/server/core-execution.ts:48), [aislamiento](/Users/javi/repos/specrails-desktop/server/modules/delivery/runtime/rail-isolation.ts:28), [control de herramientas](/Users/javi/repos/specrails-desktop/server/mcp/tools/types.ts:280).
 
 **Comparativa de alternativas**
 

package/docs/internals/api-reference.md

@@ -25,7 +25,7 @@ The CLI and the desktop client read the token automatically. The browser client
 
 There is no UI to set or clear the token, and it is not an app setting.
 
-This page is hand-maintained against the route declarations in `server/*-router.ts`, the per-domain `server/project-router-{jobs,spending,settings,terminals,tickets,chat,setup}.ts` family, `server/code-explorer-router.ts`, and `server/jira-router.ts`. If you spot a discrepancy, please file an issue.
+This page is hand-maintained against the route declarations in `server/*-router.ts`, the per-domain `server/project-router-{jobs,spending,settings,terminals,tickets,chat,setup}.ts` family, `server/modules/code/runtime/code-explorer-router.ts`, and `server/jira-router.ts`. If you spot a discrepancy, please file an issue.
 
 ---
 
@@ -761,5 +761,5 @@ Error responses are `{ "error": "<message>" }`.
 
 ## Caveats
 
-- **Surface drift**: this file is hand-maintained against the route declarations in `server/*-router.ts`, the per-domain `server/project-router-{jobs,spending,settings,terminals,tickets,chat,setup}.ts` family, `server/code-explorer-router.ts`, and `server/jira-router.ts`. The app adds endpoints regularly; if a route exists in code but not here, please open an issue.
+- **Surface drift**: this file is hand-maintained against the route declarations in `server/*-router.ts`, the per-domain `server/project-router-{jobs,spending,settings,terminals,tickets,chat,setup}.ts` family, `server/modules/code/runtime/code-explorer-router.ts`, and `server/jira-router.ts`. The app adds endpoints regularly; if a route exists in code but not here, please open an issue.
 - **Stability**: routes under `/api/*` and `/api/projects/:projectId/*` are considered stable. A few legacy setup endpoints (`setup/start`, `setup/message`, `enrich/*`) back a flow the UI does not expose and remain only for forward compatibility.

package/docs/internals/architecture.md

@@ -55,7 +55,7 @@ Tests use vitest with `:memory:` SQLite databases.
 
 > **Artifact relocation + bundled framework (pre-release, branch `feat/relocate-artifacts-to-home`).** Relocated projects spawn AI-CLIs from `projects/<slug>/workspace` (with `SPECRAILS_REPO_DIR` pointing at the repo) instead of the repo, so imported repos stay pristine; the framework is bundled and symlinked instead of installed per-project via `npx`. See the **Artifact relocation + bundled framework** section in `CLAUDE.md` and the three internal docs: `global-artifacts-relocation-evaluation.md`, `global-artifacts-alignment-contract.md`, `bundled-framework-build-plan.md`.
 
-The app SQLite (`desktop.sqlite`) stores only project metadata. All per-project data lives in an isolated `jobs.sqlite` under the project's slug directory — not just jobs and chat, but rails, tickets, agent profiles/versions, AI invocations (cost analytics), telemetry pointers, file provenance, terminal settings/marks, and more (see the `MIGRATIONS` array in `server/db.ts`). Projects can be removed and re-added without losing history, and the registry can be wiped without touching project data.
+The app SQLite (`desktop.sqlite`) stores only project metadata. All per-project data lives in an isolated `jobs.sqlite` under the project's slug directory — not just jobs and chat, but rails, tickets, agent profiles/versions, AI invocations (cost analytics), telemetry pointers, file provenance, terminal settings/marks, and more (see the `MIGRATIONS` array in `server/db/migrations.ts`). Projects can be removed and re-added without losing history, and the registry can be wiped without touching project data.
 
 > The data root is hardcoded to `os.homedir()/.specrails`. There is no environment override for the data directory.
 >
@@ -109,7 +109,7 @@ The `boundBroadcast` closure injects `projectId` into all WebSocket messages, so
 | `project-registry.ts` | `ProjectRegistry` class: load/unload per-project `ProjectContext` |
 | `desktop-router.ts` | `/api/*` routes: projects, settings, themes, specrails-tech proxy, cross-project analytics |
 | `project-router.ts` | `/api/projects/:id/*` routes: all project-scoped operations |
-| `db.ts` | Per-project SQLite: schema (`MIGRATIONS`) + queries |
+| `db.ts`, `db/` | Stable persistence facade with separate connection, migrations and domain repositories; see [source boundaries](source-architecture.md) |
 | `queue-manager.ts` | Job queue: spawn provider CLI processes serially per project |
 | `chat-manager.ts` | Chat/Explore: spawn provider CLI for conversational turns |
 | `setup-manager.ts` | Setup wizard: orchestrate `specrails-core` install + `/setup` chat |
@@ -265,14 +265,14 @@ The app is more than the job pipeline. Each subsystem owns its modules; this is
 | Subsystem | Server modules | Notes |
 |-----------|---------------|-------|
 | **Multi-provider adapters** | `server/providers/{types,claude-adapter,codex-adapter,gemini-adapter,kimi-adapter,registry,index}.ts`, `server/provider-selection.ts` | **Four first-class providers — Claude, Codex, Gemini, and Kimi — enabled by default** behind a `ProviderAdapter` contract. Claude reports native cost and supports persistent stdin; Codex (`≥ 0.128.0`) and Gemini (`≥ 0.11.0`) expose estimated usage; Kimi (`≥ 0.27.0`) runs CLI-only prompt-mode JSONL, resumes through terminal hints, uses `.kimi-code` skills/MCP, and leaves absent cost/tokens unavailable. A project can install any subset; `providers[]` is a JSON column, the first entry is primary. Per-invocation provider is late-bound. Provider availability is gated by executable detection, Core target compatibility, and the existing Codex/Gemini emergency switches. See [`adding-a-provider.md`](adding-a-provider.md), [`../codex.md`](../codex.md), [`../gemini.md`](../gemini.md), and [`../kimi.md`](../kimi.md). |
-| **Spending analytics** | `server/spending.ts`, `server/ai-invocations.ts`, `server/pricing.ts` | `recordInvocation` writes an `ai_invocations` row per AI CLI call across six surfaces (`job`, `quick-spec`, `explore-spec`, `ai-edit`, `smash`, `file-summary`); powers the Analytics page and `spending.invalidated`. |
-| **Agent profiles** | `server/profile-manager.ts`, `server/profiles-router.ts` | Declarative JSON in `.specrails/profiles/*.json`, snapshot-per-job, `SPECRAILS_PROFILE_PATH` env injection. Requires `specrails-core ≥ 4.1.0` in general and the Core 4.12 Kimi target for Kimi roles (the app-wide install floor is `^4.12.0`). Claude and Kimi advertise profile support; other adapters force legacy/no-profile mode. |
+| **Spending analytics** | `server/modules/accounting/runtime/spending.ts`, `server/modules/accounting/runtime/ai-invocations.ts`, `server/modules/accounting/runtime/pricing.ts` | `recordInvocation` writes an `ai_invocations` row per AI CLI call across six surfaces (`job`, `quick-spec`, `explore-spec`, `ai-edit`, `smash`, `file-summary`); powers the Analytics page and `spending.invalidated`. |
+| **Agent profiles** | `server/modules/agents/runtime/profile-manager.ts`, `server/modules/agents/runtime/profiles-router.ts` | Declarative JSON in `.specrails/profiles/*.json`, snapshot-per-job, `SPECRAILS_PROFILE_PATH` env injection. Requires `specrails-core ≥ 4.1.0` in general and the Core 4.12 Kimi target for Kimi roles (the app-wide install floor is `^4.12.0`). Claude and Kimi advertise profile support; other adapters force legacy/no-profile mode. |
 | **Plugins (Integrations)** | `server/plugin-manager.ts`, `server/plugins/` | Bundled-only, MCP-based, additivity invariant, surgical `.mcp.json` merge, `plugin.*` WS events. Serena ships today. |
-| **Terminal panel** | `server/terminal-manager.ts` | `node-pty` sessions over the dedicated `/ws/terminal/:id` socket, OSC shell-integration marks. See [`../terminal.md`](../terminal.md). |
-| **Code explorer** | `server/code-explorer-router.ts`, `server/file-provenance.ts`, `server/file-summary-manager.ts` | A non-developer-friendly file tree + Monaco viewer with plain-language AI summaries and *touched-by-AI* provenance chips per ticket/job, plus opt-in in-app editing of existing files (overwrite-only via `PUT /file` — no create/rename; refuses binaries `415`, enforces a 2 MB cap `413`, `404` on a missing path, respects deny-list/`.gitignore`). |
-| **Pipeline telemetry** | `server/telemetry-receiver.ts` + QueueManager OTEL injection | Opt-in OTLP/JSON signals to `POST /otlp/v1/{traces,metrics,logs}`; blobs compacted after 7 days; diagnostic ZIP export. |
-| **Explore acceleration + Contract Refine** | `server/explore-cwd-manager.ts`, `server/contract-refine-runner.ts` | App-managed Explore spawn cwd for fast first-token; optional post-commit Contract Layer enrichment. Kill switches: `SPECRAILS_EXPLORE_CONTRACT_REFINE`, `SPECRAILS_EXPLORE_LEGACY_CWD`. |
-| **Tickets / drafts** | `server/ticket-store.ts` | Spec tickets (incl. `draft` status) backing the Specs board and Save-as-Draft flow. |
+| **Terminal panel** | `server/modules/terminals/runtime/terminal-manager.ts` | `node-pty` sessions over the dedicated `/ws/terminal/:id` socket, OSC shell-integration marks. See [`../terminal.md`](../terminal.md). |
+| **Code explorer** | `server/modules/code/runtime/code-explorer-router.ts`, `server/modules/code/runtime/file-provenance.ts`, `server/modules/code/runtime/file-summary-manager.ts` | A non-developer-friendly file tree + Monaco viewer with plain-language AI summaries and *touched-by-AI* provenance chips per ticket/job, plus opt-in in-app editing of existing files (overwrite-only via `PUT /file` — no create/rename; refuses binaries `415`, enforces a 2 MB cap `413`, `404` on a missing path, respects deny-list/`.gitignore`). |
+| **Pipeline telemetry** | `server/modules/accounting/runtime/telemetry-receiver.ts` + QueueManager OTEL injection | Opt-in OTLP/JSON signals to `POST /otlp/v1/{traces,metrics,logs}`; blobs compacted after 7 days; diagnostic ZIP export. |
+| **Explore acceleration + Contract Refine** | `server/modules/conversations/runtime/explore-cwd-manager.ts`, `server/modules/specs/runtime/contract-refine-runner.ts` | App-managed Explore spawn cwd for fast first-token; optional post-commit Contract Layer enrichment. Kill switches: `SPECRAILS_EXPLORE_CONTRACT_REFINE`, `SPECRAILS_EXPLORE_LEGACY_CWD`. |
+| **Tickets / drafts** | `server/modules/specs/runtime/ticket-store.ts` | Spec tickets (incl. `draft` status) backing the Specs board and Save-as-Draft flow. |
 | **Jira integration** | `server/jira/*` (`jira-sync-manager`, `jira-client`, `jira-materializer`, `jira-status-resolver`, `jira-db`, `jira-credential-store`), `server/jira-router.ts` | Optional per-project sync that backs a project's specs with a Jira board (Cloud or Data Center). Desktop is the sync layer — specrails-core reads the materialized cache unchanged and stays read-only. Inbound polling + a durable outbox handle write-back; the encrypted token lives on-device. Routes under `/api/projects/:id/jira/*` (gated by `SPECRAILS_JIRA_SECTION`, 404 when off); project-scoped WS events `jira.synced`, `jira.sync_error`, `jira.auth_expired`, `jira.outbox_changed`, `jira.degraded`. See [`../jira-integration-plan.md`](../jira-integration-plan.md). |
 | **Theme system** | `server/desktop-router.ts` (`GET/PATCH /api/theme`) | Five built-in themes (`dracula`, `aurora-light`, `obsidian-dark`, `matrix`, `specrails`), default `specrails`, persisted app-wide with an anti-FOUC inline script. |
 

package/docs/internals/browser-capture-performance.md

@@ -8,10 +8,10 @@ The Playwright capture engine backs **Add Spec → From a website** (`BrowserCap
 Chromium (headless, persistent shared context — browser-context-pool.ts)
   │  CDP Page.startScreencast (JPEG frames)          Playwright input API
   ▼                                                   ▲
-PlaywrightPageHandle (server/browser-playwright.ts)   │
+PlaywrightPageHandle (server/modules/browser/runtime/browser-playwright.ts)   │
   │  ScreencastFrame (raw JPEG Buffer)                │ dispatchInput
   ▼                                                   │
-BrowserCaptureManager (server/browser-capture-manager.ts)
+BrowserCaptureManager (server/modules/browser/runtime/browser-capture-manager.ts)
   │  binary WS frames (dedicated /ws/browser/:id)     │ JSON control {type:'input'|'probe'}
   ▼                                                   │
 useBrowserCaptureSession (client)  ───────────────────┘
@@ -119,7 +119,7 @@ Pop-ups now work end-to-end — the design:
 
 ## Verification
 
-Unit coverage: `server/browser-capture-manager.test.ts` (deferred nav, conflation, full popup lifecycle), `server/browser-playwright.test.ts` (`screencastParams`), `server/project-router.browser.test.ts` (popup-view route), `client/src/lib/browser-frame-pipeline.test.ts` (latest-wins/drop/dispose/stats), `client/src/lib/browser-capture.test.ts` (coalescer, popup helpers).
+Unit coverage: `server/modules/browser/runtime/browser-capture-manager.test.ts` (deferred nav, conflation, full popup lifecycle), `server/modules/browser/runtime/browser-playwright.test.ts` (`screencastParams`), `server/project-router.browser.test.ts` (popup-view route), `client/src/features/browser/lib/browser-frame-pipeline.test.ts` (latest-wins/drop/dispose/stats), `client/src/features/browser/lib/browser-capture.test.ts` (coalescer, popup helpers).
 
 `node scripts/smoke-browser-rendering.mjs` exercises the real exported Playwright
 handle using generated pages and temporary profiles, with no Specrails DB or

package/docs/internals/code-explorer-story.md

@@ -40,12 +40,12 @@ to the Code explorer.
 | `summary_model`, `summary_generated_at` | generation metadata |
 
 Stats rows are written **inside `recordProvenanceForJob`'s transaction**
-(`server/file-provenance.ts`), for every provenance row that has a collected
+(`server/modules/code/runtime/file-provenance.ts`), for every provenance row that has a collected
 patch. That means every producer — QueueManager jobs AND the loop seam — gets
 stats with zero extra calls. The prepare is guarded (like the migration-23
 `insertPatch`) so a pre-37 DB degrades cleanly.
 
-## The loop-run seam (`server/file-story.ts`)
+## The loop-run seam (`server/modules/code/runtime/file-story.ts`)
 
 `recordLoopRunProvenance({ db, projectId, runId, ticketId, repoDir, snapshot,
 broadcast })` is the single chokepoint that mirrors QueueManager's

package/docs/internals/companion-rails-as-loops-contract.md

@@ -6,10 +6,10 @@
 
 The single fact that scopes the whole gap, verified directly in code:
 
-`server/rails-router.ts:301` — `if (isLoopsEnabled() && loopId) → LoopRunManager (loop.run_*, no jobId); else → QueueManager (jobId, rail.job_*)`.
+`server/modules/delivery/runtime/rails-router.ts:301` — `if (isLoopsEnabled() && loopId) → LoopRunManager (loop.run_*, no jobId); else → QueueManager (jobId, rail.job_*)`.
 
 - **Phone-initiated launches** send bare `{mode}` with **no `loopId`** (`desktop_repository.dart:116-123`) → fall to the **`else` / QueueManager** path → real `jobId` → `rail.job_*` → **the v1 companion mirrors them correctly (view + log tail + completion push). NO regression.**
-- **Desktop-initiated launches** now **always** send a `loopId`: the loop picker uses `effectiveLoopId = selectedLoopId || factoryIdForMode(mode)` (`client/src/lib/rail-loops.ts:43-44`) so even a plain "Implement" rail sends `loopId='factory:implement'`, and `doLaunchRail` always passes it (`client/src/pages/DashboardPage.tsx:824,869`) → **LoopRunManager** → `loop.run_*` (no `jobId`) → **dropped at the mobile boundary** (`mobile-ws.ts topicFor` default→null).
+- **Desktop-initiated launches** now **always** send a `loopId`: the loop picker uses `effectiveLoopId = selectedLoopId || factoryIdForMode(mode)` (`client/src/features/rails/lib/rail-loops.ts:43-44`) so even a plain "Implement" rail sends `loopId='factory:implement'`, and `doLaunchRail` always passes it (`client/src/features/dashboard/pages/DashboardPage.tsx:824,869`) → **LoopRunManager** → `loop.run_*` (no `jobId`) → **dropped at the mobile boundary** (`mobile-ws.ts topicFor` default→null).
 
 **Net:** the mirror gap is NOT in the phone's own launches — it is in **mirroring rails the user launches from the desktop** (the normal case), which now emit `loop.run_*` the boundary never forwards. So a connected phone shows desktop-launched loop rails as **idle, with no live progress and no completion notification.** The frozen wire is untouched (additive only). Everything below stands with this scoping.