specrails-desktop 2.61.0 → 2.63.0

package/client/dist/assets/zap-bugHyWzQ.js

@@ -0,0 +1 @@
+import{t as e}from"./createLucideIcon-DtODIU64.js";var t={name:`zap`,size:24,node:[[`path`,{d:`M15.914 4a1.5 1.5 0 00-2.474-1.561l-9 9A1.5 1.5 0 005.5 14h4.002a.5.5 0 01.471.666L8.086 20a1.5 1.5 0 002.475 1.56l9-9A1.5 1.5 0 0018.5 10h-3.997a.5.5 0 01-.472-.667z`,key:`1v7up4`}]]};t.node;var n=e(t);export{n as t};

package/client/dist/index.html

@@ -204,16 +204,16 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-lTGJJTuk.js"></script>
+    <script type="module" crossorigin src="/assets/index-Culan6y7.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/jsx-runtime-BbYvbtY8.js">
+    <link rel="modulepreload" crossorigin href="/assets/react-dom-DDD8FYaU.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/chunk-OB3PAWPO-B1EMk45A.js">
     <link rel="modulepreload" crossorigin href="/assets/tauri-shell-DE6LfGPw.js">
     <link rel="modulepreload" crossorigin href="/assets/activity-DiyjsgQV.js">
     <link rel="modulepreload" crossorigin href="/assets/addspec-BOvgmcgk.js">
-    <link rel="modulepreload" crossorigin href="/assets/agent-Z5s_GTP0.js">
+    <link rel="modulepreload" crossorigin href="/assets/agent-Dip4h2YE.js">
     <link rel="modulepreload" crossorigin href="/assets/agentRuntime-C_yLPKDy.js">
     <link rel="modulepreload" crossorigin href="/assets/agents-Doe1sHY5.js">
     <link rel="modulepreload" crossorigin href="/assets/agentstudio-BzugqB_N.js">
@@ -236,52 +236,55 @@
     <link rel="modulepreload" crossorigin href="/assets/narration-DbHnz0qV.js">
     <link rel="modulepreload" crossorigin href="/assets/nav--u7iPYlS.js">
     <link rel="modulepreload" crossorigin href="/assets/packet-B0H15elv.js">
-    <link rel="modulepreload" crossorigin href="/assets/settings-Dbyd6gmj.js">
+    <link rel="modulepreload" crossorigin href="/assets/settings-nryN6wuS.js">
     <link rel="modulepreload" crossorigin href="/assets/setup-CKGUxKr-.js">
     <link rel="modulepreload" crossorigin href="/assets/specs-DfIdoU5L.js">
     <link rel="modulepreload" crossorigin href="/assets/subscriptionUsage-CdlE5Mg1.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-DaWuiO0S.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-D5eOjfvG.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-DKNbOF0u.js">
+    <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-DtODIU64.js">
+    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-CNOvmgTr.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-CVSryAL1.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-C5JVBeur.js">
     <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-lePfeT_Y.js">
-    <link rel="modulepreload" crossorigin href="/assets/save-OsUqVn99.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-DQDNtM8q.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-CroAs6Kh.js">
-    <link rel="modulepreload" crossorigin href="/assets/zap-CUOlvtT1.js">
-    <link rel="modulepreload" crossorigin href="/assets/file-text-BcLCfcWZ.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/external-link-D6XxC_Cu.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">
-    <link rel="modulepreload" crossorigin href="/assets/square-Ci-PFcFe.js">
-    <link rel="modulepreload" crossorigin href="/assets/plus-CsnjfkmX.js">
-    <link rel="modulepreload" crossorigin href="/assets/rotate-ccw-Wh4id13q.js">
-    <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-Bp0zXwjg.js">
+    <link rel="modulepreload" crossorigin href="/assets/save-LmPSfsvZ.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-BfjSJjBd.js">
+    <link rel="modulepreload" crossorigin href="/assets/chevron-up-6EFqEHBj.js">
+    <link rel="modulepreload" crossorigin href="/assets/sparkles-CCfUdFGY.js">
+    <link rel="modulepreload" crossorigin href="/assets/x-Bu7X_eR2.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-eH_KaAZ1.js">
+    <link rel="modulepreload" crossorigin href="/assets/ban-wqfdzoXt.js">
+    <link rel="modulepreload" crossorigin href="/assets/file-text-C0blZHLh.js">
+    <link rel="modulepreload" crossorigin href="/assets/circle-x-D2ttKotB.js">
+    <link rel="modulepreload" crossorigin href="/assets/download-C9wP_42h.js">
+    <link rel="modulepreload" crossorigin href="/assets/external-link-CZ6Q-v1-.js">
+    <link rel="modulepreload" crossorigin href="/assets/git-branch-yf6LE1Bw.js">
+    <link rel="modulepreload" crossorigin href="/assets/layers-BCLTgHXO.js">
+    <link rel="modulepreload" crossorigin href="/assets/loader-circle-BqV9xYGf.js">
+    <link rel="modulepreload" crossorigin href="/assets/pencil-CxrRbDwb.js">
+    <link rel="modulepreload" crossorigin href="/assets/square-D0JTbRSR.js">
+    <link rel="modulepreload" crossorigin href="/assets/plus-fHDdjBk1.js">
+    <link rel="modulepreload" crossorigin href="/assets/rotate-ccw-DalJAQQX.js">
+    <link rel="modulepreload" crossorigin href="/assets/search-BDVp3fkH.js">
+    <link rel="modulepreload" crossorigin href="/assets/trash-D8zYUmTg.js">
+    <link rel="modulepreload" crossorigin href="/assets/triangle-alert-Cxpn8bqr.js">
+    <link rel="modulepreload" crossorigin href="/assets/jira-api-Bl8xEIpk.js">
+    <link rel="modulepreload" crossorigin href="/assets/zap-bugHyWzQ.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-CMgps2MY.js">
-    <link rel="modulepreload" crossorigin href="/assets/lib-CGdyxIWg.js">
-    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-9JiGlFrx.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-DZ3VWsHq.js">
-    <link rel="modulepreload" crossorigin href="/assets/button-D1xExSTF.js">
-    <link rel="modulepreload" crossorigin href="/assets/project-repositories-CadLZOnr.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-CeCr6Jz-.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-YBJX3RmP.js">
+    <link rel="modulepreload" crossorigin href="/assets/dialog-DtdR05v1.js">
+    <link rel="modulepreload" crossorigin href="/assets/lib-DWJfei6y.js">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-ZHg7WpdH.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-NVM6rK3i.js">
+    <link rel="modulepreload" crossorigin href="/assets/button-4FS1ZDTp.js">
+    <link rel="modulepreload" crossorigin href="/assets/project-repositories-CvJf1a6H.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-BSgUqk_u.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-BoafEcm4.js">
     <link rel="modulepreload" crossorigin href="/assets/core-B3mKBIh5.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-DJCm1pZr.js">
