specrails-desktop 2.58.1 → 2.59.1

package/docs/guide/en/integrations/1-ai-providers.md

@@ -1,108 +1,19 @@
-# AI providers (Claude, Codex, Gemini, Kimi)
+<!-- guide-revision: mission-first-v1 -->
 
-Specrails isn't tied to a single AI. Explore, rails, chat, loops, and the
-terminal's "Open AI CLI" action run through a provider adapter; pure-output
-surfaces additionally require a safe tool policy. You choose the provider set
-for a project and can switch among compatible engines per invocation.
+# Connect an AI provider
 
-## The four providers
+Specrails coordinates your authenticated Claude or Codex CLI. Provider installation, account access and model billing remain separate from the application.
 
-| Provider | CLI | Made by | Notes |
-|---|---|---|---|
-| **Claude** | `claude` | Anthropic | Native billed-cost events and persistent interactive stdin. |
-| **Codex** | `codex` | OpenAI | Needs codex `0.128.0+`. Reads its MCP servers from your global `~/.codex/config.toml`. |
-| **Gemini** | `gemini` | Google | Needs gemini `0.11.0+`. Uses native telemetry and a `GEMINI.md` instructions file. |
-| **Kimi Code** | `kimi` | Moonshot AI | Needs Kimi Code `0.27.0+`. Uses CLI-only `-p` execution and `.kimi-code` directory-form skills. |
+## Connect and verify
 
-All four are registered by default. A provider is selectable in **Add Project**
-when its CLI is installed, executable, and on `PATH`. Once its `--version`
-command works in a fresh terminal, Specrails can use it. Kimi users must also
-complete `kimi login`; the setup probe does not spend quota merely to test
-authentication.
+Install the desired CLI using its official instructions and sign in with the account you intend to use. Check availability in Specrails, then select a supported model and settings for the mission or rail.
 
-## Providers are detected automatically
+A successful discovery check does not guarantee quota or network availability for the next call. Resolve authentication and compatibility errors before retrying an implementation.
 
-You never pick providers per project. Specrails detects every provider CLI
-installed on your machine and makes **all of them** available to **every**
-project, always. Each surface then checks the provider's advertised
-capabilities. See [Using Kimi](../../../kimi.md) for Kimi's exact matrix.
+## Understand the boundary
 
-If a provider you want doesn't show up anywhere, it's almost always because the
-CLI isn't installed or isn't on your `PATH`. Install it, sign in, and switch
-back to the app — detection re-runs on focus and the provider appears
-everywhere on its own, with its project workspace surface assembled in the
-background. A provider that's installed but not signed in still appears, with
-a *Not signed in* badge on the engine selectors.
+The app keeps project records locally, while model requests and configured integrations may send context outside your machine. Choose which references and attachments to provide with that in mind.
 
-A few things worth knowing about multi-provider machines:
+Capabilities differ: reasoning controls, structured responses, subagents and active-turn steering are not interchangeable across providers. See [provider execution settings](/docs/pipeline-picking-an-engine-per-rail) and [steering](/docs/missions-steering-and-receipts).
 
