specrails-desktop 2.43.2 → 2.44.1

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-m5pKr1T6.js"></script>
+    <script type="module" crossorigin src="/assets/index-UnaJTMIy.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">
@@ -228,26 +228,26 @@
     <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-DzMjUcaN.js">
+    <link rel="modulepreload" crossorigin href="/assets/jobs-DMPU64ms.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-B-ynWTpn.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-BJB9RKJj.js">
+    <link rel="modulepreload" crossorigin href="/assets/settings-CCNZN5Q-.js">
     <link rel="modulepreload" crossorigin href="/assets/setup-Ba11l2JA.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-BOdS5_Iz.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-SnMX4MhW.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-RSMTyy7V.js">
+    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-DbGL_YOt.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-mjFZpHw1.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-gVGoWWiY.js">
     <link rel="modulepreload" crossorigin href="/assets/save-B6wGWwBR.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-BqbdPm_4.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-DXOcv1tn.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-Deg39peL.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-C843Y13h.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">
@@ -259,23 +259,23 @@
     <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-CSCqGr-Q.js">
+    <link rel="modulepreload" crossorigin href="/assets/jira-api-B2BBZQTx.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-YhD8rIEs.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-DSj5DprF.js">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-Cs9z2sdO.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-BIL-HxGy.js">
     <link rel="modulepreload" crossorigin href="/assets/button-Ccc9Dc-D.js">
-    <link rel="modulepreload" crossorigin href="/assets/project-repositories-DYhTvwQ1.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-D-RCaknl.js">
+    <link rel="modulepreload" crossorigin href="/assets/project-repositories-xSqimlaj.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-CZ_U_R3U.js">
     <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-B-wOHfLP.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-BNa1mdXq.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-BbRA6cb7.js">
     <link rel="modulepreload" crossorigin href="/assets/core-B3mKBIh5.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-IiQCcndQ.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-bgIHE8ep.js">
     <link rel="modulepreload" crossorigin href="/assets/event-Bt7f3wXe.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-D5n_jg_I.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-Bfj8HvX1.css">
   </head>
   <body>
     <div id="specrails-splash" aria-hidden="false" role="status" aria-label="Loading Specrails">

package/docs/README.md

@@ -8,6 +8,10 @@ project and choose which engine runs each task.
 
 If you're contributing to the app itself or building on its API, head over to [`internals/`](internals/) for the technical deep dive.
 
+## Exclusively for agents
+
+When asked to connect to Specrails MCP, read [the agent runbook](agents/mcp.md). It covers Claude, Codex, Kimi and Gemini, preserves existing servers and requires a real read-only verification.
+
 ## Start here
 
 1. [Getting started](getting-started.md) — install the app, register your first project, run your first pipeline. ~10 minutes.
@@ -27,7 +31,7 @@ If you're contributing to the app itself or building on its API, head over to [`
 | [Tracking cost](tracking-cost.md) | …you want to see what AI is costing you and which specs are the most expensive |
 | [Customising the app](customizing.md) | …you want to change theme, configure settings, set a budget, or turn on telemetry |
 | [Terminal panel](terminal.md) | …you want to use the built-in terminal: shortcuts, shell integration, drag-and-drop |
-| [MCP server](mcp.md) | …you want to drive the app from an MCP client (Claude Desktop, Cursor, your own agent) |
+| [MCP server](mcp.md) | …you want to drive the app from an MCP client (Codex, Claude Desktop, Cursor, your own agent) |
 | [CLI reference](cli.md) | …you want to drive specrails-desktop from the terminal instead of (or alongside) the dashboard |
 
 ## Platform-specific notes
