specrails-desktop 2.46.0 → 2.48.0

package/client/dist/assets/wrench-BfmNO9Vw.js

@@ -0,0 +1 @@
+import{t as e}from"./createLucideIcon-Bjbbp_KS.js";var t=e(`wrench`,[[`path`,{d:`M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.106-3.105c.32-.322.863-.22.983.218a6 6 0 0 1-8.259 7.057l-7.91 7.91a1 1 0 0 1-2.999-3l7.91-7.91a6 6 0 0 1 7.057-8.259c.438.12.54.662.219.984z`,key:`1ngwbx`}]]);export{t};

package/client/dist/index.html

@@ -204,20 +204,20 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-DYoyDWim.js"></script>
+    <script type="module" crossorigin src="/assets/index-DORCrgbI.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">
     <link rel="modulepreload" crossorigin href="/assets/preload-helper-Czpn1I53.js">
     <link rel="modulepreload" crossorigin href="/assets/chunk-KS7C4IRE-DEKu087k.js">
     <link rel="modulepreload" crossorigin href="/assets/activity-DiyjsgQV.js">
-    <link rel="modulepreload" crossorigin href="/assets/addspec-D2YIQ0GU.js">
+    <link rel="modulepreload" crossorigin href="/assets/addspec-BOvgmcgk.js">
     <link rel="modulepreload" crossorigin href="/assets/agent-Bh9K7iEt.js">
-    <link rel="modulepreload" crossorigin href="/assets/agentRuntime-D4RmeuNY.js">
-    <link rel="modulepreload" crossorigin href="/assets/agents-ms7TwG16.js">
+    <link rel="modulepreload" crossorigin href="/assets/agentRuntime-bAAjw1vw.js">
+    <link rel="modulepreload" crossorigin href="/assets/agents-CTwbx-fb.js">
     <link rel="modulepreload" crossorigin href="/assets/agentstudio-CN2pokQu.js">
     <link rel="modulepreload" crossorigin href="/assets/aiedit-iIjz2_Qk.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-BMzCvrCU.js">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-BlypLLR6.js">
     <link rel="modulepreload" crossorigin href="/assets/attachments-B53PG733.js">
     <link rel="modulepreload" crossorigin href="/assets/browser-CG0PE1j_.js">
     <link rel="modulepreload" crossorigin href="/assets/builder-BTiGnPT0.js">
@@ -225,33 +225,34 @@
     <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-BfBir_6o.js">
+    <link rel="modulepreload" crossorigin href="/assets/dashboard-DBAP2_SQ.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">
-    <link rel="modulepreload" crossorigin href="/assets/jobs-DMPU64ms.js">
+    <link rel="modulepreload" crossorigin href="/assets/jobs-C9j2PuwW.js">
     <link rel="modulepreload" crossorigin href="/assets/loops-B7YpGizO.js">
     <link rel="modulepreload" crossorigin href="/assets/mcp-CUAN6ORK.js">
-    <link rel="modulepreload" crossorigin href="/assets/narration-Dypjxeel.js">
+    <link rel="modulepreload" crossorigin href="/assets/narration-n3hOA7LY.js">
     <link rel="modulepreload" crossorigin href="/assets/nav-Ch-zHBG5.js">
-    <link rel="modulepreload" crossorigin href="/assets/packet-Cx-zRuWn.js">
-    <link rel="modulepreload" crossorigin href="/assets/settings-BlYvaQ7w.js">
-    <link rel="modulepreload" crossorigin href="/assets/setup-Ba11l2JA.js">
+    <link rel="modulepreload" crossorigin href="/assets/packet-_m5aOy_d.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-DII0C8gw.js">
     <link rel="modulepreload" crossorigin href="/assets/terminal-BAzpHtpY.js">
     <link rel="modulepreload" crossorigin href="/assets/tickets-W6pBmbrX.js">
     <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-Bjbbp_KS.js">
-    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-DnxHj8jP.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-BwLgX6n7.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-mxHVQOdx.js">
+    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-BHIfW4QT.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-9pHTy2fH.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-CAisjKWC.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-DNM6NAoA.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-hcgxHP4O.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-B6wVevPq.js">
-    <link rel="modulepreload" crossorigin href="/assets/file-text-BcLCfcWZ.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-UpnqccPx.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-x-CMYsN4ZH.js">
     <link rel="modulepreload" crossorigin href="/assets/download-CFHyyHcw.js">
+    <link rel="modulepreload" crossorigin href="/assets/file-text-CFT-xXKN.js">
     <link rel="modulepreload" crossorigin href="/assets/git-branch-BRM0F5GN.js">
     <link rel="modulepreload" crossorigin href="/assets/loader-circle-DcygOQpC.js">
     <link rel="modulepreload" crossorigin href="/assets/pencil-C9RkrIPZ.js">
@@ -260,24 +261,24 @@
     <link rel="modulepreload" crossorigin href="/assets/search-Cq_gE3Ik.js">
     <link rel="modulepreload" crossorigin href="/assets/trash-2-BOU3WdZZ.js">
     <link rel="modulepreload" crossorigin href="/assets/triangle-alert-H9T4jAmh.js">
-    <link rel="modulepreload" crossorigin href="/assets/jira-api-ChjVGJx_.js">
+    <link rel="modulepreload" crossorigin href="/assets/wrench-BfmNO9Vw.js">
     <link rel="modulepreload" crossorigin href="/assets/zap-CHo3aCD1.js">
     <link rel="modulepreload" crossorigin href="/assets/clsx-CjueKrWZ.js">
     <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-DxAkjvJb.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-CeZv93iR.js">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-BRymg1Kk.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-w_2U5pm0.js">
     <link rel="modulepreload" crossorigin href="/assets/button-Ccc9Dc-D.js">