-    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-D3YMw9qx.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-DgzNnJmn.js">
+    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-DohBmeg8.js">
     <link rel="modulepreload" crossorigin href="/assets/event-Bt7f3wXe.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-Bfunvi6w.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-D1v33giW.css">
   </head>
   <body>
     <div id="specrails-splash" aria-hidden="false" role="status" aria-label="Loading Specrails">

package/docs/ci-cd.md

@@ -11,12 +11,19 @@ Desktop distributes an npm package and native installers. Their publication work
 | `npm run build` then `npm run check:package` | A real npm tarball, isolated production install with lifecycle scripts disabled, CLI help/version, MCP and required runtime resources |
 | Windows x64 and ARM64 jobs | Native filesystem/process regressions, terminal/background containment, client tests, bundled Core and native browser/mission window fixtures |
 | macOS native job | Native Rust tests and browser, popup, multiwindow and mission window fixtures |
-| Native release builds | Packaged resources and installer validation; Windows additionally exercises installed NSIS/MSI artifacts |
+| Paired Core engine | Real Core acceptance suites, discovered as `*-paired.test.ts` and time-balanced across runners by `scripts/paired-core-shards.mjs` (2 shards on Linux/macOS, 4 on Windows) |
+| Native release builds | Packaged resources and installer validation; Windows additionally exercises the installed NSIS artifact |
 
 The npm package check does not start a server or exercise native postinstall rebuilds. Native platform jobs and installed application smoke tests provide separate evidence. Defining a Windows or signing job is not evidence that it has passed: inspect the corresponding GitHub run before claiming platform or release acceptance.
 
 Actions are pinned to commit SHAs. Downloaded actionlint and gitleaks binaries have fixed checksums verified before execution. Actionlint checks workflow structure, expressions and action inputs; its ShellCheck integration is disabled, so it does not claim complete shell-script analysis. Dependabot covers root/client/MCP npm dependencies, GitHub Actions and Cargo.
 
+## Pipeline speed
+
+The CI critical path is kept near the slowest ordinary job (~8 min) rather than one long serial suite. Add a paired suite by naming it `*-paired.test.ts`; it is assigned automatically, and `scripts/paired-core-shards.test.mjs` fails if any suite is unassigned, duplicated or has a stale timing weight. Refresh `WEIGHTS` from a CI JUnit artifact when suites grow.
+
+Tag builds can only restore caches saved on `main`, so `Release Rust cache` compiles the release profile on `main` (on `src-tauri/**` changes, daily, or manually) under the `desktop-release-*` shared keys that `Desktop Release` restores without saving. A cache miss only costs time: the release still compiles from scratch. Windows ships only NSIS, which removes a second compression pass, smoke install and upload per architecture.
+
 ## Release flow
 
 1. A successful main `CI` run triggers `Release`. It checks out that exact revision, skips superseded main revisions and lets release-please maintain the release pull request or tag. The credential-bearing job does not install dependencies or run builds.

package/docs/customizing.md

@@ -138,6 +138,7 @@ Most settings live in the UI. A few app-level switches are env-only because they
 |----------|--------|
 | `SPECRAILS_CORE_BIN` | Override the `specrails-core` binary (default: `npx --yes --prefer-online specrails-core@^5.1.0` — the 5.1.0 floor is the release that quotes the command path in its Windows shell runner, so OpenSpec init works from an install directory with spaces; it is also the version bundled with the app) |
 | `SPECRAILS_TECH_URL` | Override the specrails-tech proxy base URL |
+| `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` | Budget in milliseconds for reading configured project environment names from your login shell (default `10000`, max `120000`). Raise it when the Environment card shows **Shell timed out**. See the [project environment guide](guide/en/settings/5-project-environment.md) |
 | `SPECRAILS_AGENTS_SECTION=false` | Hide the Agents section from every project |
 | `SPECRAILS_PLUGINS_SECTION=false` | Hide the Integrations section from every project |
 | `SPECRAILS_JIRA_SECTION=false` | Hide the Jira integration and 404 its routes |

package/docs/getting-started.md

@@ -19,7 +19,7 @@ Two options:
 Download a signed build for your OS from `https://specrails.dev/downloads/specrails-desktop/latest/`:
 
 - **macOS** — `specrails-desktop-<version>-aarch64.dmg` (Apple Silicon, notarised)
-- **Windows** — `specrails-desktop-<version>-x64-setup.exe` (NSIS) or `.msi`
+- **Windows** — `specrails-desktop-<version>-x64-setup.exe` (NSIS; `-arm64-setup.exe` on ARM64)
 
 Open the installer, drag to Applications (macOS) or click through the wizard (Windows). The app bundles the server, so you don't need a separate process. The desktop app resolves your PATH for you at startup — no manual Homebrew/Volta/nvm setup needed — see [platforms/macos.md](platforms/macos.md) if anything looks off.
 