@@ -51,6 +55,7 @@ If you're contributing to the app itself or building on its API, head over to [`
 - **"How much did I spend last week?"** → [Tracking cost](tracking-cost.md)
 - **"How do I change the theme?"** → [Customising the app › Themes](customizing.md#themes)
 - **"How do I set a daily budget?"** → [Customising the app › Budget](customizing.md#budget)
+- **"How do I connect Codex CLI or the desktop app?"** → [Codex MCP setup and verification](agents/mcp.md)
 - **"How do I connect an MCP client (Claude Desktop / Cursor)?"** → [MCP server](mcp.md#connecting-a-client)
 
 ## Internals

package/docs/agents/README.md

@@ -0,0 +1,13 @@
+# Documentation exclusively for agents
+
+When a person says “connect to the Specrails MCP”, use the [connection runbook](mcp.md). These instructions cover Claude Code, Codex CLI/desktop, Kimi Code and Gemini CLI. They require local discovery, a configuration-preserving registration and a real read-only verification.
+
+## Maintaining the public copy
+
+The canonical connection runbook is `docs/agents/mcp.md` in Specrails Desktop. Specrails Web keeps a reviewed copy in `src/content/for-agents/`. Its `docs:sync` command generates `/llms.txt`, `/for-agents/index.html` and the static Markdown runbook. These resources are usable without executing the documentation SPA.
+
+Desktop's `docs/guide/` and Web's `src/content/guide/` are separate article trees. Do not overwrite the Web guide with Desktop's tree: the Web guide has its own revision markers and current product structure. Update their MCP article links deliberately. Other Desktop languages point to the current English runbook.
+
+To import this runbook in a Web checkout, run `npm run docs:sync -- --desktop-source` followed by the quoted path to this Desktop checkout. To compare without writing, use `npm run docs:check -- --desktop-source` followed by that same path. Normal Web builds use their committed copy and do not need Desktop checked out.
+
+Review paired PRs together. Merging Desktop alone does not update specrails.dev. Web's release workflow builds and uploads `dist/` to Hostinger on a release or manual dispatch; importing, building and opening PRs do not deploy the site. After an authorized deployment, verify that the Markdown URLs return text, not the SPA shell.

package/docs/agents/mcp.md

@@ -0,0 +1,103 @@
+# For agents only: connect to Specrails MCP
+
+Use this runbook when a person asks Claude, Codex, Kimi or Gemini to connect to Specrails. Complete discovery, registration and a read-only verification for the requested client. Do not configure all four clients unless asked. If the tools are already loaded, test the existing connection before changing anything.
+
+This is an external agent connecting to Specrails Desktop. It is separate from choosing an AI provider inside Specrails. Connection authorization does not authorize starting missions, creating specs or changing permission tiers. If local files or the client configuration are inaccessible, complete the available checks and report the exact remaining step.
+
+## Discover the local bridge
+
+Keep **Specrails Desktop running on the same machine** and enable MCP in **Settings ▸ MCP**. Use the stdio bridge bundled with Desktop: it reads `~/.specrails/mcp.token` locally. Do not paste tokens into prompts, logs or configuration. This setup does not require the separate legacy `specrails-mcp` npm package or its hub.
+
+1. Inspect the requested client's existing `specrails` entry locally (for Codex, `codex mcp get specrails`). If it already points to the installed bridge, keep it. Preserve every other server and setting; never replace the whole Codex configuration. Do not share configuration output containing credentials.
+2. Open **Settings ▸ MCP ▸ Copy client config** in Specrails. Use its `command` and each `args` element separately. Some versions only copy `command: "specrails-mcp"`; that is usable only if the executable actually resolves in the client's PATH. It is not a guarantee that Desktop installed a global command.
+3. If the command does not resolve, locate the installed app's `binaries/specrails-mcp.js` and bundled Node executable. Verify that both files exist before registering them. In Codex, `command` is the Node executable and `args` contains the bridge script path; do not put a whole shell command into `command`.
+
+| Platform | How to locate the installed bridge |
+|---|---|
+| macOS | Inspect the installed `Specrails.app` bundle. Resources are under `Contents/Resources`; the example below applies only to `/Applications/Specrails.app`. Apps installed elsewhere need their actual paths. |
+| Windows | Inspect the installed app's resources for `binaries/specrails-mcp.js` and its bundled `node.exe`. Installation directories vary; preserve each complete path as one argument and use PowerShell quoting or TOML literal strings for backslashes. |
+| Linux | Inspect the installation's resource directory (or mounted/extracted AppImage) for `binaries/specrails-mcp.js` and bundled Node. Avoid a temporary AppImage mount path that disappears after exit. If unavailable, report the missing files instead of guessing a global executable. |
+
+Within the verified resource root, look for `binaries/specrails-mcp.js` and `runtimes/node/bin/node` (macOS/Linux) or `runtimes/node/node.exe` (Windows). Search only the identified installation if its layout differs. These are resource-relative candidates, not universal install locations. If you have no local filesystem access, ask for the installed paths or client configuration without credentials.
+
+For **macOS with this exact installation**, this Codex-only example first checks the files and then registers the bridge. For another client, use its registration below. Run the registration only if the existing entry is absent or you intend to update that entry:
+
+```bash
+test -x /Applications/Specrails.app/Contents/Resources/runtimes/node/bin/node &&
+test -f /Applications/Specrails.app/Contents/Resources/binaries/specrails-mcp.js &&
+codex mcp add specrails -- \
+  /Applications/Specrails.app/Contents/Resources/runtimes/node/bin/node \
+  /Applications/Specrails.app/Contents/Resources/binaries/specrails-mcp.js
+```
+
+For other installations, construct the invocation from the verified paths: `codex mcp add`, the name `specrails`, `--`, the quoted executable path, then each quoted argument. If Codex CLI is not in PATH, locate the installed CLI or use the client's MCP configuration UI; do not assume a universal CLI installation path. Codex uses TOML (`[mcp_servers.specrails]` with `command` and `args`), so do not paste the panel's `mcpServers` JSON directly into `config.toml`.
+
+Codex's default user configuration is `~/.codex/config.toml`; project configuration can also apply in trusted projects. CLI and desktop clients using the same local configuration can reuse the entry. Check that they use the same host and configuration home; a cloud task cannot launch your local bridge. See the [official OpenAI MCP documentation](https://developers.openai.com/codex/mcp).
+
+## Register only the requested client
+
+Check the installed client's version and help before editing. Prefer user scope for this machine-local app unless the user requested project scope. Preserve other servers, unrelated fields, existing permissions and file permissions. Inspect the effective entry first; if `specrails` already has a different purpose, resolve the name collision instead of replacing it. With JSON, parse and merge only `mcpServers.specrails`; invalid JSON is a diagnostic, never a reason to reset a file. Review the change locally without exposing secrets.
+
+| Client | Registration and effective configuration | Check |
+|---|---|---|
+| Claude Code | `claude mcp add --scope user --transport stdio specrails --` followed by the verified executable and arguments. User and local entries live in `~/.claude.json`; project entries use `.mcp.json`. The default CLI scope is local, so select scope explicitly. | `claude mcp get specrails`; `/mcp` in the client. Project approvals can block loading. |
+| Codex CLI / desktop | `codex mcp add specrails --` followed by the verified executable and arguments. TOML user configuration, normally `~/.codex/config.toml`, is shared by local Codex clients using that home. | `codex mcp get specrails`; inspect the actual conversation tool catalog. |
+| Gemini CLI | `gemini mcp add --scope user --transport stdio specrails` followed by the verified executable and arguments. Uses `mcpServers` in `~/.gemini/settings.json`; project scope uses `.gemini/settings.json` and is the CLI default. | `gemini mcp list`; `/mcp` in the client. Check allowed/excluded servers and tools. Do not add `--trust` merely to connect. |
+| Kimi Code | Merge the stdio entry into `~/.kimi-code/mcp.json` (or the configured `KIMI_CODE_HOME`), or project `.kimi-code/mcp.json`. Project entries override user entries. Kimi Code 0.27.0 does **not** expose `kimi mcp add`; do not confuse it with the older Python Kimi CLI. | `/mcp` shows connection status; `/mcp-config` edits entries interactively. A newly added file entry requires a new session. |
+
+The following commands are **alternatives**, not a script to install all clients. These macOS examples require the same two file checks shown above and no conflicting existing entry:
+
+```bash
+# Claude Code only
+claude mcp add --scope user --transport stdio specrails -- \
+  /Applications/Specrails.app/Contents/Resources/runtimes/node/bin/node \
+  /Applications/Specrails.app/Contents/Resources/binaries/specrails-mcp.js
+```
+
+```bash
+# Gemini CLI only
+gemini mcp add --scope user --transport stdio specrails \
+  /Applications/Specrails.app/Contents/Resources/runtimes/node/bin/node \
+  /Applications/Specrails.app/Contents/Resources/binaries/specrails-mcp.js
+```
+
+For Kimi Code, merge this macOS example into the chosen `mcp.json`, retaining the existing root object and other servers. Use the verified paths for other installations:
+
+```json
+{
+  "mcpServers": {
+    "specrails": {
+      "command": "/Applications/Specrails.app/Contents/Resources/runtimes/node/bin/node",
+      "args": ["/Applications/Specrails.app/Contents/Resources/binaries/specrails-mcp.js"]
+    }
+  }
+}
+```
+
+Claude Desktop is a separate client from Claude Code. If that is the requested host, merge this same `mcpServers` structure in its local MCP configuration through its settings; registering Claude Code alone is not proof that Claude Desktop is configured.
+
+Sources: [Claude Code MCP](https://code.claude.com/docs/en/mcp), [Gemini CLI MCP](https://geminicli.com/docs/tools/mcp-server/), [Kimi Code MCP](https://moonshotai.github.io/kimi-code/en/customization/mcp). Command shapes were also checked against installed help for Claude Code 2.1.265, Gemini CLI 0.49.0 and Kimi Code 0.27.0. Client configuration and live connection are separate checks.
+
+## Verify all three stages
+
+- **Registered:** the requested client's configuration check (for Codex, `codex mcp get specrails`) shows the expected stdio command and arguments. This only proves configuration was saved.
+- **Connected:** a real MCP session completes `initialize`, sends `notifications/initialized`, then receives `tools/list` without a protocol error. Inspect the returned catalog; tool counts vary by version and do not grant permission to every action.
+- **Usable in this conversation:** ask the agent to call `specrails_projects` with `{"action":"list"}` and inspect the real result (including `isError`). This is read-only. Use returned project IDs for subsequent calls, and read `specrails_guide` before operating the app. A successful empty project list is still a successful connection.
+
+If an agent has a protocol client but no loaded tools, it can perform the handshake and read-only call through the verified stdio bridge. Report that as bridge connectivity, separately from tool availability in the current conversation. Do not launch a rail or create a spec as a connection test.
+
+## Connection troubleshooting
+
+| Symptom | Check |
+|---|---|
+| App not running / connection refused | Start Specrails and check Settings ▸ MCP is enabled. Closing its window may leave it in the tray; quitting the app stops the server. |
+| Command not found / missing script | Verify the actual executable and script paths. Recheck after moving or updating the app. The generic panel command may not be installed in PATH. |
+| Registered, but no tools in this conversation | Check the desktop client's MCP status and effective config, including disabled servers/tools and project overrides. A saved entry does not retroactively prove a conversation loaded it. Verify in a new local session if needed; do not assume a reload command or promise an existing task will refresh automatically. |
+| Transport error | Launch the bridge as stdio; do not pass an HTTP URL as its executable. Direct HTTP clients use streamable HTTP at the panel's `/api/mcp` URL, not SSE-only transport. |
+| Wrong port | The bridge defaults to `4200`; it reads `SPECRAILS_MCP_PORT`, then `SPECRAILS_PORT`. For a custom app port, set `SPECRAILS_MCP_PORT` in the server's environment to the actual port. It does not discover arbitrary ports automatically. |
+| Missing token / 401 | Run the bridge as the same OS user as Specrails and check local token-file access without printing its contents. If using `SPECRAILS_REGISTRY_HOME`, it must point to the same registry home as the app. Reconnect after token rotation. Never copy the master `desktop.token`. |
+| Permission-tier error | Connectivity succeeded, but the requested action is restricted. Project listing needs only Read; enable other tiers only for the intended work. |
+
+## Report the result
+
+State the client and scope, whether the existing entry was reused or changed, whether `initialize` and `tools/list` succeeded, and whether the current conversation actually called `specrails_projects` successfully. Distinguish an empty list from a failed call. Report unavailable stages explicitly and give the next concrete step; do not claim success from registration alone. Never include tokens or full private configuration in the report.

package/docs/guide/de/integrations/5-mcp-server.md

@@ -1,5 +1,7 @@
 # Specrails von jeder KI aus steuern (MCP-Server)
 
+> **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude, Codex, Kimi and Gemini. It includes verified bridge discovery, registration and read-only checks.
+
 Specrails kann **sich selbst** für jeden KI-Assistenten bereitstellen, der das [Model Context Protocol](https://modelcontextprotocol.io) spricht — Claude Desktop, Claude Code, Cursor, Cline oder deinen eigenen Agenten. Schalte es ein, richte deinen Assistenten auf Specrails aus, und schon kannst du die ganze App per Chat steuern: *„Liste meine Projekte auf", „Erstelle eine Spec für Social-Login im API-Projekt", „Starte Rail 0 und sag mir, wenn es fertig ist", „Wie viel habe ich diese Woche ausgegeben?"*. Dein Assistent ruft im Hintergrund die Tools von Specrails auf, statt dass du dich durchklickst.
 
 Das ist die umgekehrte Richtung zu den Plugins und dem Feature „Meine freigegebenen MCPs": Diese lassen Specrails andere MCP-Server *nutzen*; dieses hier lässt andere Apps **Specrails** nutzen.

package/docs/guide/de/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # Pipeline-Telemetrie & Diagnose
 
-Wenn ein Pipeline-Job nicht so läuft, wie du es erwartet hast, liefert dir die Telemetrie eine detaillierte Aufzeichnung dessen, was die AI-CLI hinter den Kulissen tatsächlich getan hat. Sie ist **standardmäßig aus** und vollständig optional, pro Projekt – aktiviere sie nur dann, wenn du sie wirklich willst.
+Die Telemetrie zeichnet Pipeline-Diagnosen lokal auf. Sie ist für Projekte ohne gespeicherte Einstellung **standardmäßig aktiviert**. Du kannst sie pro Projekt deaktivieren; ausdrücklich gespeicherte Einstellungen bleiben erhalten.
 
 ## Was es ist
 

package/docs/guide/en/integrations/5-mcp-server.md

@@ -19,38 +19,11 @@ You stay in control of *what* an external AI may do through a set of permission
 
 All four tiers are granted out of the box, so a connected assistant can drive the whole app right away. Untick any tier you'd rather keep to yourself; if your assistant then tries something that tier covers, Specrails refuses with a clear message telling you which tier to switch back on.
 
-## Connecting your assistant
+## For agents only: connect your client
 
-The panel shows a ready-to-paste configuration block. The simplest, universal path is the bundled **bridge** (`specrails-mcp`): your assistant runs it, and it relays to Specrails for you. The bridge reads the access token locally, so **the token never appears in your assistant's config**.
+When a person asks an agent to connect, read the [dedicated MCP connection runbook](../../../agents/mcp.md). It covers Claude Code, Codex CLI and desktop, Kimi Code and Gemini CLI: locate the bundled bridge, preserve existing configuration, verify the real connection and diagnose failures. The web version is plain Markdown and needs no JavaScript.
 
-In a client like Claude Desktop or Cursor, the config looks like:
-
-```json
-{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
-```
-
-Clients that support remote HTTP MCP servers can instead point straight at `http://127.0.0.1:4200/api/mcp` with the token from the panel.
-
-### From the terminal: Claude Code, Gemini CLI, Codex CLI
-
-Copy your token from **Settings ▸ MCP ▸ Copy token**, then:
-
-```bash
-# Claude Code
-claude mcp add --transport http specrails http://localhost:4200/api/mcp \
-  --header "X-Desktop-Token: <your token>"
-
-# Gemini CLI
-gemini mcp add --transport http specrails http://localhost:4200/api/mcp \
-  --header "X-Desktop-Token: <your token>"
-
-# Codex CLI (stdio — register the bridge command shown in Settings ▸ MCP)
-codex mcp add specrails -- <bridge command from Settings ▸ MCP>
-```
-
-The `Authorization: Bearer <token>` header works too. If you changed the app port, swap `4200` for yours.
-
-Once connected, your assistant sees **22 tools** covering the whole app — projects, specs, rails and jobs, chat/Explore, agents, plugins, Jira, loops, the code explorer, analytics, settings — including a built-in **guide** tool it reads first so it understands how Specrails works without you explaining anything.
+Keep Specrails running and open **Settings ▸ MCP ▸ Copy client config**. Some versions return only `specrails-mcp`, which may not be on PATH; the runbook explains how to locate the actual executable and script. The bridge reads the token locally, so no token belongs in client configuration. Registration alone is not proof of connection: complete `initialize`, `tools/list`, and a read-only `specrails_projects` call with `{"action":"list"}`.
 
 Before acting, the assistant can use `specrails_context` for a current briefing on the project, specs, runs and Git state. Unavailable sections are reported explicitly; they do not mean the project is empty. `specrails_code(search)` finds source text, and `read_file` reads specific line ranges with continuation information when more content remains.
 

package/docs/guide/en/pipeline/3-batch-implement-and-multi-feature.md

@@ -95,3 +95,32 @@ There's no global concurrency limit to tune. Open the projects or rails you need
 - [Rails & jobs](rails-and-jobs) — the queue model in depth.
 - [The Job Detail view](the-job-detail-view) — watch a batch run live.
 - [Picking an engine per rail](picking-an-engine-per-rail) — Batch runs on any provider; Freestyle is available on Claude and Kimi.
+
+
+## Read the implementation result
+
+With a Core runtime that supports acceptance evidence, the completed run shows four
+separate states: implementation, validation, archive and delivery. “Verified with
+exceptions” means accepted requirement interpretations or failed/unavailable
+supplementary checks remain visible. “Pending host delivery” means Core has not
+performed the host's delivery work, even if the change has been archived.
+
+Open **Evidence, exceptions and phase timings** to inspect decisions, approval
+references, measurement scope and limitations, review findings and recorded phase
+times. Required checks and unresolved requirements block acceptance. A passing Node
+benchmark does not establish browser rendering performance. Material requirement
+changes need existing user/host authorization; minor interpretations can be accepted
+by the reviewer with a recorded reason and impact.
+
+Execution success describes the process. If the current runtime reports incomplete
+implementation or blocked/pending validation, Desktop settles the run as blocked
+and does not complete its tickets. Older or unavailable runtimes show acceptance
+evidence as unavailable; a successful process alone is not proof of acceptance.
+The result is a snapshot captured at completion, not a revalidation of later edits.
+
+The final counters distinguish executed steps, decider evaluations and agent turns.
+A built-in Implement run can have one step, zero decider evaluations and many agent
+turns. Core phase durations/attempts are shown when recorded; per-phase costs are
+unavailable because provider usage is attributed to loop steps. Valid full test
+receipts are reused until their inputs change; each phase does not need another
+identical full-suite execution.

package/docs/guide/en/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # Pipeline telemetry & diagnostics
 
-When a pipeline job doesn't go the way you expected, telemetry gives you a detailed, behind-the-scenes record of what the AI CLI actually did. It's **off by default** and entirely opt-in, per project — turn it on only when you want it.
+Telemetry records pipeline diagnostics locally. It is **on by default** for projects without a saved preference. You can turn it off per project; an explicitly saved choice is preserved.
 
 ## What it is
 
@@ -44,3 +44,12 @@ This is the bundle to grab when you want to understand a tricky run, keep a reco
 ## Turning it off
 
 Flip the toggle back off any time. New jobs stop recording immediately. Anything already captured stays on disk until it's compacted or you remove the project — nothing is sent anywhere or lost behind your back.
+
+
+## Completion evidence
+
+Loop history stores a terminal result independently of optional provider telemetry.
+It separates process execution from Core acceptance and delivery, and distinguishes
+steps, decider evaluations and agent turns. Phase durations and attempts come from
+Core's journal; no per-phase cost is inferred from the total. Older runtimes keep
+acceptance evidence unavailable. See the implementation result in the batch guide.

package/docs/guide/es/integrations/5-mcp-server.md

@@ -19,38 +19,11 @@ Tú mantienes el control de *qué* puede hacer una IA externa mediante un conjun
 
 Los cuatro niveles vienen concedidos de serie, así que un asistente conectado puede manejar toda la app desde el primer momento. Desmarca cualquier nivel que prefieras reservarte; si después tu asistente intenta algo que cubre ese nivel, Specrails lo rechaza con un mensaje claro que te indica qué nivel volver a activar.
 
-## Conectar tu asistente
+## Exclusivamente para agentes: conecta tu cliente
 
-El panel muestra un bloque de configuración listo para pegar. La vía más sencilla y universal es el **puente** (bridge) incluido (`specrails-mcp`): tu asistente lo ejecuta y este se encarga de retransmitir a Specrails por ti. El puente lee el token de acceso localmente, así que **el token nunca aparece en la configuración de tu asistente**.
+Cuando una persona pida al agente conectarse, consulta el [procedimiento de conexión MCP para agentes](../../../agents/mcp.md). Cubre Claude Code, Codex CLI y escritorio, Kimi Code y Gemini CLI: localizar el puente incluido, conservar la configuración, verificar la conexión real y diagnosticar fallos. La versión web es Markdown y no necesita JavaScript.
 
-En un cliente como Claude Desktop o Cursor, la configuración tiene este aspecto:
-
-```json
-{ "mcpServers": { "specrails": { "command": "specrails-mcp" } } }
-```
-
-Los clientes que admiten servidores MCP remotos por HTTP pueden, en su lugar, apuntar directamente a `http://127.0.0.1:4200/api/mcp` con el token del panel.
-
-### Desde la terminal: Claude Code, Gemini CLI, Codex CLI
-
-Copia tu token desde **Ajustes ▸ MCP ▸ Copiar token** y después:
-
-```bash
-# Claude Code
-claude mcp add --transport http specrails http://localhost:4200/api/mcp \
-  --header "X-Desktop-Token: <tu token>"
-
-# Gemini CLI
-gemini mcp add --transport http specrails http://localhost:4200/api/mcp \
-  --header "X-Desktop-Token: <tu token>"
-
-# Codex CLI (stdio — registra el comando del bridge que muestra Ajustes ▸ MCP)
-codex mcp add specrails -- <comando del bridge de Ajustes ▸ MCP>
-```
-
-La cabecera `Authorization: Bearer <token>` también funciona. Si cambiaste el puerto de la app, sustituye `4200` por el tuyo.
-
-Una vez conectado, tu asistente ve **22 herramientas** que cubren toda la app — proyectos, specs, rails y trabajos, chat/Explore, agentes, plugins, Jira, loops, el explorador de código, analíticas, configuración — incluida una herramienta de **guía** incorporada que lee primero para entender cómo funciona Specrails sin que tú tengas que explicar nada.
+Mantén Specrails en ejecución y abre **Ajustes ▸ MCP ▸ Copiar configuración de cliente**. Algunas versiones devuelven solo `specrails-mcp`, que puede no estar en PATH; el procedimiento explica cómo localizar ejecutable y script. El puente lee el token localmente: no lo copies en la configuración. Registrar no demuestra conexión: completa `initialize`, `tools/list` y una llamada de lectura a `specrails_projects` con `{"action":"list"}`.
 
 Antes de actuar, el asistente puede usar `specrails_context` para consultar el estado actual del proyecto, las specs, las ejecuciones y Git. Las secciones no disponibles se indican expresamente; no significan que el proyecto esté vacío. `specrails_code(search)` busca texto en el código y `read_file` lee rangos concretos de líneas, indicando cómo continuar cuando queda contenido.
 

package/docs/guide/es/pipeline/3-batch-implement-and-multi-feature.md

@@ -82,3 +82,33 @@ No hay límite global de concurrencia que ajustar. Abre los proyectos o rails qu
 - [Rails y jobs](rails-and-jobs) — el modelo de cola en profundidad.
 - [La vista de detalle del job](the-job-detail-view) — mira un batch ejecutarse en vivo.
 - [Elegir un motor por rail](picking-an-engine-per-rail) — Batch corre en cualquier proveedor; Freestyle está disponible con Claude y Kimi.
+
+
+## Interpretar el resultado de Implement
+
+Con un runtime de Core que admita evidencia de aceptación, el resultado muestra cuatro
+estados separados: implementación, validación, archivo y entrega. «Verificada con
+excepciones» conserva las interpretaciones aceptadas y los checks complementarios
+fallidos o no disponibles. «Pendiente del host» indica que Core no ha realizado la
+entrega que corresponde al host, aunque el cambio ya esté archivado.
+
+Abre **Evidencia, excepciones y tiempos por fase** para consultar decisiones,
+referencias de aprobación, alcance y limitaciones de las mediciones, conclusiones de
+revisión y tiempos registrados. Los checks obligatorios fallidos y los requisitos
+sin resolver bloquean la aceptación. Un benchmark de Node no demuestra el rendimiento
+de renderizado del navegador. Los cambios materiales requieren autorización previa
+del usuario o del host; el reviewer puede aceptar interpretaciones menores dejando
+constancia de su motivo e impacto.
+
+El éxito de ejecución describe el proceso. Si el runtime informa de implementación
+incompleta o validación bloqueada/pendiente, Desktop cierra el run como bloqueado y
+no completa sus tickets. Con runtimes antiguos o no disponibles, la evidencia aparece
+como no disponible: el éxito del proceso por sí solo no prueba la aceptación.
+El resultado se registra al terminar; no revalida modificaciones posteriores.
+
+Los contadores distinguen pasos ejecutados, evaluaciones del decider y turnos del
+agente. Un Implement integrado puede tener un paso, cero evaluaciones y muchos turnos.
+Se muestran tiempos e intentos por fase de Core cuando están registrados; el coste por
+fase no está disponible porque el consumo se atribuye a pasos del loop. Los receipts
+completos se reutilizan mientras sus entradas sigan vigentes: cada fase no necesita
+repetir la misma suite completa.

package/docs/guide/es/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # Telemetría del pipeline y diagnósticos
 
-Cuando un job del pipeline no sale como esperabas, la telemetría te ofrece un registro detallado, entre bambalinas, de lo que el CLI de IA hizo en realidad. Está **desactivada por defecto** y es totalmente opcional, por proyecto: actívala solo cuando la quieras.
+La telemetría registra los diagnósticos del pipeline en local. Está **activada por defecto** en los proyectos sin una preferencia guardada. Puedes desactivarla por proyecto; se respeta cualquier elección guardada explícitamente.
 
 ## Qué es
 
@@ -44,3 +44,13 @@ Este es el paquete que conviene tener a mano cuando quieres entender una ejecuci
 ## Cómo desactivarla
 
 Vuelve a apagar el interruptor cuando quieras. Los nuevos jobs dejan de registrar de inmediato. Lo que ya se capturó se mantiene en disco hasta que se compacta o eliminas el proyecto: nada se envía a ninguna parte ni se pierde a tus espaldas.
+
+
+## Evidencia al finalizar
+
+El historial del loop conserva el resultado final independientemente de la telemetría
+opcional del proveedor. Separa ejecución, aceptación de Core y entrega, y distingue
+pasos, evaluaciones del decider y turnos del agente. Los tiempos e intentos por fase
+proceden del registro de Core; no se deduce un coste por fase a partir del total. Con
+runtimes antiguos, la evidencia queda como no disponible. Consulta el resultado de
+Implement en la guía de ejecución por lotes.

package/docs/guide/fr/integrations/5-mcp-server.md

@@ -1,5 +1,7 @@
 # Piloter Specrails depuis n'importe quelle IA (serveur MCP)
 
+> **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude, Codex, Kimi and Gemini. It includes verified bridge discovery, registration and read-only checks.
+
 Specrails peut s'exposer **lui-même** à n'importe quel assistant IA qui parle le [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline, ou votre propre agent. Activez-le, pointez votre assistant vers Specrails, et vous pouvez piloter toute l'app en discutant : *« liste mes projets », « crée une spec pour la connexion sociale dans le projet API », « lance le rail 0 et préviens-moi quand c'est terminé », « combien ai-je dépensé cette semaine ? »*. Votre assistant appelle les outils de Specrails en coulisses, plutôt que de vous faire cliquer partout.
 
 C'est la direction inverse des fonctionnalités plugins et « Mes MCP approuvés » : celles-ci permettent à Specrails d'*utiliser* d'autres serveurs MCP ; ceci permet à d'autres apps d'utiliser **Specrails**.

package/docs/guide/fr/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # Télémétrie & diagnostics du pipeline
 
-Quand un job de pipeline ne se déroule pas comme prévu, la télémétrie vous offre un compte rendu détaillé et en coulisses de ce que la CLI d'IA a réellement fait. Elle est **désactivée par défaut** et entièrement optionnelle, projet par projet — ne l'activez que lorsque vous en avez besoin.
+La télémétrie enregistre les diagnostics du pipeline localement. Elle est **activée par défaut** pour les projets sans préférence enregistrée. Vous pouvez la désactiver par projet ; les choix explicitement enregistrés sont conservés.
 
 ## De quoi s'agit-il
 

package/docs/guide/it/integrations/5-mcp-server.md

@@ -1,5 +1,7 @@
 # Controlla Specrails da qualsiasi AI (server MCP)
 
+> **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude, Codex, Kimi and Gemini. It includes verified bridge discovery, registration and read-only checks.
+
 Specrails può esporre **se stesso** a qualsiasi assistente AI che parli il [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline o un tuo agente. Attivalo, punta il tuo assistente verso Specrails e potrai pilotare l'intera app chiacchierando: *"elenca i miei progetti", "crea una spec per il login social nel progetto API", "lancia il rail 0 e dimmi quando ha finito", "quanto ho speso questa settimana?"*. Il tuo assistente richiama gli strumenti di Specrails dietro le quinte, al posto tuo che clicchi qua e là.
 
 Questa è la direzione opposta rispetto alle funzionalità dei plugin e degli "MCP approvati da me": quelle permettono a Specrails di *usare* altri server MCP; questa permette ad altre app di usare **Specrails**.

package/docs/guide/it/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # Telemetria della pipeline e diagnostica
 
-Quando un job della pipeline non va come ti aspettavi, la telemetria ti offre un resoconto dettagliato e dietro le quinte di ciò che la AI CLI ha realmente fatto. È **disattivata per impostazione predefinita** e completamente opzionale, per ogni progetto — attivala solo quando ti serve.
+La telemetria registra i dati diagnostici della pipeline in locale. È **attivata per impostazione predefinita** nei progetti senza una preferenza salvata. Puoi disattivarla per progetto; le scelte salvate esplicitamente vengono rispettate.
 
 ## Cos'è
 

package/docs/guide/ja/integrations/5-mcp-server.md

@@ -1,5 +1,7 @@
 # 任意の AI から Specrails を操作する（MCP サーバー）
 
+> **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude, Codex, Kimi and Gemini. It includes verified bridge discovery, registration and read-only checks.
+
 Specrails は、[Model Context Protocol](https://modelcontextprotocol.io) を話す任意の AI アシスタント（Claude Desktop、Claude Code、Cursor、Cline、あるいは自作のエージェント）に対して、**自分自身**を公開できます。これをオンにしてアシスタントを Specrails に向ければ、チャットするだけでアプリ全体を操作できます。たとえば *「プロジェクト一覧を見せて」「API プロジェクトにソーシャルログインのスペックを作って」「レール 0 を起動して、終わったら教えて」「今週はいくら使った？」* といった具合です。あなたがあちこちクリックする代わりに、アシスタントが裏側で Specrails のツールを呼び出します。
 
 これは、プラグインや「My approved MCPs」機能とは逆方向の働きをします。それらは Specrails が*ほかの* MCP サーバーを*使う*ためのものですが、こちらは他のアプリに **Specrails** を使わせるためのものです。

package/docs/guide/ja/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # パイプラインテレメトリと診断
 
-パイプラインのジョブが思いどおりに進まなかったとき、テレメトリは AI CLI が実際に何をしたのかを、舞台裏まで詳しく記録して見せてくれます。**デフォルトはオフ** で、プロジェクトごとに完全に任意です。必要なときだけオンにしてください。
+テレメトリはパイプラインの診断情報をローカルに記録します。設定が保存されていないプロジェクトでは**デフォルトでオン**です。プロジェクトごとにオフにでき、明示的に保存された設定は維持されます。
 
 ## テレメトリとは
 

package/docs/guide/pt/integrations/5-mcp-server.md

@@ -1,5 +1,7 @@
 # Controlar o Specrails a partir de qualquer IA (servidor MCP)
 
+> **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude, Codex, Kimi and Gemini. It includes verified bridge discovery, registration and read-only checks.
+
 O Specrails pode expor-se **a si próprio** a qualquer assistente de IA que fale o [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Claude Code, Cursor, Cline ou o seu próprio agente. Ative-o, aponte o seu assistente para o Specrails e poderá conduzir a app inteira conversando: *"lista os meus projetos", "cria uma spec para login social no projeto da API", "lança o rail 0 e avisa-me quando terminar", "quanto gastei esta semana?"*. O seu assistente invoca as ferramentas do Specrails nos bastidores em vez de ser você a clicar por toda a parte.
 
 Este é o sentido oposto das funcionalidades de plugins e "Os meus MCPs aprovados": essas permitem que o Specrails *use* outros servidores MCP; esta permite que outras apps usem o **Specrails**.

package/docs/guide/pt/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # Telemetria do pipeline e diagnóstico
 
-Quando um job do pipeline não corre como esperava, a telemetria dá-lhe um registo detalhado, dos bastidores, do que a CLI de IA fez de facto. Está **desativada por omissão** e é totalmente opcional, por projeto — ative-a apenas quando quiser.
+A telemetria regista os diagnósticos do pipeline localmente. Está **ativada por omissão** nos projetos sem uma preferência guardada. Pode desativá-la por projeto; as escolhas guardadas explicitamente são respeitadas.
 
 ## O que é
 

package/docs/guide/zh/integrations/5-mcp-server.md

@@ -1,5 +1,7 @@
 # 从任意 AI 操控 Specrails（MCP 服务器）
 
+> **For agents (English):** use the [current connection runbook](../../../agents/mcp.md) for Claude, Codex, Kimi and Gemini. It includes verified bridge discovery, registration and read-only checks.
+
 Specrails 可以把**自己**暴露给任何会说 [Model Context Protocol](https://modelcontextprotocol.io) 的 AI 助手——Claude Desktop、Claude Code、Cursor、Cline，或者你自己的 agent。打开这个功能，把你的助手指向 Specrails，你就能靠聊天来驱动整个应用：*「列出我的项目」「在 API 项目里为社交登录创建一份规格」「启动 rail 0，跑完了告诉我」「我这周花了多少钱？」*。你的助手会在幕后调用 Specrails 的工具，而不用你点来点去。
 
 这和插件以及「My approved MCPs」功能的方向正好相反：那些功能是让 Specrails 去*使用*别的 MCP 服务器；而这个功能是让别的应用来使用 **Specrails**。

package/docs/guide/zh/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -1,6 +1,6 @@
 # 流水线遥测与诊断
 
-当一个流水线任务的运行结果不如你所料时，遥测能为你提供一份详尽的幕后记录，告诉你 AI CLI 实际做了什么。它**默认关闭**、完全按需开启、按项目独立配置——只有在你需要时才开启它。
+遥测在本地记录流水线诊断信息。未保存偏好的项目**默认开启**。可以按项目关闭；明确保存的选择会保留。
 
 ## 它是什么