-    <link rel="modulepreload" crossorigin href="/assets/project-repositories-BvBj9XH9.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-DnAFtjTz.js">
-    <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-CXipwrXJ.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-B1X5glzV.js">
+    <link rel="modulepreload" crossorigin href="/assets/jira-api-BqHbSdxK.js">
+    <link rel="modulepreload" crossorigin href="/assets/project-repositories-BsCs1PPA.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-0Gz_fR1E.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-C5GgJlEt.js">
     <link rel="modulepreload" crossorigin href="/assets/core-B3mKBIh5.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-BQm_3TO8.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-C36ipKp_.js">
     <link rel="modulepreload" crossorigin href="/assets/format-duration-NJVPOPBG.js">
     <link rel="modulepreload" crossorigin href="/assets/event-Bt7f3wXe.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-Cfh9aaep.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-D0ScFZvR.css">
   </head>
   <body>
     <div id="specrails-splash" aria-hidden="false" role="status" aria-label="Loading Specrails">

package/docs/guide/de/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# Lokale KI-Engines
+
+Betreibe Specrails mit Modellen, die du selbst hostest — Ollama, llama.cpp, LM Studio, vLLM oder jeder Server, der die OpenAI-Chat-Completions-API spricht. Einmal verbunden ist ein lokaler Endpunkt eine Engine wie jede andere: Er erscheint in der Rail-Kopfzeile, in Spec hinzufügen (Quick und Explore), im Seitenleisten-Chat und in Agenten-Missionen.
+
+## Endpunkt verbinden
+
+1. Öffne **Einstellungen ▸ Specrails-Agenten ▸ Provider-Verbindungen** und wähle **Lokale Engine hinzufügen**.
+2. Gib eine ID, die Basis-URL (z. B. `http://127.0.0.1:11434/v1`) und, falls dein Server einen Schlüssel braucht, den **Namen der Umgebungsvariable** an, die ihn enthält. Der Schlüssel wird nie gespeichert — Specrails liest ihn beim Start jedes Laufs aus der Umgebung der App.
+3. Klicke auf **Verbindung testen**. Die Pille wird grün, sobald der Server antwortet, und die bereitgestellten Modelle werden aufgelistet. Wähle ein Standardmodell.
+4. **Speichern**. Die Engine ist sofort verfügbar — kein Neustart nötig.
+
+> Wird die App über Finder, Dock oder Startmenü gestartet, werden Shell-Exports nicht übernommen. Meldet die Karte, die Variable sei *im App-Prozess nicht gesetzt*, setze sie systemweit oder starte die App aus einem Terminal, das sie kennt. Server ohne Schlüssel brauchen nichts davon.
+
+Jede Verbindung hat außerdem die Einstellung **Agenten-Schleife**. **Kompakt** (Standard) führt kleine Modelle durch kurze, strukturierte Schritte – damit schafft ein 7–14B-Modell den Implement-Lauf; **Frei** ist die klassische einzelne Agentenschleife für starke Modelle (~30B+). Setze das **Kontextfenster** auf die echte Größe deines Servers, damit Specrails komprimiert, bevor der Server eine Anfrage ablehnt.
+
+## Was du bekommst
+
+- Rails (implement, batch, freestyle, eigene Loops), Explore und Quick-Specs, Chat und Missionen laufen auf dem lokalen Modell.
+- Missionen behalten ihre Specrails-Tools und deine externen MCP-Server.
+- Sitzungen werden über Turns hinweg fortgesetzt; interaktive Jobs funktionieren.
+- Kosten sind ehrlich: Tokens werden erfasst, die Kosten bleiben *unbekannt*, sofern du keine Tarife einträgst (dann als *geschätzt* markiert).
+
+Auf lokalen Engines nicht verfügbar: Agentenprofile und eigene Rollen, SMASH-/Contract-Layer-Anreicherung, Anhänge und Pipeline-Telemetrie. Der Project Builder läuft im reinen Ausgabemodus (ohne Tools); sein Blueprint-Vertrag ist streng, nutze also ein leistungsfähiges Modell.
+
+> Missionen brauchen ein **großes Kontextfenster** auf dem Server (64k Tokens oder mehr): Operator-Prompt plus Specrails-Tool-Schemas sind umfangreich. Chat und Explore kommen mit 32k aus. Schlägt ein Turn mit *exceeds the available context size* fehl, vergrößere das Fenster (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
+
+## Nur eine lokale Engine installiert?
+
+Nichts zu konfigurieren. Specrails bietet die Engines an, die deine Maschine tatsächlich ausführen kann, und wählt den Standard überall nach derselben Regel: eine installierte CLI (Claude → Codex → Gemini → Kimi), sonst die erste lokale Engine, deren Endpoint antwortet. Auf einer Maschine mit nur einem lokalen Endpoint starten Rails, Add Spec, Chat, **Agent-Missionen und der Project Builder** darauf — kein Selektor nötig. Eine Engine, deren Server nicht läuft, wird schlicht nicht angeboten, bis sie wieder antwortet. Bestehende Missionen behalten die Engine, mit der sie erstellt wurden; der Selektor erlaubt weiterhin den Wechsel.
+
+## Modell wählen
+
+Die Qualität hängt vom Modell ab, nicht von Specrails. Nutze für Rails ein auf Tool-Calling trainiertes Coder-Modell mit mindestens 30B Parametern; kleinere Instruct-Modelle reichen für Chat, Explore und Quick-Specs. Probiere **Freestyle** oder eine Explore-Sitzung, bevor du einem neuen Modell einen kompletten Implement-Rail anvertraust.
+
+## Abschalten
+
+Setze `SPECRAILS_LOCAL_ENGINES=false` in der App-Umgebung, um lokale Engines überall auszublenden. Gespeicherte Verbindungen bleiben erhalten und gelten weiterhin als Rollen-Provider der programmatischen Runtime.

package/docs/guide/en/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# Local AI engines
+
+Run Specrails on models you host yourself — Ollama, llama.cpp, LM Studio, vLLM or any server that speaks the OpenAI chat-completions API. Once connected, a local endpoint is an engine like any other: it shows up in the rail header, Add Spec (Quick and Explore), the sidebar chat and agent missions.
+
+## Connect an endpoint
+
+1. Open **Settings ▸ Specrails Agents ▸ Provider connections** and choose **Add local engine**.
+2. Enter an id, the base URL (for example `http://127.0.0.1:11434/v1`) and, if your server needs a key, the **name of the environment variable** that holds it. The key is never stored — Specrails reads it from the app's environment when it starts a run.
+3. Press **Test connection**. The pill turns green when the server answers and the models it serves are listed. Pick a default model.
+4. **Save**. The engine is available right away — no restart.
+
+> Launching the app from Finder, the Dock or the Start menu does not inherit shell exports. If the card says the variable is *not set in the app process*, set it system-wide or start the app from a terminal that has it. Servers without a key need nothing.
+
+Each connection also has an **Agent loop** setting. **Compact** (default) drives small models through short structured steps and is what makes a 7–14B model get through implement; **Free** is the classic single agent loop for strong (~30B+) models. Set the **context window** to your server's real size so Specrails compacts before the server rejects a request.
+
+## What you get
+
+- Rails (implement, batch, freestyle, custom loops), Explore and Quick specs, chat and missions all run on the local model.
+- Missions keep their Specrails tools and your external MCP servers.
+- Sessions resume across turns; interactive jobs work.
+- Cost is honest: tokens are recorded, cost stays *unknown* unless you enter rates (then it is marked *estimated*).
+
+Not available on local engines: agent profiles and custom roles, SMASH / Contract Layer enrichment, attachments and pipeline telemetry. The Project Builder works in pure-output mode (no tools) — its blueprint contract is strict, so use a capable model.
+
+> Missions need a **large context window** on the server (64k tokens or more): the operator prompt plus the Specrails tool schemas are big. Chat and Explore are fine at 32k. If a turn fails with *exceeds the available context size*, raise the window (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
+
+## Only a local engine installed?
+
+Nothing to configure. Specrails offers the engines your machine can actually run and picks the default with one rule everywhere: an installed CLI (Claude → Codex → Gemini → Kimi), otherwise the first local engine whose endpoint answers. On a machine with just a local endpoint, rails, Add Spec, chat, **agent missions and the Project Builder** all start on it — no selector to touch. An engine whose server is down is simply not offered until it answers again. Existing missions keep the engine they were created on; the selector still lets you switch.
+
+## Choosing a model
+
+Quality depends on the model, not on Specrails. For rails use a tool-calling-tuned coder model of 30B parameters or more; smaller instruct models are fine for chat, Explore and Quick specs. Try **Freestyle** or an Explore session before trusting a full implement rail to a new model.
+
+## Turning it off
+
+Set `SPECRAILS_LOCAL_ENGINES=false` in the app environment to hide local engines everywhere. Saved connections are kept and still work as per-role providers of the programmatic runtime.

package/docs/guide/es/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# Motores de IA locales
+
+Ejecuta Specrails con modelos que alojas tú — Ollama, llama.cpp, LM Studio, vLLM o cualquier servidor que hable la API de chat-completions de OpenAI. Una vez conectado, un endpoint local es un motor como cualquier otro: aparece en la cabecera del rail, en Añadir spec (Quick y Explore), en el chat lateral y en las misiones del agente.
+
+## Conectar un endpoint
+
+1. Abre **Ajustes ▸ Agentes Specrails ▸ Conexiones de proveedor** y elige **Añadir motor local**.
+2. Indica un id, la URL base (por ejemplo `http://127.0.0.1:11434/v1`) y, si tu servidor necesita clave, el **nombre de la variable de entorno** que la contiene. La clave nunca se guarda: Specrails la lee del entorno de la app al iniciar cada ejecución.
+3. Pulsa **Probar conexión**. La píldora se pone verde cuando el servidor responde y se listan los modelos que sirve. Elige un modelo por defecto.
+4. **Guardar**. El motor queda disponible al instante, sin reiniciar.
+
+> Al abrir la app desde Finder, el Dock o el menú Inicio no se heredan los exports de la shell. Si la tarjeta dice que la variable *no está definida en el proceso de la app*, defínela a nivel de sistema o arranca la app desde un terminal que la tenga. Los servidores sin clave no necesitan nada.
+
+Cada conexión tiene además un ajuste **Bucle del agente**. **Compacto** (por defecto) guía a los modelos pequeños con pasos cortos y estructurados: es lo que permite que un modelo de 7–14B supere el implement; **Libre** es el bucle agéntico clásico para modelos potentes (~30B+). Ajusta la **ventana de contexto** al tamaño real de tu servidor para que Specrails compacte antes de que el servidor rechace una petición.
+
+## Qué obtienes
+
+- Rails (implement, batch, freestyle, loops personalizados), Explore y specs Quick, chat y misiones se ejecutan con el modelo local.
+- Las misiones conservan sus herramientas Specrails y tus servidores MCP externos.
+- Las sesiones se reanudan entre turnos; los jobs interactivos funcionan.
+- El coste es honesto: se registran los tokens, el coste queda *desconocido* salvo que indiques tarifas (entonces se marca *estimado*).
+
+No disponible en motores locales: perfiles de agente y roles personalizados, enriquecimiento SMASH / Contract Layer, adjuntos y telemetría del pipeline. El Project Builder funciona en modo solo-salida (sin herramientas); su contrato de blueprint es estricto, así que usa un modelo capaz.
+
+> Las misiones necesitan una **ventana de contexto grande** en el servidor (64k tokens o más): el prompt del operador más los schemas de herramientas de Specrails ocupan mucho. Chat y Explore van bien con 32k. Si un turno falla con *exceeds the available context size*, amplía la ventana (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
+
+## ¿Solo tienes un motor local?
+
+No hay nada que configurar. Specrails ofrece los motores que tu máquina puede ejecutar de verdad y elige el predeterminado con una única regla en todas partes: un CLI instalado (Claude → Codex → Gemini → Kimi) o, si no hay ninguno, el primer motor local cuyo endpoint responda. En una máquina con solo un endpoint local, los rails, Add Spec, el chat, **las misiones del agente y el Project Builder** arrancan en él sin tocar ningún selector. Un motor cuyo servidor está caído simplemente no se ofrece hasta que vuelva a responder. Las misiones existentes conservan el motor con el que se crearon; el selector sigue permitiendo cambiarlo.
+
+## Elegir modelo
+
+La calidad depende del modelo, no de Specrails. Para rails usa un modelo de código afinado para tool calling de 30B parámetros o más; los modelos instruct pequeños valen para chat, Explore y specs Quick. Prueba **Freestyle** o una sesión Explore antes de confiar un rail implement completo a un modelo nuevo.
+
+## Desactivarlo
+
+Define `SPECRAILS_LOCAL_ENGINES=false` en el entorno de la app para ocultar los motores locales en todas partes. Las conexiones guardadas se conservan y siguen valiendo como proveedores por rol del runtime programático.

package/docs/guide/fr/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# Moteurs d'IA locaux
+
+Faites tourner Specrails sur des modèles que vous hébergez vous-même — Ollama, llama.cpp, LM Studio, vLLM ou tout serveur parlant l'API chat-completions d'OpenAI. Une fois connecté, un endpoint local est un moteur comme les autres : il apparaît dans l'en-tête du rail, dans Ajouter une spec (Quick et Explore), dans le chat latéral et dans les missions de l'agent.
+
+## Connecter un endpoint
+
+1. Ouvrez **Réglages ▸ Agents Specrails ▸ Connexions de fournisseur** puis **Ajouter un moteur local**.
+2. Saisissez un id, l'URL de base (par exemple `http://127.0.0.1:11434/v1`) et, si votre serveur exige une clé, le **nom de la variable d'environnement** qui la contient. La clé n'est jamais enregistrée : Specrails la lit dans l'environnement de l'application au lancement de chaque exécution.
+3. Cliquez sur **Tester la connexion**. La pastille devient verte quand le serveur répond et les modèles servis sont listés. Choisissez un modèle par défaut.
+4. **Enregistrer**. Le moteur est disponible immédiatement, sans redémarrage.
+
+> Lancer l'application depuis le Finder, le Dock ou le menu Démarrer n'hérite pas des exports du shell. Si la carte indique que la variable *n'est pas définie dans le processus de l'application*, définissez-la au niveau système ou lancez l'application depuis un terminal qui la possède. Les serveurs sans clé n'ont besoin de rien.
+
+Chaque connexion possède aussi un réglage **Boucle de l'agent**. **Compacte** (par défaut) guide les petits modèles par de courtes étapes structurées : c'est ce qui permet à un modèle de 7–14B de passer l'implement ; **Libre** est la boucle agentique classique pour les modèles puissants (~30B+). Réglez la **fenêtre de contexte** sur la taille réelle de votre serveur pour que Specrails compacte avant que le serveur ne rejette une requête.
+
+## Ce que vous obtenez
+
+- Rails (implement, batch, freestyle, boucles personnalisées), Explore et specs Quick, chat et missions s'exécutent sur le modèle local.
+- Les missions conservent leurs outils Specrails et vos serveurs MCP externes.
+- Les sessions reprennent d'un tour à l'autre ; les jobs interactifs fonctionnent.
+- Le coût est honnête : les tokens sont enregistrés, le coût reste *inconnu* sauf si vous saisissez des tarifs (il est alors marqué *estimé*).
+
+Indisponible sur les moteurs locaux : profils d'agent et rôles personnalisés, enrichissement SMASH / Contract Layer, pièces jointes et télémétrie du pipeline. Le Project Builder fonctionne en mode sortie pure (sans outils) ; son contrat de blueprint est strict, utilisez donc un modèle capable.
+
+> Les missions exigent une **grande fenêtre de contexte** côté serveur (64k tokens ou plus) : le prompt de l'opérateur et les schémas d'outils Specrails sont volumineux. Chat et Explore fonctionnent à 32k. Si un tour échoue avec *exceeds the available context size*, augmentez la fenêtre (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
+
+## Seulement un moteur local ?
+
+Rien à configurer. Specrails propose les moteurs que votre machine peut réellement exécuter et choisit la valeur par défaut avec une seule règle partout : un CLI installé (Claude → Codex → Gemini → Kimi), sinon le premier moteur local dont l'endpoint répond. Sur une machine n'ayant qu'un endpoint local, les rails, Add Spec, le chat, **les missions de l'agent et le Project Builder** démarrent dessus, sans toucher au sélecteur. Un moteur dont le serveur est arrêté n'est simplement pas proposé tant qu'il ne répond pas. Les missions existantes gardent le moteur avec lequel elles ont été créées ; le sélecteur permet toujours d'en changer.
+
+## Choisir un modèle
+
+La qualité dépend du modèle, pas de Specrails. Pour les rails, utilisez un modèle de code entraîné au tool calling d'au moins 30B paramètres ; les petits modèles instruct suffisent pour le chat, Explore et les specs Quick. Essayez **Freestyle** ou une session Explore avant de confier un rail implement complet à un nouveau modèle.
+
+## Désactiver
+
+Définissez `SPECRAILS_LOCAL_ENGINES=false` dans l'environnement de l'application pour masquer les moteurs locaux partout. Les connexions enregistrées sont conservées et restent valables comme fournisseurs par rôle du runtime programmatique.

package/docs/guide/it/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# Motori di IA locali
+
+Esegui Specrails su modelli che ospiti tu stesso — Ollama, llama.cpp, LM Studio, vLLM o qualsiasi server che parli l'API chat-completions di OpenAI. Una volta collegato, un endpoint locale è un motore come gli altri: compare nell'intestazione del rail, in Aggiungi spec (Quick ed Explore), nella chat laterale e nelle missioni dell'agente.
+
+## Collegare un endpoint
+
+1. Apri **Impostazioni ▸ Agenti Specrails ▸ Connessioni provider** e scegli **Aggiungi motore locale**.
+2. Inserisci un id, l'URL base (per esempio `http://127.0.0.1:11434/v1`) e, se il server richiede una chiave, il **nome della variabile d'ambiente** che la contiene. La chiave non viene mai salvata: Specrails la legge dall'ambiente dell'app all'avvio di ogni esecuzione.
+3. Premi **Prova connessione**. La spia diventa verde quando il server risponde e vengono elencati i modelli serviti. Scegli un modello predefinito.
+4. **Salva**. Il motore è subito disponibile, senza riavvio.
+
+> Avviare l'app da Finder, Dock o menu Start non eredita gli export della shell. Se la scheda indica che la variabile *non è impostata nel processo dell'app*, impostala a livello di sistema o avvia l'app da un terminale che la conosce. I server senza chiave non hanno bisogno di nulla.
+
+Ogni connessione ha anche l'impostazione **Loop dell'agente**. **Compatto** (predefinito) guida i modelli piccoli con passi brevi e strutturati: è ciò che permette a un modello da 7–14B di superare l'implement; **Libero** è il classico loop agentico per modelli potenti (~30B+). Imposta la **finestra di contesto** alla dimensione reale del server così Specrails compatta prima che il server rifiuti una richiesta.
+
+## Cosa ottieni
+
+- Rails (implement, batch, freestyle, loop personalizzati), Explore e spec Quick, chat e missioni girano sul modello locale.
+- Le missioni mantengono i loro strumenti Specrails e i tuoi server MCP esterni.
+- Le sessioni riprendono tra un turno e l'altro; i job interattivi funzionano.
+- Il costo è onesto: i token vengono registrati, il costo resta *sconosciuto* a meno che tu non inserisca tariffe (allora è contrassegnato come *stimato*).
+
+Non disponibile sui motori locali: profili agente e ruoli personalizzati, arricchimento SMASH / Contract Layer, allegati e telemetria della pipeline. Il Project Builder funziona in modalità solo-output (senza strumenti); il suo contratto di blueprint è rigido, quindi usa un modello capace.
+
+> Le missioni richiedono una **finestra di contesto ampia** sul server (64k token o più): il prompt dell'operatore più gli schemi degli strumenti Specrails sono grandi. Chat ed Explore vanno bene a 32k. Se un turno fallisce con *exceeds the available context size*, aumenta la finestra (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
+
+## Hai solo un motore locale?
+
+Niente da configurare. Specrails offre i motori che la tua macchina può davvero eseguire e sceglie il predefinito con un'unica regola ovunque: una CLI installata (Claude → Codex → Gemini → Kimi), altrimenti il primo motore locale il cui endpoint risponde. Su una macchina con il solo endpoint locale, rail, Add Spec, chat, **missioni dell'agente e Project Builder** partono su di esso — nessun selettore da toccare. Un motore con il server spento semplicemente non viene offerto finché non risponde di nuovo. Le missioni esistenti mantengono il motore con cui sono state create; il selettore permette comunque di cambiarlo.
+
+## Scegliere il modello
+
+La qualità dipende dal modello, non da Specrails. Per i rail usa un modello di codice addestrato al tool calling da 30B parametri o più; i modelli instruct piccoli bastano per chat, Explore e spec Quick. Prova **Freestyle** o una sessione Explore prima di affidare un rail implement completo a un modello nuovo.
+
+## Disattivare
+
+Imposta `SPECRAILS_LOCAL_ENGINES=false` nell'ambiente dell'app per nascondere ovunque i motori locali. Le connessioni salvate restano e continuano a valere come provider per ruolo del runtime programmatico.

package/docs/guide/ja/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# ローカル AI エンジン
+
+自分でホストしたモデル（Ollama、llama.cpp、LM Studio、vLLM、または OpenAI chat-completions API を話す任意のサーバー）で Specrails を動かせます。接続すると、ローカルエンドポイントは他と同じエンジンになります。レールのヘッダー、スペック追加（Quick と Explore）、サイドバーチャット、エージェントミッションに表示されます。
+
+## エンドポイントを接続する
+
+1. **設定 ▸ Specrails エージェント ▸ プロバイダー接続** を開き、**ローカルエンジンを追加** を選びます。
+2. id、ベース URL（例 `http://127.0.0.1:11434/v1`）を入力し、サーバーがキーを必要とする場合はキーを保持する**環境変数名**を入力します。キー自体は保存されません。Specrails は実行開始時にアプリの環境から読み取ります。
+3. **接続をテスト** を押します。サーバーが応答するとピルが緑になり、提供モデルが一覧表示されます。デフォルトモデルを選びます。
+4. **保存**。エンジンはすぐに使えます。再起動は不要です。
+
+> Finder、Dock、スタートメニューからアプリを起動すると、シェルの export は引き継がれません。カードに変数が*アプリプロセスに設定されていない*と表示される場合は、システム全体で設定するか、その変数を持つターミナルからアプリを起動してください。キー不要のサーバーには何も必要ありません。
+
+各接続には **エージェントループ** の設定もあります。**コンパクト**（既定）は小さなモデルを短い構造化ステップで導き、7–14B のモデルでも implement を完走させます。**フリー** は強力なモデル（約 30B 以上）向けの従来型の単一エージェントループです。**コンテキストウィンドウ** はサーバーの実際のサイズに合わせてください。サーバーがリクエストを拒否する前に Specrails が圧縮します。
+
+## できること
+
+- レール（implement、batch、freestyle、カスタムループ）、Explore と Quick スペック、チャット、ミッションがローカルモデルで動作します。
+- ミッションは Specrails ツールと外部 MCP サーバーをそのまま使えます。
+- セッションはターンをまたいで再開でき、インタラクティブジョブも動作します。
+- コストは正直です。トークンは記録され、レートを入力しない限りコストは*不明*のまま（入力すると*推定*と表示）。
+
+ローカルエンジンで利用不可：エージェントプロファイルとカスタムロール、SMASH / Contract Layer の拡充、添付ファイル、パイプラインテレメトリ。Project Builder はツールなしの純出力モードで動作します。ブループリントの契約は厳格なので、十分に高性能なモデルを使ってください。
+
+> ミッションにはサーバー側に**大きなコンテキストウィンドウ**（64k トークン以上）が必要です。オペレータープロンプトと Specrails ツールのスキーマは大きいためです。チャットと Explore は 32k で十分です。ターンが *exceeds the available context size* で失敗する場合は、ウィンドウを拡大してください（Ollama `OLLAMA_CONTEXT_LENGTH`、llama.cpp `-c`、LM Studio *Context Length*）。
+
+## ローカルエンジンしかない場合は？
+
+設定は不要です。Specrails はマシンが実際に実行できるエンジンだけを提示し、既定値はどこでも同じ規則で選びます。インストール済み CLI（Claude → Codex → Gemini → Kimi）、なければエンドポイントが応答する最初のローカルエンジンです。ローカルエンドポイントしかないマシンでは、レール、Add Spec、チャット、**エージェントのミッションと Project Builder** がそのままそのエンジンで始まり、セレクターに触れる必要はありません。サーバーが停止しているエンジンは、再び応答するまで提示されません。既存のミッションは作成時のエンジンを保持し、セレクターで切り替えることもできます。
+
+## モデルの選び方
+
+品質は Specrails ではなくモデル次第です。レールには 30B パラメータ以上のツール呼び出し対応コーダーモデルを使ってください。小さな instruct モデルはチャット、Explore、Quick スペックには十分です。新しいモデルに implement レール全体を任せる前に、**Freestyle** か Explore セッションで試してください。
+
+## 無効化
+
+アプリ環境で `SPECRAILS_LOCAL_ENGINES=false` を設定すると、ローカルエンジンはすべての場所から消えます。保存済みの接続は保持され、プログラマティックランタイムのロール別プロバイダーとしては引き続き有効です。

package/docs/guide/pt/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# Motores de IA locais
+
+Execute o Specrails com modelos hospedados por você — Ollama, llama.cpp, LM Studio, vLLM ou qualquer servidor que fale a API chat-completions da OpenAI. Uma vez conectado, um endpoint local é um motor como qualquer outro: aparece no cabeçalho do rail, em Adicionar spec (Quick e Explore), no chat lateral e nas missões do agente.
+
+## Conectar um endpoint
+
+1. Abra **Configurações ▸ Agentes Specrails ▸ Conexões de provedor** e escolha **Adicionar motor local**.
+2. Informe um id, a URL base (por exemplo `http://127.0.0.1:11434/v1`) e, se o servidor exigir chave, o **nome da variável de ambiente** que a contém. A chave nunca é armazenada — o Specrails a lê do ambiente do app ao iniciar cada execução.
+3. Clique em **Testar conexão**. O indicador fica verde quando o servidor responde e os modelos disponíveis são listados. Escolha um modelo padrão.
+4. **Salvar**. O motor fica disponível na hora — sem reiniciar.
+
+> Abrir o app pelo Finder, Dock ou menu Iniciar não herda os exports do shell. Se o cartão disser que a variável *não está definida no processo do app*, defina-a no sistema ou inicie o app por um terminal que a tenha. Servidores sem chave não precisam de nada disso.
+
+Cada conexão também tem a configuração **Loop do agente**. **Compacto** (padrão) conduz modelos pequenos por passos curtos e estruturados — é o que permite a um modelo de 7–14B concluir o implement; **Livre** é o loop agêntico clássico para modelos fortes (~30B+). Ajuste a **janela de contexto** ao tamanho real do seu servidor para que o Specrails compacte antes que o servidor rejeite um pedido.
+
+## O que você ganha
+
+- Rails (implement, batch, freestyle, loops personalizados), Explore e specs Quick, chat e missões rodam no modelo local.
+- As missões mantêm suas ferramentas Specrails e seus servidores MCP externos.
+- As sessões são retomadas entre turnos; jobs interativos funcionam.
+- O custo é honesto: os tokens são registrados, o custo fica *desconhecido* a menos que você informe tarifas (então é marcado como *estimado*).
+
+Indisponível em motores locais: perfis de agente e papéis personalizados, enriquecimento SMASH / Contract Layer, anexos e telemetria do pipeline. O Project Builder funciona em modo só-saída (sem ferramentas); o contrato do blueprint é rígido, então use um modelo capaz.
+
+> Missões precisam de uma **janela de contexto grande** no servidor (64k tokens ou mais): o prompt do operador mais os schemas de ferramentas do Specrails são grandes. Chat e Explore funcionam bem com 32k. Se um turno falhar com *exceeds the available context size*, aumente a janela (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
+
+## Só tem um motor local?
+
+Nada a configurar. O Specrails oferece os motores que sua máquina realmente consegue executar e escolhe o padrão com uma única regra em todo lugar: um CLI instalado (Claude → Codex → Gemini → Kimi) ou, se não houver, o primeiro motor local cujo endpoint responda. Em uma máquina só com um endpoint local, rails, Add Spec, chat, **missões do agente e o Project Builder** começam nele — sem tocar em nenhum seletor. Um motor cujo servidor está fora do ar simplesmente não é oferecido até voltar a responder. Missões existentes mantêm o motor com que foram criadas; o seletor continua permitindo trocar.
+
+## Escolher um modelo
+
+A qualidade depende do modelo, não do Specrails. Para rails use um modelo de código ajustado para tool calling com 30B parâmetros ou mais; modelos instruct menores servem para chat, Explore e specs Quick. Experimente **Freestyle** ou uma sessão Explore antes de confiar um rail implement completo a um modelo novo.
+
+## Desativar
+
+Defina `SPECRAILS_LOCAL_ENGINES=false` no ambiente do app para ocultar motores locais em toda parte. As conexões salvas são mantidas e continuam válidas como provedores por papel do runtime programático.

package/docs/guide/zh/integrations/7-local-engines.md

@@ -0,0 +1,37 @@
+# 本地 AI 引擎
+
+让 Specrails 运行在你自己托管的模型上——Ollama、llama.cpp、LM Studio、vLLM，或任何支持 OpenAI chat-completions API 的服务器。连接后，本地端点就是一个普通引擎：会出现在 rail 标题栏、添加 spec（Quick 与 Explore）、侧栏聊天和 agent 任务中。
+
+## 连接端点
+
+1. 打开 **设置 ▸ Specrails Agents ▸ 提供商连接**，选择 **添加本地引擎**。
+2. 填写 id、基础 URL（例如 `http://127.0.0.1:11434/v1`），如果服务器需要密钥，填写**保存密钥的环境变量名**。密钥永远不会被保存——Specrails 在每次启动运行时从应用环境读取它。
+3. 点击 **测试连接**。服务器响应后指示灯变绿，并列出其提供的模型。选择一个默认模型。
+4. **保存**。引擎立即可用，无需重启。
+
+> 从 Finder、Dock 或开始菜单启动应用不会继承 shell 的 export。若卡片提示该变量*未在应用进程中设置*，请在系统级别设置它，或从已设置该变量的终端启动应用。无需密钥的服务器不需要任何配置。
+
+每个连接还有一个 **Agent 循环** 设置。**紧凑**（默认）通过简短的结构化步骤驱动小模型，正是它让 7–14B 模型能跑通 implement；**自由** 是面向强模型（约 30B 以上）的经典单一 agent 循环。请把 **上下文窗口** 设为服务器的真实大小，以便 Specrails 在服务器拒绝请求前进行压缩。
+
+## 你将获得
+
+- Rails（implement、batch、freestyle、自定义 loop）、Explore 与 Quick spec、聊天和任务都在本地模型上运行。
+- 任务保留 Specrails 工具和你的外部 MCP 服务器。
+- 会话可跨轮次恢复；交互式 job 可用。
+- 成本诚实：记录 token，除非你填写费率，否则成本显示为*未知*（填写后标记为*估算*）。
+
+本地引擎不支持：agent 配置文件与自定义角色、SMASH / Contract Layer 增强、附件与流水线遥测。Project Builder 以纯输出模式（无工具）运行；其蓝图契约很严格，请使用能力较强的模型。
+
+> 任务需要服务器提供**较大的上下文窗口**（64k token 以上）：operator 提示词加上 Specrails 工具 schema 体积很大。聊天和 Explore 在 32k 下即可。若某轮以 *exceeds the available context size* 失败，请增大窗口（Ollama `OLLAMA_CONTEXT_LENGTH`、llama.cpp `-c`、LM Studio *Context Length*）。
+
+## 只安装了本地引擎？
+
+无需任何配置。Specrails 只提供你的机器真正能运行的引擎，并在所有地方用同一条规则选择默认值：已安装的 CLI（Claude → Codex → Gemini → Kimi），否则是第一个端点有响应的本地引擎。在只有本地端点的机器上，rails、Add Spec、聊天、**agent 任务和 Project Builder** 都会直接在它上面启动，无需碰任何选择器。服务器未运行的引擎在恢复响应前不会被提供。已有任务保留创建时的引擎；选择器仍可切换。
+
+## 选择模型
+
+质量取决于模型而非 Specrails。运行 rails 请使用 30B 参数以上、针对工具调用调优的代码模型；较小的 instruct 模型足以应对聊天、Explore 和 Quick spec。将完整的 implement rail 交给新模型之前，先试试 **Freestyle** 或一次 Explore 会话。
+
+## 关闭
+
+在应用环境中设置 `SPECRAILS_LOCAL_ENGINES=false` 即可在所有位置隐藏本地引擎。已保存的连接会保留，并仍可作为程序化运行时的按角色提供商使用。

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

@@ -385,3 +385,15 @@ papering over it with another manager-level branch.
 - [`docs/codex.md`](../codex.md) and [`docs/gemini.md`](../gemini.md) — the
   user-facing guides for the two non-Claude providers; `gemini.md` is the most
   recent worked example end-to-end.
+
+## Dynamic (non-CLI) adapters
+
+Not every adapter is a static module-load registration. **Local AI engines**
+(`server/providers/local-adapter.ts`) build one adapter per user-configured
+OpenAI-compatible connection at runtime and register/unregister them through
+`syncLocalAdapters` (`local-adapter-registry.ts`) — at boot and after every
+save of `~/.specrails/runtime-providers.json`. Execution is delegated to the
+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`.

package/docs/internals/local-agent-runner.md

@@ -0,0 +1,153 @@
+# Local agent runner (internals)
+
+Contract for `local-runner/` — the bundled process that makes an
+OpenAI-compatible endpoint behave like an agentic CLI for every Desktop spawn
+site. OpenSpec change: `local-ai-engines`.
+
+## Packaging
+
+- Source `local-runner/src/`, bundled by `scripts/build-local-runner.mjs`
+  (esbuild, CJS, node20, SDK bundled) to `local-runner/dist/specrails-local-runner.js`
+  and copied to `src-tauri/binaries/specrails-local-runner.js` (listed in
+  `tauri.conf.json` `bundle.resources`). Same pattern as `specrails-mcp`.
+- Spawned by `server/providers/local-adapter.ts` with the bundled Node
+  (`resolveBundledNodeExe()` → `node` fallback), argv `[<script>, ...flags]`,
+  through `windowsSpawnEnv` + cross-spawn on Windows (pkg sidecar trap: never
+  `process.execPath`).
+- Script resolution order mirrors the MCP bridge: `src-tauri/binaries/…` then
+  `local-runner/dist/…` (dev).
+
+## Argv
+
+| Flag | Meaning |
+|---|---|
+| `-p <prompt>` | one-shot prompt (absent in persistent mode) |
+| `--model <id>` | model id sent verbatim |
+| `--base-url <url>` / `--api-key-env <NAME>` | endpoint + env var holding the bearer key |
+| `--resume <sessionId>` | load a stored session |
+| `--system-prompt` / `--append-system-prompt` | replace / extend the system message |
+| `--tools <csv|__none__>` / `--disallowedTools <csv>` | tool policy |
+| `--max-turns <n>` | tool-loop bound (`result.is_error` + `reason: max_turns`) |
+| `--mcp-config <file>` | claude-shaped `{ mcpServers }` stdio servers |
+| `--add-dir <path>` (repeatable) | extra confinement roots |
+| `--output-format stream-json` | required |
+| `--input-format stream-json` | persistent multi-turn over stdin |
+| `--reasoning-effort <v>` | forwarded as OpenAI `reasoning_effort` |
+
+Unknown flag ⇒ `unknown flag: X` on stderr, exit 2, no network call.
+
+## Frames (stdout, one JSON per line)
+
+```
+{ "type":"system", "subtype":"init", "session_id":"…", "model":"…" }
+{ "type":"assistant", "message":{ "id":"<per API call>", "role":"assistant",
+    "content":[{ "type":"text", "text":"<delta>" }],
+    "usage":{ "input_tokens":N, "output_tokens":N } } }
+{ "type":"assistant", "message":{ "id":"…", "content":[{ "type":"tool_use", "id":"call_1", "name":"Read", "input":{…} }], "usage":{…} } }
+{ "type":"user", "message":{ "content":[{ "type":"tool_result", "tool_use_id":"call_1", "content":"…", "is_error":false }] } }
+{ "type":"result", "subtype":"success", "is_error":false, "num_turns":2, "duration_ms":1234,
+  "usage":{ "input_tokens":N, "output_tokens":N }, "session_id":"…", "result":"<final text>" }
+```
+
+`total_cost_usd` is never emitted. `message.id` is stable per API call so the
+adapter's per-message usage dedup (the claude precedent) sums one row per call.
+Diagnostics go to stderr only. The adapter (`local-adapter.ts`) owns its own
+`parseStreamLine` — a copy of the claude frame mapping WITHOUT the
+notification-frame / background-task heuristics — so a claude parser change
+can never silently break local engines.
+
+## Tool loop
+
+`POST <baseUrl>/chat/completions` with `stream:true`, the message history and
+OpenAI `tools` definitions for the enabled set. SSE deltas are assembled
+(`tool_calls` fragments by index). Each completed call executes and appends a
+`tool` message; the loop ends when the model returns no calls or `--max-turns`
+is hit. Malformed argument JSON ⇒ error `tool_result` back to the model (small
+models self-correct). Context-length errors ⇒ evict the oldest tool-call/result
+pairs (never the system prompt nor the latest user turn), retry once, then fail
+with the endpoint message. `429` bodies pass through verbatim so
+`classifyProviderLimit` recognises them.
+
+Built-in tools (claude-compatible schemas): `Read`, `Grep`, `Glob`, `Bash`,
+`Write`, `Edit`. Filesystem paths are realpath-confined to `cwd` + `--add-dir`
+roots. `Bash` runs via `/bin/sh -c` (`cmd.exe /d /s /c` on win32), 10-minute
+cap, 64 KB captured output. Policies: `__none__` sends no tools; a csv
+restricts; `--disallowedTools` subtracts from the default set. There is no
+permission prompt — the policy IS the permission model.
+
+Slash commands: a prompt starting with `/<name>` resolves
+`<cwd>/.claude/commands/<name with ':'→'/'>.md`; its body becomes the system
+tail with `$ARGUMENTS` substituted. Missing file ⇒ `Unknown command: /<name>`
+(the same failure semantics kimi has).
+
+## Small-model tolerances (local engines only)
+
+- Assistant messages carrying `tool_calls` are sent with `content: ""` — never
+  `null` (llama.cpp: `invalid message content type: <nil>`).
+- A tool turn that ends with an EMPTY final message is nudged once
+  (`EMPTY_REPLY_NUDGE`, an extra user message asking for the plain-text reply);
+  a second empty reply settles as an empty non-error result.
+- Desktop side: `agent-fence-promotion.ts` (client ⇄ server twins) re-tags a
+  closed ```` ```json ```` fence with an `options` / `problem-frame` /
+  `spec-draft` shaped body, gated on the conversation provider being a local
+  id, and the per-turn context prefix restates the fence-tag + no-`#noframe`
+  rules. CLI providers are untouched.
+
+## Sessions
+
+`$SPECRAILS_LOCAL_RUNNER_HOME` (default `~/.specrails/local-runner`)
+`/sessions/<uuid>.json`, mode 0600, LRU-capped at 200. Missing session on
+`--resume` ⇒ `result { is_error:true, result:"No conversation found with session ID: <id>" }`
+— the exact diagnostic the Explore recovery path matches.
+
+Persistent mode reads `{ "type":"user", "message":{ "content": … } }` lines
+from stdin, one turn per line, one `result` per turn, exit 0 at stdin end.
+Errors keep the process alive in this mode.
+
+## MCP
+
+`--mcp-config` servers are started with the SDK stdio `Client`; tools are
+exposed as `mcp__<server>__<tool>` (claude naming, so the operator prompt and
+activity chip work unchanged). A server that fails to start is logged and
+skipped. `agent-mcp-config.ts` `prepareAgentMcp` has a `local` branch writing
+the same per-conversation file it writes for claude (bridge + enabled external
+servers); `SPECRAILS_AGENT_CONVERSATION` and the tier header ride `entry.env`.
+
+## Desktop wiring
+
+- Registry: `local-adapter-registry.ts` `syncLocalAdapters(connections)` at boot
+  and after `PUT /runtime-providers`; `registry.unregisterAdapter` never removes
+  CLI adapters; in-flight jobs keep the adapter instance they resolved.
+- Detection: `local-engine-detection.ts` `probeConnection` (`GET /models`,
+  3000 ms, no redirects, Bearer from env; 2xx ⇒ authenticated + models, 401/403
+  ⇒ unauthenticated, else unreachable) inside the 60 s provider-detection cycle;
+  `modelCatalog()` reads the cache.
+- Selection: `validateRequestedProvider` accepts detected local ids; primary
+  derivation never prefers a local id over a detected CLI.
+- Rails: local engine ⇒ `runtimeProviderOverride { provider, model }` for all
+  three core roles (core's `OpenAICompatibleExecutor`); non-core ai-steps spawn
+  the runner; deciders use `--tools __none__`; no profile env, no OTEL, no
+  plugins snapshot (capability-gated).
+- Accounting: `result-event.ts` — rates ⇒ estimated cost, else `NULL`; never a
+  rate-card guess.
+- Kill switch `SPECRAILS_LOCAL_ENGINES`.
+
+## Verification
+
+`local-runner/src/__tests__/` runs the runner against an in-process fake SSE
+server. `server/providers/__fixtures__/local-runner-transcript.jsonl` is fed
+through the adapter to pin the `AdapterEvent[]` shape. Manual smoke record (2026-09-14, endpoint `http://192.168.68.74:8080/v1`,
+`qwen3.5-9b:latest`, Ollama behind an OpenAI-compatible proxy):
+
+- Runner one-shot with `--tools Read,Grep,Glob`: `system/init` → `Read`
+  tool_use → tool_result → streamed text → `result { num_turns: 2, usage:
+  { input_tokens: 1210, output_tokens: 132 } }`, exit 0.
+- `--resume <id>` + `--input-format stream-json`, two user lines: two
+  `result` frames on the same session id, prior-turn memory intact, exit 0.
+- Dev server: `[local-engines] registered: local` at boot;
+  `POST /api/runtime-providers/test` ⇒ reachable, authenticated, both models,
+  20 ms; `GET /api/providers/detected?refresh=1` ⇒ `local` usable with models.
+  The very first boot probe timed out under startup congestion — the probe
+  bound was raised 1500 → 3000 ms as a result.
+- Pending: in-app UI pass (Settings card, rail/Add Spec/chat selectors, a
+  full implement rail on the local engine).