package/docs/guide/de/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ Antworten strömen flüssig herein und landen bereits formatiert (Überschriften
 - **Ohne Git keine PR-Phase.** Ein Projekt ohne Git-Repository (oder ohne Commits) bekommt trotzdem eine Run-Karte — Fortschritt, Log, Fehler und Wiederherstellung —, aber es gibt keinen Branch und keinen PR-Schritt; die Karte sagt das.
 - **`@rail-N`.** Tippe `@` und wähle ein Rail, um es in deiner Nachricht zu referenzieren, mit seinen Specs und ob es frei, belegt oder in Entscheidung ist.
 
+## Sub-Agenten
+
+Manche Anbieter können Teile einer Aufgabe an **Sub-Agenten** abgeben – Helfer, die parallel arbeiten und weitermachen, nachdem der Agent geantwortet hat. Sub-Agenten sind **standardmäßig aus**, weil sie die Kosten einer Anfrage vervielfachen.
+
+- **Pro Projekt einschalten.** Öffne in den Projekteinstellungen den Bereich **Sub-Agenten** und aktiviere **Sub-Agenten in diesem Projekt erlauben**. Das gilt für Missionen, Explore und Verfeinerungen dieses Projekts; Implement-Pipelines sind nie betroffen. Missionen ohne Projekt folgen **App-Einstellungen → KI-Anbieter → Sub-Agenten in Missionen ohne Projekt erlauben**.
+- **Wählen Sie, wer sie ausführt.** Unter **Sub-Agenten ausführen mit** lässt die Standardoption **Wie der Missions-Agent** das CLI der Mission sie nativ starten: am schnellsten, und sie teilen dessen Prompt-Cache. Wählen Sie stattdessen Anbieter, Modell und Aufwand, um Anbieter zu kombinieren – etwa eine Codex-Mission mit Claude-Sub-Agenten. Missionen, die bereits diesen Anbieter nutzen, bleiben mit diesem Modell nativ; bei einem anderen Anbieter startet Specrails jeden Sub-Agenten selbst, was kälter startet und mehr kosten kann, Ihnen aber mehr Kontrolle gibt und die echten Kosten jedes einzelnen zeigt. Specrails fragt vor dem Wechsel nach einer Bestätigung, und diese Sub-Agenten tragen in der Mission ein Anbieter-Badge.
+- **Bei der Arbeit zusehen.** Die von einer Antwort gestarteten Agenten erscheinen als eine kompakte Zeile unter dieser Antwort. Sie bleibt offen, solange sie arbeiten, und klappt sich zu einer Zusammenfassung mit Gesamtzeit und Tokens zusammen, sobald alle fertig sind. Klappe eine Zeile auf, um Ergebnis und Kosten zu lesen oder die Aktivität live zu verfolgen. Jeder Start bleibt an seiner Stelle im Gespräch, spätere Starts vermischen sich also nie mit früheren. Stoppe einen laufenden Agenten in seiner Zeile oder alle über die Zeile.
+- **Der Agent macht selbst weiter.** Wenn Hintergrund-Agenten fertig sind, setzt der Agent fort und berichtet, was sie gefunden haben – markiert mit *Nach Hintergrund-Agenten fortgesetzt*.
+- **Die Einstellung zu ändern ist sicher.** Eine Mission mit laufenden Agenten übernimmt die Änderung, sobald diese fertig sind; sie sagt es dir und bietet **Agenten stoppen und jetzt übernehmen** an.
+- **Nichts startet heimlich neu.** Durch einen Neustart unterbrochene Agenten bleiben als unterbrochen markiert; **Neu starten** entwirft nur eine Nachricht, die den Agenten bittet, diese Arbeit erneut zu erledigen.
+
 ## Ein paar Dinge, die du wissen solltest
 
 - **Ausführen und Autonom kosten Geld**, weil sie KI laufen lassen. Der Agent hebt kostenverursachende Aktionen hervor, bevor er sie ausführt; belasse die Stufe bei Beobachten oder Bearbeiten, wenn du nur schauen und aufräumen willst.

package/docs/guide/de/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# Projektumgebung
+
+Manche Projekte brauchen zur Laufzeit ein Zugangsdatum, etwa `NODE_AUTH_TOKEN` für private npm-Pakete. Füge unter **Projekteinstellungen → Umgebung** die **Namen** der Variablen hinzu, die deine Rails und Loops brauchen. Specrails speichert nur die Namen, nie die Werte.
+
+## Woher die Werte kommen
+
+Beim Start eines Laufs liest Specrails jeden konfigurierten Namen aus der Umgebung, mit der es gestartet wurde. Öffnest du Specrails über das Dock oder den Finder, enthält diese Umgebung nicht, was dein Shell-Profil exportiert. Deshalb liest Specrails fehlende Namen zusätzlich aus deiner Login-Shell (zum Beispiel `~/.zprofile` oder `~/.zshrc`). Bewahre das echte Zugangsdatum in deinem Shell-Profil auf, nicht im Repository.
+
+Die Prüfung läuft im Hintergrund, wenn das Projekt geöffnet wird, wenn du die Namen änderst, und danach regelmäßig. Ein langsames Profil verzögert deine Läufe also nicht. Die Werte bleiben nur für dieses Projekt im Speicher.
+
+## Die Statuschips lesen
+
+Jeder gespeicherte Name zeigt einen Chip:
+
+| Chip | Bedeutung | Was tun |
+|------|-----------|---------|
+| **Geerbt** | Specrails wurde mit der Variable gestartet. | Nichts. |
+| **Aus Login-Shell** | Specrails hat sie aus deiner Login-Shell gelesen. | Nichts. |
+| **Nicht definiert** | Deine Login-Shell exportiert sie nicht. | Füge ein `export` in dein Shell-Profil ein. |
+| **Shell-Zeitüberschreitung** | Deine Login-Shell brauchte zu lange zum Starten. | Beschleunige das Profil oder erhöhe `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (Standard 10 Sekunden). |
+| **Shell-Prüfung fehlgeschlagen** | Specrails konnte deine Login-Shell nicht lesen. | Korrigiere das Profil oder starte Specrails aus einem Terminal. |
+
+Fahre mit der Maus über einen Chip, um die Erklärung zu sehen. Klicke nach der Korrektur deines Profils auf **Erneut prüfen**: Ein Neustart von Specrails ist nicht nötig.
+
+Startet ein Lauf mit einem ungelösten Namen, zeigt sein Log eine `[environment]`-Zeile mit der Variable und ihrem Status. Der Lauf startet trotzdem. Der Wert erscheint nie in der App, in den Logs oder in den MCP-Tools.
+
+Unter Windows verwendet Specrails nur die Umgebung, mit der es gestartet wurde.

package/docs/guide/en/integrations/6-agent-chat.md

@@ -66,6 +66,17 @@ Replies stream in smoothly and land formatted (headings, tables, lists), each wi
 - **No git, no PR phase.** A project without a git repository (or without commits) still gets a run card — progress, log, failure and recovery — but there is no branch and no PR step; the card says so.
 - **`@rail-N`.** Type `@` and pick a rail to reference it in your message, with its specs and whether it is free, busy or awaiting a decision.
 
+## Sub-agents
+
+Some providers can hand parts of a task to **sub-agents** — helpers that work in parallel and keep going after the agent replies. Sub-agents are **off by default**: they multiply what one request costs.
+
+- **Turn them on per project.** Open the project's **Settings → Sub-agents** and switch on **Allow sub-agents in this project**. It covers that project's missions, explore and refinements; Implement pipelines are never affected. Missions without a project follow **App settings → AI providers → Allow sub-agents in missions without a project**.
+- **Choose who runs them.** Under **Run sub-agents with**, the default **Same as the mission agent** lets the mission's own CLI launch them natively: fastest, and they share its prompt cache. Pick a provider, model and effort instead to mix providers — for example a Codex mission with Claude sub-agents. Missions already on that provider stay native with that model; on another provider Specrails launches each sub-agent itself, which starts colder and can cost more, but gives you more control and shows each one's real cost. Specrails asks you to confirm before switching, and those sub-agents carry a provider badge in the mission.
+- **Watch them work.** The agents a reply launched appear as one compact line under that reply. It stays open while they work, and once they all finish it folds into a summary with the total time and tokens. Expand a row to read its result and what it cost, or to follow its activity live. Each launch stays at its point in the conversation, so later launches never mix with earlier ones. Stop a running agent from its row, or stop them all from the line.
+- **The agent follows up on its own.** When background agents finish, the agent continues and posts what they found, marked *Continued after background agents*.
+- **Changing the setting is safe.** A mission with agents still running applies the change once they finish; it tells you so and offers **Stop agents and apply now**.
+- **Nothing restarts behind your back.** Agents interrupted by a restart stay marked as interrupted; **Relaunch** only drafts a message asking the agent to redo that work.
+
 ## A few things to know
 
 - **Operate and Autonomous cost money** because they run AI. The agent surfaces cost-incurring actions before doing them; keep the level at Observe or Edit if you just want to look and tidy.

package/docs/guide/en/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# Project environment
+
+Some projects need a credential at run time, such as `NODE_AUTH_TOKEN` for private npm packages. In **Project Settings → Environment**, add the **names** of the variables your rails and loops need. Specrails stores only the names, never the values.
+
+## Where the values come from
+
+When a run starts, Specrails reads each configured name from the environment it was launched with. When you open Specrails from the Dock or Finder, that environment does not include what your shell profile exports, so Specrails also reads the missing names from your login shell (for example `~/.zprofile` or `~/.zshrc`). Keep the real credential in your shell profile, not in the repository.
+
+The check runs in the background when the project opens, when you change the names, and regularly afterwards, so a slow profile does not delay your runs. Values stay in memory for that project only.
+
+## Reading the status chips
+
+Each saved name shows a chip:
+
+| Chip | What it means | What to do |
+|------|---------------|------------|
+| **Inherited** | Specrails was started with the variable. | Nothing. |
+| **From login shell** | Specrails read it from your login shell. | Nothing. |
+| **Not defined** | Your login shell does not export it. | Add an `export` for it to your shell profile. |
+| **Shell timed out** | Your login shell took too long to start. | Speed up the profile, or raise `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (default 10 seconds). |
+| **Shell check failed** | Specrails could not read your login shell. | Fix the profile, or launch Specrails from a terminal. |
+
+Hover a chip for the explanation. After fixing your profile, click **Check again**: you do not need to restart Specrails.
+
+If a run starts while a name is unresolved, its log shows one `[environment]` line naming the variable and its status. The run still starts. The value is never shown in the app, the logs or the MCP tools.
+
+On Windows, Specrails uses only the environment it was started with.

package/docs/guide/es/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ Las respuestas llegan fluidas y ya formateadas (encabezados, tablas, listas), ca
 - **Sin git no hay fase de PR.** Un proyecto sin repositorio git (o sin commits) también tiene card de ejecución — progreso, log, fallo y recuperación — pero no hay rama ni paso de PR; la card lo indica.
 - **`@rail-N`.** Escribe `@` y elige un rail para referenciarlo en tu mensaje, con sus specs y si está libre, ocupado o pendiente de decisión.
 
+## Sub-agentes
+
+Algunos proveedores pueden repartir partes de una tarea entre **sub-agentes**: ayudantes que trabajan en paralelo y siguen después de que el agente responda. Los sub-agentes vienen **desactivados por defecto** porque multiplican lo que cuesta una petición.
+
+- **Actívalos por proyecto.** Abre **Configuración → Sub-agentes** del proyecto y activa **Permitir sub-agentes en este proyecto**. Cubre las misiones, la exploración y los refinamientos de ese proyecto; los pipelines de Implement nunca se ven afectados. Las misiones sin proyecto siguen **Ajustes de la app → Proveedores de IA → Permitir sub-agentes en misiones sin proyecto**.
+- **Elige quién los ejecuta.** En **Ejecutar sub-agentes con**, la opción por defecto **Igual que el agente de la misión** deja que el propio CLI de la misión los lance de forma nativa: es lo más rápido y comparten su caché de prompt. Elige en su lugar un proveedor, modelo y esfuerzo para combinar proveedores — por ejemplo, una misión en Codex con sub-agentes en Claude. Las misiones que ya usan ese proveedor siguen siendo nativas con ese modelo; con otro proveedor, Specrails lanza cada sub-agente por su cuenta, que arranca en frío y puede costar más, pero te da más control y muestra el coste real de cada uno. Specrails te pide confirmación antes del cambio, y esos sub-agentes llevan una etiqueta con su proveedor en la misión.
+- **Míralos trabajar.** Los agentes que lanza una respuesta aparecen como una línea compacta bajo esa respuesta. Se mantiene abierta mientras trabajan y, cuando terminan todos, se pliega en un resumen con el tiempo y los tokens totales. Despliega una fila para leer su resultado y lo que costó, o para seguir su actividad en directo. Cada lanzamiento se queda en su punto de la conversación, así que los siguientes nunca se mezclan con los anteriores. Detén un agente en marcha desde su fila, o todos desde la línea.
+- **El agente retoma solo.** Cuando terminan los agentes en segundo plano, el agente continúa y publica lo que encontraron, marcado como *Continuó tras los agentes en segundo plano*.
+- **Cambiar el ajuste es seguro.** Una misión con agentes en marcha aplica el cambio cuando terminan; te lo indica y ofrece **Detener agentes y aplicar ya**.
+- **Nada se relanza a tus espaldas.** Los agentes interrumpidos por un reinicio quedan marcados como interrumpidos; **Relanzar** solo redacta un mensaje pidiendo al agente que rehaga ese trabajo.
+
 ## Algunas cosas que conviene saber
 
 - **Opera y Autónomo cuestan dinero** porque ejecutan IA. El agente saca a la luz las acciones que generan coste antes de hacerlas; mantén el nivel en Observa o Edita si solo quieres mirar y ordenar.

package/docs/guide/es/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# Entorno del proyecto
+
+Algunos proyectos necesitan una credencial al ejecutarse, como `NODE_AUTH_TOKEN` para paquetes privados de npm. En **Ajustes del proyecto → Entorno**, añade los **nombres** de las variables que necesitan tus rails y loops. Specrails guarda solo los nombres, nunca los valores.
+
+## De dónde salen los valores
+
+Al iniciar una ejecución, Specrails lee cada nombre configurado del entorno con el que se abrió. Si abres Specrails desde el Dock o el Finder, ese entorno no incluye lo que exporta tu perfil de shell, así que Specrails también lee los nombres que faltan de tu login shell (por ejemplo `~/.zprofile` o `~/.zshrc`). Guarda la credencial real en tu perfil de shell, no en el repositorio.
+
+La comprobación se hace en segundo plano al abrir el proyecto, al cambiar los nombres y periódicamente después, así que un perfil lento no retrasa tus ejecuciones. Los valores quedan en memoria solo para ese proyecto.
+
+## Cómo leer los indicadores
+
+Cada nombre guardado muestra un indicador:
+
+| Indicador | Qué significa | Qué hacer |
+|-----------|---------------|-----------|
+| **Heredada** | Specrails se inició con la variable. | Nada. |
+| **Del login shell** | Specrails la leyó de tu login shell. | Nada. |
+| **No definida** | Tu login shell no la exporta. | Añade un `export` en tu perfil de shell. |
+| **Shell agotó el tiempo** | Tu login shell tardó demasiado en arrancar. | Acelera el perfil o sube `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (10 segundos por defecto). |
+| **Fallo al leer el shell** | Specrails no pudo leer tu login shell. | Corrige el perfil o abre Specrails desde una terminal. |
+
+Pasa el ratón por encima de un indicador para ver la explicación. Tras corregir el perfil, pulsa **Comprobar de nuevo**: no hace falta reiniciar Specrails.
+
+Si una ejecución arranca con un nombre sin resolver, su log muestra una línea `[environment]` con la variable y su estado. La ejecución arranca igualmente. El valor nunca aparece en la app, en los logs ni en las herramientas MCP.
+
+En Windows, Specrails usa solo el entorno con el que se inició.

package/docs/guide/fr/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ Les réponses arrivent en flux fluide et s'affichent déjà mises en forme (titr
 - **Sans git, pas de phase PR.** Un projet sans dépôt git (ou sans commits) a quand même une carte d'exécution — progression, log, échec et récupération — mais il n'y a ni branche ni étape PR ; la carte le dit.
 - **`@rail-N`.** Tapez `@` et choisissez un rail pour le référencer dans votre message, avec ses specs et son état : libre, occupé ou en attente de décision.
 
+## Sous-agents
+
+Certains fournisseurs peuvent confier des parties d'une tâche à des **sous-agents** : des assistants qui travaillent en parallèle et continuent après la réponse de l'agent. Les sous-agents sont **désactivés par défaut** car ils multiplient le coût d'une demande.
+
+- **Activez-les par projet.** Ouvrez **Réglages → Sous-agents** du projet et activez **Autoriser les sous-agents dans ce projet**. Cela couvre les missions, l'exploration et les affinages du projet ; les pipelines Implement ne sont jamais concernés. Les missions sans projet suivent **Réglages de l'app → Fournisseurs d'IA → Autoriser les sous-agents dans les missions sans projet**.
+- **Choisissez qui les exécute.** Sous **Exécuter les sous-agents avec**, l'option par défaut **Comme l'agent de la mission** laisse le CLI de la mission les lancer nativement : c'est le plus rapide, et ils partagent son cache de prompt. Choisissez plutôt un fournisseur, un modèle et un effort pour mélanger les fournisseurs — par exemple une mission Codex avec des sous-agents Claude. Les missions déjà sur ce fournisseur restent natives avec ce modèle ; sur un autre fournisseur, Specrails lance lui-même chaque sous-agent, qui démarre à froid et peut coûter plus, mais vous donne plus de contrôle et affiche le coût réel de chacun. Specrails demande une confirmation avant le changement, et ces sous-agents portent un badge de fournisseur dans la mission.
+- **Suivez leur travail.** Les agents lancés par une réponse apparaissent sur une ligne compacte sous cette réponse. Elle reste ouverte pendant qu'ils travaillent et se replie en un résumé avec la durée et les jetons totaux une fois qu'ils ont tous fini. Dépliez une ligne pour lire son résultat et son coût, ou suivre son activité en direct. Chaque lancement reste à sa place dans la conversation : les suivants ne se mélangent jamais aux précédents. Arrêtez un agent en cours depuis sa ligne, ou tous depuis la ligne de résumé.
+- **L'agent reprend tout seul.** Quand les agents en arrière-plan ont fini, l'agent continue et publie ce qu'ils ont trouvé, marqué *Suite après les agents en arrière-plan*.
+- **Changer le réglage est sans risque.** Une mission dont des agents tournent applique le changement quand ils ont fini ; elle vous l'indique et propose **Arrêter les agents et appliquer**.
+- **Rien ne redémarre dans votre dos.** Les agents interrompus par un redémarrage restent marqués interrompus ; **Relancer** rédige seulement un message demandant à l'agent de refaire ce travail.
+
 ## Quelques points à savoir
 
 - **Opérer et Autonome coûtent de l'argent** car ils exécutent de l'IA. L'agent met en avant les actions génératrices de coût avant de les réaliser ; gardez le niveau sur Observer ou Modifier si vous voulez juste regarder et ranger.

package/docs/guide/fr/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# Environnement du projet
+
+Certains projets ont besoin d'un identifiant à l'exécution, comme `NODE_AUTH_TOKEN` pour des paquets npm privés. Dans **Paramètres du projet → Environnement**, ajoutez les **noms** des variables dont vos rails et vos loops ont besoin. Specrails enregistre uniquement les noms, jamais les valeurs.
+
+## D'où viennent les valeurs
+
+Au démarrage d'une exécution, Specrails lit chaque nom configuré dans l'environnement avec lequel il a été lancé. Si vous ouvrez Specrails depuis le Dock ou le Finder, cet environnement ne contient pas ce qu'exporte votre profil de shell : Specrails lit donc aussi les noms manquants dans votre shell de connexion (par exemple `~/.zprofile` ou `~/.zshrc`). Gardez le véritable identifiant dans votre profil de shell, pas dans le dépôt.
+
+La vérification s'exécute en arrière-plan à l'ouverture du projet, quand vous modifiez les noms, puis régulièrement : un profil lent ne retarde donc pas vos exécutions. Les valeurs restent en mémoire pour ce projet uniquement.
+
+## Lire les pastilles d'état
+
+Chaque nom enregistré affiche une pastille :
+
+| Pastille | Signification | Que faire |
+|----------|---------------|-----------|
+| **Héritée** | Specrails a été lancé avec la variable. | Rien. |
+| **Du shell de connexion** | Specrails l'a lue dans votre shell de connexion. | Rien. |
+| **Non définie** | Votre shell de connexion ne l'exporte pas. | Ajoutez un `export` dans votre profil de shell. |
+| **Délai du shell dépassé** | Votre shell de connexion a mis trop de temps à démarrer. | Allégez le profil ou augmentez `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (10 secondes par défaut). |
+| **Échec de lecture du shell** | Specrails n'a pas pu lire votre shell de connexion. | Corrigez le profil ou lancez Specrails depuis un terminal. |
+
+Survolez une pastille pour afficher l'explication. Après avoir corrigé votre profil, cliquez sur **Vérifier à nouveau** : inutile de redémarrer Specrails.
+
+Si une exécution démarre alors qu'un nom n'est pas résolu, son journal affiche une ligne `[environment]` indiquant la variable et son état. L'exécution démarre quand même. La valeur n'apparaît jamais dans l'application, les journaux ou les outils MCP.
+
+Sous Windows, Specrails utilise uniquement l'environnement avec lequel il a été lancé.

package/docs/guide/it/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ Le risposte arrivano fluide e già formattate (titoli, tabelle, elenchi), ciascu
 - **Senza git niente fase PR.** Un progetto senza repository git (o senza commit) ha comunque una card di esecuzione — progresso, log, fallimento e recupero — ma non c'è branch né passaggio PR; la card lo dice.
 - **`@rail-N`.** Digita `@` e scegli un rail per citarlo nel messaggio, con le sue spec e se è libero, occupato o in attesa di decisione.
 
+## Sotto-agenti
+
+Alcuni provider possono affidare parti di un compito a **sotto-agenti**: aiutanti che lavorano in parallelo e proseguono dopo la risposta dell'agente. I sotto-agenti sono **disattivati per impostazione predefinita** perché moltiplicano il costo di una richiesta.
+
+- **Attivali per progetto.** Apri **Impostazioni → Sotto-agenti** del progetto e attiva **Consenti sotto-agenti in questo progetto**. Vale per missioni, esplorazione e rifiniture del progetto; le pipeline Implement non sono mai interessate. Le missioni senza progetto seguono **Impostazioni dell'app → Provider di IA → Consenti sotto-agenti nelle missioni senza progetto**.
+- **Scegli chi li esegue.** In **Esegui i sotto-agenti con**, l'opzione predefinita **Come l'agente della missione** lascia che il CLI della missione li avvii nativamente: è la più veloce e condividono la sua cache del prompt. Scegli invece provider, modello ed effort per combinare provider — ad esempio una missione Codex con sotto-agenti Claude. Le missioni che usano già quel provider restano native con quel modello; con un altro provider Specrails avvia da sé ogni sotto-agente, che parte a freddo e può costare di più, ma ti dà più controllo e mostra il costo reale di ciascuno. Specrails chiede conferma prima del cambio, e quei sotto-agenti mostrano un badge del provider nella missione.
+- **Guardali lavorare.** Gli agenti avviati da una risposta compaiono come una riga compatta sotto quella risposta. Resta aperta mentre lavorano e, quando finiscono tutti, si chiude in un riepilogo con tempo e token totali. Espandi una riga per leggerne il risultato e il costo, o seguirne l'attività dal vivo. Ogni avvio resta al suo punto della conversazione, quindi i successivi non si mescolano mai ai precedenti. Ferma un agente in corso dalla sua riga, o tutti dalla riga di riepilogo.
+- **L'agente riprende da solo.** Quando gli agenti in background finiscono, l'agente prosegue e pubblica ciò che hanno trovato, con l'etichetta *Proseguito dopo gli agenti in background*.
+- **Cambiare l'impostazione è sicuro.** Una missione con agenti attivi applica la modifica quando finiscono; te lo segnala e offre **Ferma gli agenti e applica ora**.
+- **Niente si riavvia di nascosto.** Gli agenti interrotti da un riavvio restano segnati come interrotti; **Rilancia** si limita a preparare un messaggio che chiede all'agente di rifare quel lavoro.
+
 ## Alcune cose da sapere
 
 - **Opera e Autonomo costano denaro** perché eseguono IA. L'agente mette in evidenza le azioni che generano costi prima di eseguirle; tieni il livello su Osserva o Modifica se vuoi solo guardare e mettere in ordine.

package/docs/guide/it/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# Ambiente del progetto
+
+Alcuni progetti hanno bisogno di una credenziale durante l'esecuzione, come `NODE_AUTH_TOKEN` per i pacchetti npm privati. In **Impostazioni del progetto → Ambiente**, aggiungi i **nomi** delle variabili che servono ai tuoi rail e loop. Specrails salva solo i nomi, mai i valori.
+
+## Da dove arrivano i valori
+
+Quando un'esecuzione parte, Specrails legge ogni nome configurato dall'ambiente con cui è stato avviato. Se apri Specrails dal Dock o dal Finder, quell'ambiente non include ciò che esporta il tuo profilo della shell, quindi Specrails legge anche i nomi mancanti dalla tua login shell (per esempio `~/.zprofile` o `~/.zshrc`). Tieni la credenziale reale nel profilo della shell, non nel repository.
+
+Il controllo avviene in background all'apertura del progetto, quando cambi i nomi e poi periodicamente, così un profilo lento non ritarda le esecuzioni. I valori restano in memoria solo per quel progetto.
+
+## Leggere gli indicatori di stato
+
+Ogni nome salvato mostra un indicatore:
+
+| Indicatore | Significato | Cosa fare |
+|------------|-------------|-----------|
+| **Ereditata** | Specrails è stato avviato con la variabile. | Niente. |
+| **Dalla login shell** | Specrails l'ha letta dalla tua login shell. | Niente. |
+| **Non definita** | La tua login shell non la esporta. | Aggiungi un `export` nel profilo della shell. |
+| **Timeout della shell** | La tua login shell ha impiegato troppo ad avviarsi. | Velocizza il profilo o aumenta `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (10 secondi di default). |
+| **Lettura della shell non riuscita** | Specrails non è riuscito a leggere la tua login shell. | Correggi il profilo o avvia Specrails da un terminale. |
+
+Passa il mouse su un indicatore per vedere la spiegazione. Dopo aver corretto il profilo, fai clic su **Verifica di nuovo**: non serve riavviare Specrails.
+
+Se un'esecuzione parte con un nome non risolto, il suo log mostra una riga `[environment]` con la variabile e il suo stato. L'esecuzione parte comunque. Il valore non compare mai nell'app, nei log o negli strumenti MCP.
+
+Su Windows, Specrails usa solo l'ambiente con cui è stato avviato.

package/docs/guide/ja/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ Agent Chat は組み込みの **Specrails MCP サーバー**を通じてアプ
 - **git がなければ PR フェーズもない。** git リポジトリ（またはコミット）のないプロジェクトにも実行カードはあります——進捗、ログ、失敗と復旧——ただしブランチも PR ステップもありません。カードにそう書かれます。
 - **`@rail-N`。** `@` を入力して rail を選ぶと、その spec と状態（空き・使用中・決定待ち）付きでメッセージから参照できます。
 
+## サブエージェント
+
+一部のプロバイダーは、タスクの一部を**サブエージェント**に任せられます。サブエージェントは並行して動き、エージェントが返信した後も作業を続けるヘルパーです。1 回の依頼のコストが大きく増えるため、サブエージェントは**既定でオフ**です。
+
+- **プロジェクトごとにオンにする。** プロジェクトの**設定 → サブエージェント**を開き、**このプロジェクトでサブエージェントを許可**をオンにします。そのプロジェクトのミッション、探索、リファインに適用され、Implement パイプラインには一切影響しません。プロジェクトのないミッションは**アプリ設定 → AI プロバイダー → プロジェクトのないミッションでサブエージェントを許可**に従います。
+- **実行するプロバイダーを選ぶ。** **サブエージェントの実行環境** の既定値 **ミッションのエージェントと同じ** では、ミッション自身の CLI がネイティブに起動します。最も速く、プロンプトキャッシュも共有されます。代わりにプロバイダー・モデル・エフォートを選ぶと、たとえば Codex のミッションで Claude のサブエージェントを使うなど、プロバイダーを組み合わせられます。すでにそのプロバイダーを使うミッションはそのモデルでネイティブのまま、別のプロバイダーでは Specrails が各サブエージェントを自ら起動します。コールドスタートでコストが増えることがありますが、より細かく制御でき、それぞれの実コストも表示されます。切り替え前に確認が表示され、これらのサブエージェントにはミッション内でプロバイダーのバッジが付きます。
+- **作業を見守る。** 返信が起動したエージェントは、その返信の下に 1 行のコンパクトな表示で現れます。作業中は開いたままで、すべて完了すると合計時間とトークンをまとめた 1 行に折りたたまれます。行を展開すると、結果とコストを読んだり、アクティビティをライブで追ったりできます。各起動は会話のその位置に残るため、後の起動が前のものと混ざることはありません。実行中のエージェントは行から停止でき、まとめての停止は要約行から行えます。
+- **エージェントは自分で続ける。** バックグラウンドのエージェントが終わると、エージェントは作業を続けて結果を投稿します。その投稿には「バックグラウンドエージェントの後に続行」と表示されます。
+- **設定の変更は安全。** エージェントが動作中のミッションは、それらの完了後に変更を適用します。その旨が表示され、**エージェントを停止して今すぐ適用**も選べます。
+- **勝手に再起動しない。** 再起動で中断されたエージェントは中断済みとして残ります。**再起動**は、その作業のやり直しをエージェントに頼むメッセージを下書きするだけです。
+
 ## 知っておくとよいこと
 
 - **操作と自律は料金が発生します**。AI を実行するからです。エージェントは料金の発生する操作を実行する前に前面に示します。眺めて整理したいだけなら、レベルは観察か編集にしておいてください。

package/docs/guide/ja/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# プロジェクト環境
+
+プロジェクトによっては、プライベート npm パッケージ用の `NODE_AUTH_TOKEN` のように、実行時に認証情報が必要です。**プロジェクト設定 → 環境** で、rail と loop が必要とする変数の**名前**を追加します。Specrails が保存するのは名前だけで、値は保存しません。
+
+## 値の取得元
+
+実行の開始時に、Specrails は起動時の環境から設定済みの各名前を読み取ります。Dock や Finder から Specrails を開いた場合、その環境にはシェルのプロファイルが export する内容が含まれません。そのため Specrails は、不足している名前をログインシェル（例: `~/.zprofile` や `~/.zshrc`）からも読み取ります。実際の認証情報はリポジトリではなく、シェルのプロファイルに置いてください。
+
+確認はプロジェクトを開いたとき、名前を変更したとき、その後も定期的にバックグラウンドで行われるため、プロファイルが遅くても実行は遅れません。値はそのプロジェクトのメモリ内にのみ保持されます。
+
+## ステータスチップの見方
+
+保存した各名前にチップが表示されます。
+
+| チップ | 意味 | 対処 |
+|--------|------|------|
+| **継承** | Specrails はその変数を持って起動しました。 | 不要です。 |
+| **ログインシェルから取得** | Specrails がログインシェルから読み取りました。 | 不要です。 |
+| **未定義** | ログインシェルがその変数を export していません。 | シェルのプロファイルに `export` を追加します。 |
+| **シェルがタイムアウト** | ログインシェルの起動に時間がかかりすぎました。 | プロファイルを軽くするか、`SPECRAILS_LOGIN_SHELL_TIMEOUT_MS`（既定は 10 秒）を増やします。 |
+| **シェルの読み取りに失敗** | Specrails がログインシェルを読み取れませんでした。 | プロファイルを修正するか、ターミナルから Specrails を起動します。 |
+
+チップにカーソルを合わせると説明が表示されます。プロファイルを修正したら **再確認** をクリックしてください。Specrails の再起動は不要です。
+
+名前が未解決のまま実行が始まると、そのログに変数名とステータスを示す `[environment]` 行が 1 行表示されます。実行はそのまま開始されます。値がアプリ、ログ、MCP ツールに表示されることはありません。
+
+Windows では、Specrails は起動時の環境のみを使用します。

package/docs/guide/pt/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ As respostas chegam de forma fluida e já formatadas (títulos, tabelas, listas)
 - **Sem git, sem fase de PR.** Um projeto sem repositório git (ou sem commits) também recebe um card de execução — progresso, log, falha e recuperação — mas não há branch nem etapa de PR; o card avisa.
 - **`@rail-N`.** Digite `@` e escolha um rail para referenciá-lo na mensagem, com suas specs e se está livre, ocupado ou aguardando decisão.
 
+## Subagentes
+
+Alguns provedores podem distribuir partes de uma tarefa para **subagentes**: ajudantes que trabalham em paralelo e continuam depois que o agente responde. Os subagentes vêm **desativados por padrão** porque multiplicam o custo de um pedido.
+
+- **Ative por projeto.** Abra **Configurações → Subagentes** do projeto e ative **Permitir subagentes neste projeto**. Vale para missões, exploração e refinamentos do projeto; os pipelines de Implement nunca são afetados. Missões sem projeto seguem **Configurações do app → Provedores de IA → Permitir subagentes em missões sem projeto**.
+- **Escolha quem os executa.** Em **Executar sub-agentes com**, a opção padrão **Igual ao agente da missão** deixa o próprio CLI da missão iniciá-los nativamente: é o mais rápido, e eles compartilham o cache de prompt. Escolha um provedor, modelo e esforço para combinar provedores — por exemplo, uma missão em Codex com subagentes em Claude. Missões que já usam esse provedor continuam nativas com esse modelo; com outro provedor, o Specrails inicia cada subagente por conta própria, que começa a frio e pode custar mais, mas dá mais controle e mostra o custo real de cada um. O Specrails pede confirmação antes da troca, e esses subagentes exibem um selo do provedor na missão.
+- **Acompanhe o trabalho.** Os agentes iniciados por uma resposta aparecem como uma linha compacta abaixo dela. Ela fica aberta enquanto trabalham e, quando todos terminam, se recolhe num resumo com o tempo e os tokens totais. Expanda uma linha para ler o resultado e o custo, ou acompanhar a atividade ao vivo. Cada lançamento fica no seu ponto da conversa, então os seguintes nunca se misturam com os anteriores. Pare um agente em execução pela linha dele, ou todos pela linha de resumo.
+- **O agente continua sozinho.** Quando os agentes em segundo plano terminam, o agente continua e publica o que encontraram, marcado como *Continuou após os agentes em segundo plano*.
+- **Mudar a configuração é seguro.** Uma missão com agentes em execução aplica a mudança quando eles terminam; ela avisa e oferece **Parar agentes e aplicar agora**.
+- **Nada reinicia escondido.** Agentes interrompidos por um reinício ficam marcados como interrompidos; **Relançar** só rascunha uma mensagem pedindo ao agente que refaça esse trabalho.
+
 ## Algumas coisas para saber
 
 - **Opera e Autônomo custam dinheiro** porque executam IA. O agente destaca as ações que geram custo antes de fazê-las; mantenha o nível em Observa ou Edita se você só quer olhar e organizar.

package/docs/guide/pt/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# Ambiente do projeto
+
+Alguns projetos precisam de uma credencial durante a execução, como `NODE_AUTH_TOKEN` para pacotes npm privados. Em **Configurações do projeto → Ambiente**, adicione os **nomes** das variáveis de que seus rails e loops precisam. O Specrails guarda apenas os nomes, nunca os valores.
+
+## De onde vêm os valores
+
+Quando uma execução começa, o Specrails lê cada nome configurado do ambiente com que foi iniciado. Se você abre o Specrails pelo Dock ou pelo Finder, esse ambiente não inclui o que o seu perfil de shell exporta, então o Specrails também lê os nomes ausentes do seu login shell (por exemplo `~/.zprofile` ou `~/.zshrc`). Mantenha a credencial real no perfil do shell, não no repositório.
+
+A verificação roda em segundo plano quando o projeto abre, quando você altera os nomes e periodicamente depois disso, para que um perfil lento não atrase suas execuções. Os valores ficam na memória apenas para aquele projeto.
+
+## Como ler os indicadores de estado
+
+Cada nome salvo mostra um indicador:
+
+| Indicador | O que significa | O que fazer |
+|-----------|-----------------|-------------|
+| **Herdada** | O Specrails foi iniciado com a variável. | Nada. |
+| **Do login shell** | O Specrails a leu do seu login shell. | Nada. |
+| **Não definida** | Seu login shell não a exporta. | Adicione um `export` no perfil do shell. |
+| **Tempo do shell esgotado** | Seu login shell demorou demais para iniciar. | Acelere o perfil ou aumente `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (padrão de 10 segundos). |
+| **Falha ao ler o shell** | O Specrails não conseguiu ler seu login shell. | Corrija o perfil ou abra o Specrails a partir de um terminal. |
+
+Passe o mouse sobre um indicador para ver a explicação. Depois de corrigir o perfil, clique em **Verificar novamente**: não é preciso reiniciar o Specrails.
+
+Se uma execução começar com um nome não resolvido, o log mostra uma linha `[environment]` com a variável e seu estado. A execução começa mesmo assim. O valor nunca aparece no app, nos logs nem nas ferramentas MCP.
+
+No Windows, o Specrails usa apenas o ambiente com que foi iniciado.

package/docs/guide/zh/integrations/6-agent-chat.md

@@ -67,6 +67,17 @@ Agent Chat 通过内嵌的 **Specrails MCP 服务器**来驱动应用，因此
 - **没有 git 就没有 PR 阶段。** 没有 git 仓库（或没有提交）的项目同样有运行卡片——进度、日志、失败与恢复——但没有分支也没有 PR 步骤；卡片会明确说明。
 - **`@rail-N`。** 输入 `@` 并选择一条 rail 即可在消息中引用它，附带其 spec 以及空闲、忙碌或待决定的状态。
 
+## 子代理
+
+部分提供商可以把任务的一部分交给**子代理**——它们并行工作，并在代理回复后继续运行。由于子代理会让单次请求的成本成倍增加，它们**默认关闭**。
+
+- **按项目开启。** 打开项目的**设置 → 子代理**，开启**在此项目中允许子代理**。它适用于该项目的任务、探索和细化；Implement 流水线永远不受影响。无项目的任务遵循**应用设置 → AI 提供商 → 在无项目的任务中允许子代理**。
+- **选择由谁运行。** 在 **子代理运行方式** 中，默认的 **与任务代理相同** 会让任务自身的 CLI 原生启动它们：速度最快，并共享其提示缓存。也可以改选提供方、模型和推理强度来混用提供方——例如 Codex 任务搭配 Claude 子代理。已使用该提供方的任务保持原生并使用该模型；使用其他提供方时，Specrails 会自行启动每个子代理，冷启动可能更慢、更贵，但你能获得更多控制，并看到每个子代理的真实成本。切换前 Specrails 会请你确认，这些子代理在任务中会显示提供方标记。
+- **查看它们的工作。** 某条回复启动的代理会以一行紧凑的形式显示在该回复下方。它们工作时保持展开，全部完成后会折叠成一行摘要，显示总时长和 token。展开某一行可查看其结果和花费，或实时跟踪其活动。每次启动都会停留在对话中对应的位置，之后的启动不会与之前的混在一起。可在行内停止正在运行的代理，或在摘要行中全部停止。
+- **代理会自行跟进。** 后台代理完成后，代理会继续工作并发布它们的发现，标注为*在后台代理完成后继续*。
+- **更改设置是安全的。** 仍有代理在运行的任务会在它们完成后应用更改；任务会提示这一点，并提供**停止代理并立即应用**。
+- **不会在背后重新启动。** 因重启而中断的代理会保持“已中断”状态；**重新启动**只会起草一条消息，请代理重做该工作。
+
 ## 一些需要知道的事
 
 - **操作和自主会产生费用**，因为它们运行 AI。智能体会在执行会产生费用的操作前把它们摆到明面上；如果你只想查看和整理，就把级别保持在观察或编辑。

package/docs/guide/zh/settings/5-project-environment.md

@@ -0,0 +1,27 @@
+# 项目环境
+
+有些项目在运行时需要凭据，例如私有 npm 包所需的 `NODE_AUTH_TOKEN`。在 **项目设置 → 环境** 中，添加你的 rail 和 loop 需要的变量**名称**。Specrails 只保存名称，从不保存值。
+
+## 值从哪里来
+
+运行开始时，Specrails 会从它启动时的环境中读取每个已配置的名称。如果你从 Dock 或 Finder 打开 Specrails，该环境不包含你的 shell 配置文件导出的内容，因此 Specrails 还会从你的登录 shell（例如 `~/.zprofile` 或 `~/.zshrc`）读取缺失的名称。请把真实凭据放在 shell 配置文件中，而不是仓库里。
+
+检查会在项目打开时、你修改名称时以及之后定期在后台进行，因此较慢的配置文件不会拖慢你的运行。值只保存在该项目的内存中。
+
+## 如何阅读状态标签
+
+每个已保存的名称都会显示一个标签：
+
+| 标签 | 含义 | 处理方式 |
+|------|------|----------|
+| **已继承** | Specrails 启动时就带有该变量。 | 无需处理。 |
+| **来自登录 shell** | Specrails 从你的登录 shell 读取到了它。 | 无需处理。 |
+| **未定义** | 你的登录 shell 没有导出它。 | 在 shell 配置文件中添加 `export`。 |
+| **Shell 超时** | 你的登录 shell 启动时间过长。 | 精简配置文件，或调高 `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS`（默认 10 秒）。 |
+| **Shell 读取失败** | Specrails 无法读取你的登录 shell。 | 修复配置文件，或从终端启动 Specrails。 |
+
+将鼠标悬停在标签上可查看说明。修复配置文件后，点击 **重新检查**，无需重启 Specrails。
+
+如果运行开始时仍有名称未解析，其日志会显示一行 `[environment]`，写明变量和状态。运行仍会开始。值从不会出现在应用、日志或 MCP 工具中。
+
+在 Windows 上，Specrails 只使用它启动时的环境。

package/docs/internals/README.md

@@ -17,6 +17,7 @@ Start with [the modular architecture decision](modular-architecture.md),
 | [configuration.md](configuration.md) | Settings, env vars, kill switches, advanced flags |
 | [operations-runbook.md](operations-runbook.md) | Start/stop, port conflicts, recovery procedures, backups |
 | [core-runtime-updates.md](core-runtime-updates.md) | Core runtime discovery, durable package updates, version reporting and recovery after partial workspace refresh |
+| [agent-sessions.md](agent-sessions.md) | Core resident agent sessions in Desktop: host per scope, runner seam, projection, rebuild, sub-agent UI and rollout flag |
 | [programmatic-agent-runtime.md](programmatic-agent-runtime.md) | Paired Core build, per-role providers/local models, project settings, saved execution recovery and delivery boundaries |
 | [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 |