-- **One provider behaves exactly like before.** If only a single provider is detected, you'll never see a provider picker anywhere — the app stays clean and simple.
-- **Capability checks drive the sidebar.** A section is visible when at least
-  one detected provider supports it; inside it, engine-scoped affordances offer
-  only the capable providers. Kimi advertises profiles, custom roles, and
-  Freestyle; it does not advertise structured actions that require an
-  enforceable no-tools boundary.
-- **Nothing is locked.** Installing or removing a provider CLI updates every
-  project automatically — there is no per-project provider setting to manage.
-
-## Picking a provider per invocation
-
-The real payoff of a multi-provider project is choosing the right AI for each task — without changing any global setting. Wherever an AI runs, a small provider picker appears (only when the project has more than one):
-
-- **Add Spec** — an engine selector lets you Explore with a compatible
-  provider. Quick Spec only lists providers that can enforce its pure-output
-  boundary; Kimi uses Explore or the agentic Quick Launcher instead.
-- **Rail header** — pick the engine, model, profile, and supported reasoning
-  effort for that rail.
-- **Terminal** — the "Open AI CLI" (Sparkles) button opens a provider menu so you can drop into any installed CLI in that project's directory.
-
-Your choice is remembered per project, defaulting to the primary provider, so you don't have to re-pick every time.
-
-## Capability differences
-
-The application exposes the same provider-independent workflows where the CLI
-contract can support them. Native telemetry and transport still differ:
-
-- **Claude** reports billed USD cost and supports a long-lived stdin chat
-  transport.
-- **Codex and Gemini** report enough usage to estimate cost from the local rate
-  card.
-- **Kimi** emits text, tool activity, errors/retries, and a resumable session
-  hint, but no authoritative token or USD-cost envelope. Those fields remain
-  unavailable.
-- **Kimi user-global MCP** cannot be isolated per child process. Specrails uses
-  additive project `.kimi-code/mcp.json` integration and does not expose the
-  Claude-style "load my approved user MCPs" toggle for Kimi.
-- **Kimi `-p` permission mode** is autonomous and offers no per-invocation
-  native equivalent of Claude's `--tools __none__` or Codex's read-only
-  sandbox. Quick Spec, AI Edit, Contract Refine, SMASH/Re-SMASH, Project
-  Builder blueprint/milestone generation, Loop Decider, file summary and
-  construction-story AI, and Agent Studio generation/test/refine are
-  therefore hidden or rejected before spawn. AI auto-title uses a
-  deterministic fallback.
-- Kimi still supports Project/Agent Chat, Explore/proposals, agentic Quick
-  Launcher commands (including `/opsx:ff`), rails, loops without a Decider,
-  profiles/manual roles, terminal, project MCP, Serena, attachments, and
-  truthful invocation metadata.
-
-## Cost tracking across providers
-
-The **Analytics** page tracks every invocation regardless of provider. Claude
-cost is provider-reported; Codex/Gemini values may be estimated from the rate
-card. Kimi invocation duration, outcome, model, and session are recorded, while
-cost and token fields stay null when the CLI did not report them.
-
-## Troubleshooting
-
-- **A provider I installed isn't offered.** Confirm the CLI is on your `PATH`
-  (`claude --version`, `codex --version`, `gemini --version`, or
-  `kimi --version`) in a fresh terminal.
-- **Kimi reports a login/model error.** Run `kimi login`, then retry. Specrails
-  intentionally avoids a billable setup prompt.
-- **Codex MCP servers aren't loading in chat.** Codex reads MCP servers from your global `~/.codex/config.toml` — register them there with `codex mcp add`.
-- **Emergency disable.** A provider can be turned off app-wide via an environment variable (`SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0`). This only hides the provider from *selection*; it's rarely needed.
-
-## See also
-
-The dedicated [Kimi provider guide](../../../kimi.md), Codex guide, and Gemini
-guide cover setup and provider-specific behavior in depth.
+The Sonnet selection runs Claude Sonnet 5.5 (`claude-sonnet-5-5`). [Anthropic](https://platform.claude.com/docs/en/models/sonnet-5-5/overview).

package/docs/guide/en/integrations/2-plugins.md

@@ -34,11 +34,3 @@ Under the hood the install is *surgical and additive*: it only adds its own entr
 - **Rails.** Before a rail runs, Specrails checks which plugins are installed and healthy, and makes those tools available to the agent for that job. A degraded plugin is simply skipped for that run — the rail still launches normally. Each job records a snapshot of which plugins were active, which you can see in the job's diagnostic export.
 - **Chat.** Chat automatically picks up your project's MCP config, so installed plugins are available there too.
 - **Setup.** Plugins are ignored while a project is still being set up — they come into play once the project is ready.
-
-## Provider notes
-
-Plugins are provider-aware. Serena currently supports Claude through `.mcp.json`, Codex through `codex mcp add` with an isolated per-project `CODEX_HOME`, and Kimi through `.kimi-code/mcp.json`. A provider appears only when the plugin manifest declares support; Serena is therefore not offered for Gemini. The Jira card is provider-agnostic and shows for everyone — see the Jira guide.
-
-## Reserved files
-
-Plugins manage a small, well-defined set of files: the provider's native MCP configuration, state under `.specrails/plugins/`, and (for Claude plugins that need one) an agent fragment at `.claude/agents/custom-<plugin>.md`. Kimi entries live in `.kimi-code/mcp.json`; the app never writes Claude-only fragments for Kimi or blindly overwrites any provider config.

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

@@ -21,7 +21,7 @@ All four tiers are granted out of the box, so a connected assistant can drive th
 
 ## For agents only: connect your client
 
-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.
+When a person asks an agent to connect, read the [dedicated MCP connection runbook](../../../agents/mcp.md). It covers Claude Code and Codex CLI and desktop: locate the bundled bridge, preserve existing configuration, verify the real connection and diagnose failures. The web version is plain Markdown and needs no JavaScript.
 
 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"}`.
 

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

@@ -20,14 +20,6 @@ The header has a **project selector** (like Cursor's). Pick a project and everyt
 
 Picking a project here **does not** move your dashboard — the agent's target and what you're looking at are independent.
 
-## Provider and model
-
-Just above the message box you choose the **provider** (Claude, Codex, Gemini,
-or Kimi) and its **model**. Each provider has its own model list, and switching
-provider starts a fresh session with that provider's default model. Kimi turns
-use external `kimi -p` processes and resume only from a successful
-`session.resume_hint`.
-
 ## Permission levels — you hold the leash
 
 The agent can touch the whole app, so you decide how much freedom it has with a **level** you change live by pressing **Shift+Tab** (the same cycle Claude Code uses). Each level includes everything below it:
@@ -41,14 +33,6 @@ The agent can touch the whole app, so you decide how much freedom it has with a
 
 Start on **Observe** and raise the level only when you want the agent to act. If it tries something above the current level it stops and tells you exactly which level to switch on — it never works around the limit. This is separate from the Settings ▸ MCP tiers, which govern *external* assistants; the level here is just for this in-app agent.
 
-With Kimi, the levels still gate which **Specrails MCP tools** Desktop exposes,
-but they do not turn upstream `kimi -p` into a filesystem sandbox: prompt mode
-automatically approves Kimi-native tools. Use Kimi Agent Chat only where that
-autonomous posture is intended. Safety-sensitive pure-output operations
-(Quick Spec, AI Edit, Contract Refine, SMASH/Re-SMASH, Project Builder
-generation, Loop Decider, Code Explorer AI transforms, and Agent Studio
-automation) are rejected server-side before spawn.
-
 ## A few things you can ask
 
 Once you're on **Operate**, try:
@@ -65,7 +49,6 @@ Replies stream in smoothly and land formatted (headings, tables, lists), each wi
 
 ## Handy touches
 
-- **Super specs from a conversation.** Ask the agent to *shape* a spec with you instead of one-shotting it: it reads the real code first, interviews you briefly, and shows the evolving draft as a live card right in the conversation. On providers with a safe structured-action policy, your approval can enrich it with a **Contract Layer**. Kimi can shape and create the proposal, but Contract Refine stays unavailable.
 - **Click what it mentions.** In a project-pinned mission, spec numbers (`#12`) and job/run ids in the agent's replies are clickable chips — a spec opens the board's detail modal, a job id opens the live job view. If the reference no longer exists you get a quiet "not found" note.
 - **The implementation card stays in sight.** When the agent implements specs, a live card tracks the work — and while it needs something from you (create the PR, publish it, retry, discard) it stays **pinned just above the message box**, however far the conversation scrolls; its place in the history shows a slim "pinned above" marker instead. Several active cards stack as small chips (click one to bring it forward), and a chevron minimizes the card to a slim bar. Once the PR is published — or the work is merged or discarded — the card settles back into the conversation history.
 - **Prompt history.** With the box empty, press **↑**/**↓** to browse what you asked before (shown dimmed while you scroll); start typing to edit it, or hit Enter to send.

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

@@ -24,10 +24,6 @@ Not available on local engines: agent profiles and custom roles, SMASH / Contrac
 
 > Missions need a **large context window** on the server (64k tokens or more): the operator prompt plus the Specrails tool schemas are big. Chat and Explore are fine at 32k. If a turn fails with *exceeds the available context size*, raise the window (Ollama `OLLAMA_CONTEXT_LENGTH`, llama.cpp `-c`, LM Studio *Context Length*).
 
-## Only a local engine installed?
-
-Nothing to configure. Specrails offers the engines your machine can actually run and picks the default with one rule everywhere: an installed CLI (Claude → Codex → Gemini → Kimi), otherwise the first local engine whose endpoint answers. On a machine with just a local endpoint, rails, Add Spec, chat, **agent missions and the Project Builder** all start on it — no selector to touch. An engine whose server is down is simply not offered until it answers again. Existing missions keep the engine they were created on; the selector still lets you switch.
-
 ## Choosing a model
 
 Quality depends on the model, not on Specrails. For rails use a tool-calling-tuned coder model of 30B parameters or more; smaller instruct models are fine for chat, Explore and Quick specs. Try **Freestyle** or an Explore session before trusting a full implement rail to a new model.

package/docs/guide/en/pipeline/1-rails-and-jobs.md

@@ -35,8 +35,7 @@ That's it. The rail spins up an AI CLI process in the right execution context an
 | **Status pill** | `idle`, `running`, or `failed`. There's no separate "completed" — a rail returns to `idle` when its job finishes cleanly. |
 | **Spec list** | The IDs assigned to this rail. Drag more in, drag them out to detach. |
 | **Loop picker** | The Loop this rail runs — a built-in (`Implement` / `Freestyle` / `SDD Quick (OpenSpec)`) or a custom loop. See the table below. Persisted per rail. |
-| **Profile picker** | Which provider-scoped agent profile runs (Claude and Kimi rails). Only appears once the effective provider has at least one profile. |
-| **Engine selector** | Which installed provider runs this rail — Claude, Codex, Gemini, or Kimi. Only renders when the project has more than one provider. See [Picking an engine per rail](picking-an-engine-per-rail). |
+| **Profile picker** | Which provider-scoped agent profile runs (Claude rails). Only appears once the effective provider has at least one profile. |
 | **▶ Play / ■ Stop** | Start or cancel. |
 
 ### What a rail runs: Loops
@@ -46,24 +45,12 @@ A rail runs a **Loop** — the recipe for the work. Two loops are **built in** a
 | Built-in loop | Command | What it does |
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | One job covering all specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. The everyday default. |
-| **Freestyle** | Freestyle | A capable provider implements each spec autonomously, **bypassing** the pipeline. One independent job per spec. Claude and Kimi support it. |
+| **Freestyle** | Freestyle | A capable provider implements each spec autonomously, **bypassing** the pipeline. One independent job per spec. Claude support it. |
 
 To run several specs, put related ones (up to 3) on one rail — `Implement` runs them as one aggregate job — or spread independent specs across several rails: each git-backed rail runs in parallel in its own isolated worktree.
 
-Freestyle is the odd one out: it skips the agent chain and hands the capable
-provider the raw spec to work on with native tools. It's open-ended, so
-pressing Play opens a confirmation first, and its model picker follows that
-provider's catalog. Claude uses its persistent live-session flow; Kimi uses an
-owned agentic `kimi -p` process and has no persistent stdin.
-
 The built-ins are editable, too: edit one in the Loop Builder and publish it, and every rail that picks it runs your version (use **Restore original** to go back).
 
-Beyond the built-ins, you can **build your own loops** — repeat a verify → fix
-→ verify cycle until a goal is met, chain shell commands between AI steps, and
-more. Kimi runs loops without a Loop Decider; its `-p` transport cannot enforce
-the Decider's pure-output verdict boundary. Those custom loops appear in the
-same Loop picker. That's the next big idea: [The Loop Builder](the-loop-builder).
-
 ## The job queue
 
 Every time you press Play, the rail run becomes a **job**. The most important rule to internalise:
@@ -90,14 +77,6 @@ Click any card to open the **Job Detail view**, where the live streaming log and
 
 Click **■ Stop** on the rail header. The app sends `SIGTERM` to the subprocess, waits **5 seconds** for a clean exit, then `SIGKILL`s it. Nothing is left half-spawned.
 
-## If a rail won't launch
-
-If you pick an engine whose CLI isn't installed on your machine, the launch
-**fails fast** instead of starting a broken job — nothing spawns. Install the
-missing provider CLI ([Using Codex](../integrations/using-codex),
-[Using Gemini](../integrations/using-gemini), or
-[Using Kimi](../../../kimi.md)) and launch again.
-
 ## Stopping everything
 
 If something looks wrong:
@@ -110,4 +89,3 @@ If something looks wrong:
 
 - [The Loop Builder](the-loop-builder) — what a rail runs, and how to build your own loops.
 - [The Job Detail view](the-job-detail-view) — phases, live metrics, ticket cards.
-- [Picking an engine per rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini vs Kimi.

package/docs/guide/en/pipeline/2-the-job-detail-view.md

@@ -94,9 +94,6 @@ A few things worth knowing:
 - **The totals line is real.** The composer shows a live `N turns · $X` summary, summed from each completed turn's actual usage — consistent with this page's no-guesses promise.
 - **Two ways a session ends.** Most jobs **wrap up on their own**: the moment a turn finishes with no messages queued, the session settles and the job completes — your messages are optional steering, never an obligation. A subtle **Wrap up now** action ends it early with everything produced so far. **Freestyle** jobs are the exception: they idle between turns and wait for you to click **Finalize** — that's their design, a back-and-forth session you close when you're done.
 - **Loop runs route to the active step.** On a custom or built-in loop, your message reaches the **AI step that is running right now**. Between steps (while the Loop Decider thinks, or a shell command runs) the composer shows a short *"Waiting for the next step…"* state — your drafted text is kept, and sending re-enables when the next AI step starts. **Settle this step** ends the current step early and lets the loop advance with what it produced.
-- **Persistent interaction is Claude-only.** Codex, Gemini, and Kimi jobs run
-  one-shot — no composer appears. Kimi chat surfaces resume by spawning a new
-  `kimi --session=<id> -p` process after a successful resume hint.
 
 ## Diagnostic export
 

package/docs/guide/en/pipeline/4-picking-an-engine-per-rail.md

@@ -1,74 +1,19 @@
-# Picking an engine per rail
+<!-- guide-revision: mission-first-v1 -->
 
-Specrails desktop treats **Claude Code**, **Codex CLI**, **Gemini CLI**, and
-**Kimi Code** as first-class engines. A project can install any compatible
-combination and, when more than one is present, choose which engine runs each
-rail.
+# Choose a provider and its capabilities
 
-## When the selector appears
+Execution settings belong to the chosen provider. A familiar model name does not imply that every provider supports the same reasoning, structured output or approval controls.
 
-The **engine selector** lives in the rail header, right alongside the mode control. It only renders when the project has **more than one** provider installed.
+## Check availability first
 
-> **Single-provider projects behave byte-identically.** If a project has just one engine, no selector shows and nothing about provider selection changes — it just runs on that engine. The selector is purely for multi-provider projects.
+Authenticate the provider CLI and confirm its status in Specrails. Choose among the models and effort values offered by that provider's controls. An installed CLI can still fail because its session, quota or remote service is unavailable.
 
-When it does appear, your choice is **per rail and per launch** — different rails can run different engines, and your pick is remembered per project (defaulting to the project's primary engine).
+Claude and Codex have different adapters. Unsupported combinations should fail before a loop starts; for example, a step requiring a structured no-tools response cannot be assumed to work with every provider.
 
-## How to pick an engine
+## Use the right level of control
 
-1. Make sure the rail's engine selector is showing (project has 2+ providers).
-2. Click it and choose **Claude**, **Codex**, **Gemini**, or **Kimi**.
-3. Launch the rail with **▶ Play**.
+A rail's provider/model choice controls its execution. Role profiles and per-agent routing depend on the provider and on the Core workflow Desktop installed in the project; inspect the effective configuration rather than assuming a profile changes every call.
 
-The selected engine runs every phase of that rail's pipeline. If the chosen engine's CLI isn't installed, the launch fails fast — nothing spawns. Install the missing CLI and try again.
+When comparing runs, keep the same spec, repository revision and verification criteria. Treat reported, estimated and unavailable cost separately. See [profiles](/docs/agents-profiles-and-the-balanced-default) and [usage](/docs/insights-analytics-and-cost-tracking).
 
-## What each engine is good at
-
-All four run the standard **Implement** pipeline. Here's a practical guide to choosing:
-
-| Engine | Reach for it when… | Notes |
-|--------|--------------------|-------|
-| **Claude** | You want native billed cost, persistent job interaction, and the richest hard tool-policy controls. | Supports profiles, Freestyle, and structured transforms such as Contract Layer/SMASH. |
-| **Codex** | You prefer the OpenAI Codex CLI or want to compare implementations across providers. | `codex` ≥ 0.128.0. No native cost reporting — the app fills in cost from its rate card. Profiles don't apply. |
-| **Gemini** | You want Google's Gemini CLI, native telemetry, or a cheaper run for routine specs. | `gemini` ≥ 0.11.0 (set `GEMINI_API_KEY`). Native OTLP telemetry. Profiles don't apply. |
-| **Kimi** | You want Kimi Code's autonomous agentic CLI for implementation, Freestyle, or loops without a Decider. | External `kimi` ≥ 0.27.0. Profiles/manual roles and K3 low/high/max effort are supported; tokens and USD cost are unavailable. |
-
-### Capability differences
-
-A few things need a provider with the matching capability:
-
-- **Agent profiles** — Claude and Kimi support provider-scoped profiles. Codex
-  and Gemini rails use legacy mode.
-- **Freestyle** — Claude and Kimi support this autonomous,
-  pipeline-bypassing mode with provider-specific models.
-- **Loop Decider** — Kimi runs loops without a Decider. Its `continue`/`stop`
-  verdict needs a pure-output boundary unavailable in `kimi -p`.
-- **Structured spec and read-only AI transforms** — Quick Spec, AI Edit,
-  Contract Layer, SMASH/Re-SMASH, Project Builder generation, file summary/
-  construction story, and Agent Studio automation are unavailable for Kimi.
-
-In mixed Claude/Kimi projects, profiles and integration state are scoped to the
-selected provider; an identically named profile does not leak across engines.
-
-## A practical workflow
-
-Multi-provider projects shine when you want to **compare** or **cost-tune**:
-
-- **Compare implementations.** Put the same spec on two rails, set one to Claude and one to Codex, launch both (across projects, or one after the other in the same project's queue), then use the **Compare** button on the Jobs page to diff the results.
-- **Cost-tune by spec.** Run high-stakes specs on Claude with a `max` profile; run routine cleanup specs on Gemini to save on spend. Filter `/analytics` by engine to see the breakdown.
-- **Default sensibly.** Set your most-used engine as the project's primary so rails default to it, and only switch per-rail when a specific spec wants a different engine.
-
-## Things to keep in mind
-
-- **Provider selection is immutable after project creation** (v1). You choose installed providers when you add the project; there's no Settings toggle to add or remove one later.
-- **Available metrics are always tracked.** Codex/Gemini cost uses a rate card;
-  Kimi has no authoritative token or USD-cost stream, so those fields remain
-  unavailable rather than becoming a fabricated estimate.
-- **The terminal's "Open AI CLI" button** also offers a provider picker on multi-provider projects, if you'd rather drive a CLI by hand.
-
-## Where to go next
-
-- [Using Codex](../integrations/using-codex) — install and sign in.
-- [Using Gemini](../integrations/using-gemini) — install, `GEMINI_API_KEY`, telemetry.
-- [Using Kimi](../../../kimi.md) — external CLI setup and complete capability matrix.
-- [Rails & jobs](rails-and-jobs) — the queue and launch flow.
-- [Tracking cost](../analytics/tracking-cost) — per-engine cost breakdown.
+For a mission launch, loop steps inherit the mission provider, model and effort unless an agent explicitly overrides them in the loop editor. General settings manage provider connections; the previous Provider defaults block and the Roles selector are no longer offered.

package/docs/guide/en/pipeline/5-the-loop-builder.md

@@ -28,7 +28,6 @@ A **loop** is the *recipe* for the work; a **rail** is the *lane* that runs it a
 
 - Loops live in the **Loops** section (left sidebar, alongside your projects) — they are **global**, shared across every project.
 - A rail **picks a loop** in its header (the Loop picker) and runs it when you press Play.
-- The **rail** decides the provider, model and supported reasoning effort — *not* the loop's steps. The same capability-compatible loop runs on Claude, Codex, Gemini, or Kimi depending on the rail.
 
 So: build a loop once, then pick it on any rail in any project.
 
@@ -52,11 +51,6 @@ A loop is a graph of **nodes** connected by **edges** (the arrows). Each node is
 
 Edges connect the steps in order. The **Loop Decider** has two labelled outputs — **continue** and **stop** — so you wire "not done yet" back into the work and "done" out to an End.
 
-> **Kimi:** AI and shell steps are supported, but a graph containing a Loop
-> Decider is not. The verdict is a constrained pure-output action and Kimi
-> 0.27 `-p` cannot enforce its no-tools boundary; Desktop rejects the run before
-> it starts.
-
 ### Writing step text
 
 Inside any AI Step or Decider you can reference:
@@ -73,7 +67,6 @@ A loop that never stops would burn money forever, so every run has three guards
 |-------|--------------|
 | **Max iterations** | Hard cap on how many times the Decider may loop back, regardless of its verdict. |
 | **Timeout (min)** | Wall-clock limit for the whole run. |
-| **Max cost ($)** | *Optional.* Stops the loop once the accumulated cost crosses your budget. Checked **between steps** (a step's cost is only known once it finishes), so it may overshoot by one step. On Claude the cost is exact; on Codex and Gemini it's an estimate. Kimi reports no native token/USD envelope, so a cost cap cannot derive authoritative Kimi spend. Leave it empty for no cap. |
 
 ## Building with confidence
 

package/docs/guide/en/specs/2-add-spec-quick-mode.md

@@ -2,11 +2,6 @@
 
 Quick mode is for when you already know what you want. You type your idea, the AI writes the full spec, and it lands on your board as a **Todo**. No back-and-forth — just describe it and go.
 
-> **Kimi is not offered for Quick Spec.** Kimi 0.27 `-p` automatically
-> approves tools and cannot enforce this form's pure-output boundary. Desktop
-> rejects direct Kimi requests before spawn. Use agentic Explore, Raw, or a
-> Quick Launcher command such as `/opsx:ff` instead.
-
 ## Create a spec in Quick mode
 
 To create a spec quickly:
@@ -24,12 +19,6 @@ That's the whole flow. Everything below is optional fine-tuning.
 
 **Model** — by default the AI picks a sensible model. You can override it per spec from the model picker if you want a faster or more capable one.
 
-**Engine** — if your project has more than one **compatible** AI provider
-installed, an engine selector sits at the top of the dialog so you can choose
-which one generates this spec. Kimi is excluded from this surface. Your choice
-is remembered per project; single-compatible-provider projects don't show the
-selector.
-
 **Context** — Quick mode usually runs as a single turn, because it doesn't need to read your codebase to write a spec from your description. But a context slider lets you give it more to work with:
 
 - At the lowest setting it just reads your description.

package/docs/guide/es/agents/2-profiles-and-the-balanced-default.md

@@ -35,14 +35,6 @@ La selección de perfil ocurre justo donde lanzas — en la **cabecera del rail*
 
 Ese es todo el flujo: elige un perfil, lanza, listo. Los rails concurrentes de un mismo lote pueden llevar cada uno su propio perfil, así que un arreglo rápido y una feature pesada pueden correr en paralelo con configuraciones distintas.
 
-## Cuando la sección Agentes está en silencio
-
-Los perfiles están separados por proveedor. Claude y Kimi admiten
-perfiles/roles; Codex y Gemini ejecutan los rails en modo legacy. En proyectos
-mixtos, nombres iguales no se cruzan entre Claude y Kimi. Kimi permite roles
-manuales, pero generación, smoke test y AI Refine de Agent Studio fallan
-antes de iniciar. Kimi requiere `specrails-core` 4.12.0 o posterior.
-
 ## A dónde ir después
 
 - [Personalizar los modelos por agente](customizing-models-per-agent) — crea perfiles `fast` y `max`.

package/docs/guide/es/agents/4-custom-agents-catalog.md

@@ -11,29 +11,14 @@ Cada entrada del catálogo muestra para qué sirve el agente y su modelo por def
 
 ## Añadir un agente personalizado
 
-Los roles son assets nativos del proveedor: Claude usa
-`.claude/agents/custom-<algo>.md`; Kimi usa
-`.kimi-code/skills/custom-<algo>/SKILL.md`.
-
-Una vez que el asset existe, aparece en el catálogo de ese provider y puedes añadir su id a un perfil del mismo provider. `custom-docs` corresponde a `.claude/agents/custom-docs.md` en Claude o a `.kimi-code/skills/custom-docs/SKILL.md` en Kimi; ambos quedan separados.
-
 Como viven en tu repo, los agentes personalizados son **activos de equipo commiteables**: commitea el archivo y todo tu equipo recibe el agente. Esto refleja la idea central de toda la sección Agentes —
 
 > **Las definiciones de los agentes son compartidas (viven en el repo y viajan con `git`). La configuración de modelos es por proyecto (vive en los perfiles).**
 
-Core protege ambos formatos. Kimi permite creación/edición manual y ejecución;
-Generate, Test y AI Refine fallan antes de iniciar Kimi.
-
 ## Poner a trabajar un agente personalizado
 
 El flujo típico:
 
-1. Crea el archivo Claude o el Skill Kimi nativo con instrucciones/modelo válidos.
-2. Confirma que aparece en **Agentes → Catálogo** bajo Personalizados.
-3. En **Agentes → Perfiles**, añade el agente a la cadena de un perfil (sobrescribiendo opcionalmente su modelo para ese perfil).
-4. Añade una regla de enrutado para que las tareas con las etiquetas adecuadas lleguen a él — o confía en el orden de la cadena.
-5. Lanza un rail con ese perfil desde la cabecera del rail.
-
 ## Vigilar cómo rinden los perfiles
 
 La sección Agentes también tiene una pestaña **Uso** — un desglose por perfil de cuántos jobs corrieron bajo cada perfil en una ventana seleccionada. Es una forma rápida de confirmar que tu reparto `fast`/`max` se está usando realmente como pretendías, y de detectar hacia qué perfil gravita tu equipo.

package/docs/guide/es/getting-started/1-what-is-specrails.md

@@ -35,8 +35,6 @@ specrails funciona con los principales CLI de programación con IA:
 
 - **Claude** (Claude Code)
 - **Codex** (Codex CLI)
-- **Gemini** (Gemini CLI)
-- **Kimi** (Kimi Code)
 
 Elige el que ya uses, o instala más de uno y escoge según la tarea. Un proyecto puede funcionar con un único provider o con varios a la vez, así que nunca te quedas atado a uno.
 

package/docs/guide/es/getting-started/2-installing-and-first-run.md

@@ -22,8 +22,6 @@ Lo único que specrails no puede incluir es el **CLI del provider de IA** en sí
 
 - **Claude Code**
 - **Codex CLI**
-- **Gemini CLI**
-- **Kimi Code**
 
 Instala el que tengas pensado usar, inicia sesión una vez desde tu terminal y listo. specrails detecta automáticamente qué providers están presentes.
 

package/docs/guide/es/getting-started/3-adding-your-first-project.md

@@ -20,10 +20,6 @@ Una etiqueta amigable que se muestra en la barra lateral. Si lo dejas en blanco,
 
 Ese es todo el formulario — haz clic en **Añadir** y listo.
 
-## Los proveedores de IA se detectan automáticamente
-
-Ya no eliges proveedores. Specrails detecta cada CLI de IA instalado en tu máquina — **Claude**, **Codex**, **Gemini**, **Kimi** — y todos los proyectos pueden usarlos todos, siempre. Si instalas un proveedor nuevo más adelante, aparece en todas partes por sí solo la próxima vez que vuelvas a la app; sin re-configuración, sin ajustes por proyecto. Si un proveedor está instalado pero sin sesión iniciada, su selector muestra una insignia sutil *Sin iniciar sesión*.
-
 ## La configuración ocurre en silencio
 
 No hay asistente de configuración. En el momento en que haces clic en **Añadir**, el proyecto queda registrado y aparece en tu barra lateral — puedes abrirlo de inmediato. En segundo plano, specrails ensambla el workspace del proyecto (unos segundos, totalmente offline): un pequeño punto parpadeante en la fila del proyecto indica que está trabajando, y desaparece cuando todo está listo. Si algo falla para un proveedor, el proyecto sigue funcionando con los demás — aparece un punto ámbar y, al hacer clic, se reintenta.

package/docs/guide/es/getting-started/4-the-dashboard-tour.md

@@ -26,14 +26,9 @@ La barra lateral derecha es tu cuadro de mandos para el proyecto actual. Pasa el
 
 - **Dashboard** — el tablero de specs y los rails (donde acabas de estar).
 - **Jobs** — todas las ejecuciones de pipeline de este proyecto, pasadas y presentes, con su estado, su duración y la posibilidad de profundizar en el detalle y los logs de cualquier ejecución.
-- **Analíticas** — invocaciones por día, actividad, modelo y ticket. Claude informa coste facturado, Codex/Gemini usan estimaciones y Kimi deja vacíos los tokens/costes USD no disponibles.
-- **Agentes** — perfiles y catálogos de roles separados por proveedor para Claude y Kimi. Con Kimi puedes crear y editar roles manualmente; Generate, Test y AI Refine no están disponibles.
-- **Código** — un explorador de archivos de solo lectura y chips que muestran qué archivos ha tocado la IA. Los resúmenes en lenguaje sencillo solo aparecen con proveedores compatibles; no están disponibles con Kimi.
 - **Integraciones** — complementos opcionales, como conectar tus specs a un tablero de **Jira** o habilitar herramientas adicionales para la IA.
 - **Ajustes** — opciones por proyecto (telemetría, presupuestos, configuración de providers y más).
 
-> Las secciones y acciones aparecen según las capacidades del proveedor efectivo. Por ejemplo, los perfiles funcionan con Claude y Kimi, pero las acciones de IA de Agent Studio fallan de forma cerrada con Kimi.
-
 ## La barra de estado
 
 Una fina franja recorre la parte inferior de la ventana. Es pequeña, pero útil:

package/docs/guide/es/integrations/1-ai-providers.md

@@ -1,84 +1,19 @@
-# Proveedores de IA (Claude, Codex, Gemini, Kimi)
+<!-- guide-revision: mission-first-v1 -->
 
-Specrails no está atado a una única IA. Claude, Codex, Gemini y Kimi son
-proveedores de primera clase; cada superficie muestra solo los motores cuyas
-capacidades cumplen su contrato.
+# Conecta un proveedor de IA
 
-## Los cuatro proveedores
+Specrails coordina tus CLI autenticadas de Claude o Codex. Su instalación, la cuenta y la facturación del modelo son independientes de la aplicación.
 
-| Proveedor | CLI | Creado por | Notas |
-|---|---|---|---|
-| **Claude** | `claude` | Anthropic | Coste nativo y transporte interactivo persistente. |
-| **Codex** | `codex` | OpenAI | Necesita codex `0.128.0+`. Lee sus servidores MCP desde tu `~/.codex/config.toml` global. |
-| **Gemini** | `gemini` | Google | Necesita gemini `0.11.0+`. Usa telemetría nativa y un archivo de instrucciones `GEMINI.md`. |
-| **Kimi Code** | `kimi` | Moonshot AI | Necesita Kimi `0.27.0+`. Desktop usa la CLI externa con `-p`; no instala ni inicia un servidor. |
+## Conecta y comprueba
 
-Los cuatro están **activados por defecto**. Un proveedor aparece en **Añadir
-proyecto** cuando su CLI está instalada y en tu `PATH`. Para Kimi, comprueba
-`kimi --version` y ejecuta `kimi login`.
+Instala la CLI siguiendo sus instrucciones oficiales y autentica la cuenta elegida. Revisa su disponibilidad en Specrails y selecciona un modelo compatible para la misión o el rail.
 
-## Los proveedores se detectan automáticamente
+Detectar la CLI no garantiza cuota ni conexión en la siguiente llamada. Resuelve los errores de autenticación y compatibilidad antes de reintentar una implementación.
 
-Nunca eliges proveedores por proyecto. Specrails detecta cada CLI de proveedor
-instalado en tu máquina y pone **todos** a disposición de **todos** los
-proyectos, siempre. Cada superficie comprueba después las capacidades que el
-proveedor anuncia. Consulta [Usar Kimi](../../../kimi.md) para la matriz exacta de Kimi.
+## Comprende los límites
 
-Si un proveedor que quieres no aparece por ningún sitio, casi siempre es porque
-el CLI no está instalado o no está en tu `PATH`. Instálalo, inicia sesión y
-vuelve a la app — la detección se re-ejecuta al enfocar la ventana y el
-proveedor aparece por sí solo en todas partes, con su superficie de workspace
-ensamblada en segundo plano. Un proveedor instalado pero sin sesión iniciada
-sigue apareciendo, con una insignia *Sin iniciar sesión* en los selectores de motor.
+Los registros del proyecto se guardan localmente, pero las llamadas al modelo e integraciones pueden enviar contexto fuera del equipo. Elige referencias y adjuntos teniendo esto presente.
 
-Algunas cosas útiles sobre máquinas multi-proveedor:
+Razonamiento, respuestas estructuradas, subagentes y guía durante un turno varían por proveedor. Consulta los [ajustes de ejecución](/docs/pipeline-picking-an-engine-per-rail) y [Guiar](/docs/missions-steering-and-receipts).
 
-- **Un solo proveedor se comporta exactamente como antes.** Si solo se detecta uno, nunca verás un selector de proveedor — la app se mantiene limpia y simple.
-- **Las capacidades gobiernan la barra lateral.** Una sección es visible cuando
-  al menos un proveedor detectado la soporta; dentro, las acciones por motor solo
-  ofrecen los proveedores capaces. Kimi anuncia perfiles, roles personalizados y
-  Freestyle; no anuncia acciones estructuradas que requieran un límite sin
-  herramientas exigible.
-- **Nada queda bloqueado.** Instalar o quitar un CLI de proveedor actualiza todos
-  los proyectos automáticamente — no hay ajuste de proveedor por proyecto que gestionar.
-
-## Elegir un proveedor por cada invocación
-
-La verdadera ventaja de un proyecto multiproveedor es poder elegir la IA adecuada para cada tarea, sin tocar ningún ajuste global. Allí donde se ejecuta una IA aparece un pequeño selector de proveedor (solo cuando el proyecto tiene más de uno):
-
-- **Añadir spec** — Explore permite Kimi; Quick Spec solo muestra proveedores
-  que pueden imponer su límite pure-output, por lo que Kimi no aparece ahí.
-- **Cabecera del rail** — elige el motor para ese rail concreto antes de lanzarlo.
-- **Terminal** — el botón «Open AI CLI» (el icono de chispas) abre un menú de proveedores para que puedas entrar en cualquier CLI instalada en el directorio de ese proyecto.
-
-Tu elección se recuerda por proyecto y toma el proveedor principal por defecto, así que no tienes que volver a elegirla cada vez.
-
-## Diferencias de capacidades
-
-Kimi admite Project/Agent Chat, Explore y propuestas, Quick Launcher
-(`/opsx:ff`), rails, Freestyle, loops sin Decider, perfiles/roles manuales,
-MCP, Serena, terminal y adjuntos.
-
-Kimi `-p` aprueba herramientas automáticamente y no puede imponer un límite
-sin herramientas/read-only. Por eso fallan antes de iniciar el proceso:
-Quick Spec, AI Edit, Contract Refine, SMASH/Re-SMASH, generación de
-blueprints/milestones de Project Builder, Loop Decider, resúmenes e historia
-de construcción, y automatización de Agent Studio. El auto-title usa un
-fallback determinista. Consulta la [guía completa de Kimi](../../../kimi.md).
-
-## Seguimiento de costes entre proveedores
-
-La página de **Analytics** registra las invocaciones que llegan a ejecutarse.
-Claude informa de su coste; Codex y Gemini usan una estimación. Kimi no emite
-tokens ni coste USD autoritativos, por lo que esos campos quedan vacíos.
-
-## Resolución de problemas
-
-- **No aparece un proveedor que instalé.** Confirma que la CLI está en tu `PATH` (prueba `claude --version` / `codex --version` / `gemini --version` / `kimi --version` en un terminal nuevo).
-- **Los servidores MCP de Codex no se cargan en el chat.** Codex lee los servidores MCP desde tu `~/.codex/config.toml` global; regístralos ahí con `codex mcp add`.
-- **Desactivación de emergencia.** Un proveedor se puede desactivar en toda la app mediante una variable de entorno (`SPECRAILS_CODEX_BETA=0` o `SPECRAILS_GEMINI_BETA=0`). Esto solo oculta el proveedor de la *selección*; rara vez es necesario.
-
-## Véase también
-
-Las guías dedicadas a cada proveedor profundizan en cada CLI: consulta
-[Kimi](../../../kimi.md), Codex y Gemini.
+La selección Sonnet ejecuta Claude Sonnet 5.5 (`claude-sonnet-5-5`). [Anthropic](https://platform.claude.com/docs/en/models/sonnet-5-5/overview).

package/docs/guide/es/integrations/2-plugins.md

@@ -34,11 +34,3 @@ Por debajo, la instalación es *quirúrgica y aditiva*: solo añade sus entradas
 - **Rails.** Antes de que un rail se ejecute, Specrails comprueba qué plugins están instalados y saludables, y pone esas herramientas a disposición del agente para ese trabajo. Un plugin degradado simplemente se omite para esa ejecución: el rail se lanza igualmente con normalidad. Cada trabajo registra una instantánea de qué plugins estaban activos, que puedes ver en la exportación de diagnóstico del trabajo.
 - **Chat.** El chat recoge automáticamente la configuración MCP de tu proyecto, así que los plugins instalados también están disponibles ahí.
 - **Configuración.** Los plugins se ignoran mientras un proyecto todavía se está configurando; entran en juego una vez que el proyecto está listo.
-
-## Notas sobre proveedores
-
-Los plugins son conscientes del proveedor. Serena admite Claude mediante `.mcp.json`, Codex mediante `codex mcp add` con un `CODEX_HOME` aislado por proyecto y Kimi mediante `.kimi-code/mcp.json`. Solo aparece si su manifiesto declara el provider; por eso Serena no se ofrece para Gemini. La tarjeta de Jira es independiente del proveedor y se muestra para todos.
-
-## Archivos reservados
-
-Los plugins gestionan la configuración MCP nativa del provider, estado bajo `.specrails/plugins/` y, solo cuando corresponde a Claude, fragmentos en `.claude/agents/custom-<plugin>.md`. Las entradas Kimi viven en `.kimi-code/mcp.json`; la app no escribe fragmentos exclusivos de Claude para Kimi ni sobrescribe configuraciones a ciegas.