specrails-desktop 2.30.2 → 2.31.0

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

@@ -1,20 +1,31 @@
-# AI providers (Claude, Codex, Gemini)
+# AI providers (Claude, Codex, Gemini, Kimi)
 
-Specrails isn't tied to a single AI. Every part of the app that talks to an AI — Explore Spec, Quick spec, rails, chat, AI Edit, the terminal's "Open AI CLI" button — can run through any of three first-class providers. You pick which ones a project uses, and you can even switch on a per-task basis.
+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.
 
-## The three providers
+## The four providers
 
 | Provider | CLI | Made by | Notes |
 |---|---|---|---|
-| **Claude** | `claude` | Anthropic | The most fully featured. The only provider for Agents (profiles) and Freestyle rails, and for Contract Refine. |
+| **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. |
 
-All three are **enabled by default**. A provider shows up in **Add Project** whenever its CLI is installed and on your `PATH`. So the first step is always the same: install the CLI you want and log in with it, exactly as that tool's own docs describe. Once `claude --version` (or `codex`, or `gemini`) works in your terminal, Specrails can use it.
+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.
 
 ## Installing one provider for a project
 
-When you add a project, the setup wizard asks which provider(s) to install. Pick one, click through the install step, and you're done. From there on the project just *has* that provider — you never have to think about it again. Specs, rails, chat, and analytics all work the same regardless of which one you chose.
+When you add a project, the setup wizard asks which provider(s) to install.
+Pick one, click through the install step, and you're done. From there on the
+project has that provider, while each surface checks its advertised
+capabilities. See [Using Kimi](../../../kimi.md) for Kimi's exact matrix.
 
 If a CLI you want isn't offered in Add Project, it's almost always because the CLI isn't installed or isn't on your `PATH`. Install it, then reopen Add Project.
 
@@ -25,40 +36,70 @@ You can install **more than one** provider into the same project — for example
 A few things worth knowing about multi-provider projects:
 
 - **One provider behaves exactly like before.** If a project has just a single provider, you'll never see a provider picker anywhere — the app stays clean and simple.
-- **The right sidebar only shows sections every installed provider supports.** Because Agents (profiles) is a Claude-only concept, the **Agents** section disappears the moment a project includes any non-Claude provider. Everything else (Specs, Code, Analytics, Integrations, Terminal, Chat) stays.
+- **Capability checks drive the sidebar.** Sections are visible only when their
+  backing behavior is supported by the relevant installed providers. Kimi
+  advertises profiles, custom roles, and Freestyle; it does not advertise
+  structured actions that require an enforceable no-tools boundary.
 - **Provider choice is locked after creation.** In this version you choose your providers when you add the project and they can't be changed later from Settings. If you need a different mix, that's a fresh project.
 
 ## 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 or Quick-generate a spec with whichever provider you like.
-- **Rail header** — pick the engine for that specific rail before launching it.
+- **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.
 
-## What only Claude can do
-
-A handful of features are Claude-specific by nature, so they're either hidden or skipped when another provider is in play:
-
-- **Agents (profiles)** — the per-project agent catalog and model routing. Hidden on any project that includes a non-Claude provider.
-- **Freestyle rails** — always run on Claude.
-- **Contract Refine** — the extra "Contract Layer" pass on a committed spec runs only when the conversation's provider is Claude.
-- **Add Spec advanced modes** (SMASH / Contract Layer) — hidden for non-Claude engines.
-
-Everything else — Explore, Quick spec, the full rails pipeline, AI Edit, chat, cost analytics — works across all three.
+## 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 billable invocation regardless of provider. On multi-provider projects it adds engine filter chips so you can compare spend by provider. Claude reports its own exact cost; for Codex and Gemini, Specrails estimates cost from a built-in rate card, so the numbers are close approximations rather than billed amounts.
+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` (try `claude --version` / `codex --version` / `gemini --version` in a fresh terminal). The app probes provider CLIs through your system `PATH`.
+- **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 provider guides go deeper on each CLI: the Codex guide and the Gemini guide each cover setup, what works, and provider-specific quirks.
+The dedicated [Kimi provider guide](../../../kimi.md), Codex guide, and Gemini
+guide cover setup and provider-specific behavior in depth.

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

@@ -21,7 +21,7 @@ The headline plugin is:
 3. Click into the plugin to **preview the install** — this shows you exactly what files will change before anything happens.
 4. Click **Install**. You'll see live progress as it sets up.
 
-Under the hood the install is *surgical and additive*: it only adds its own entries to your project's `.mcp.json` (and, for some plugins, a fragment file in the protected `.claude/agents/` namespace). It never rewrites your config wholesale, and adding a second plugin can never disturb the first. If the install can't verify itself as healthy, it rolls back cleanly.
+Under the hood the install is *surgical and additive*: it only adds its own entries to the selected provider's native MCP config (and, for some Claude installs, a fragment in the protected `.claude/agents/` namespace). It never rewrites your config wholesale, and adding a second plugin can never disturb the first. If the install can't verify itself as healthy, it rolls back cleanly.
 
 ## Managing installed plugins
 
@@ -37,8 +37,8 @@ Under the hood the install is *surgical and additive*: it only adds its own entr
 
 ## Provider notes
 
-Plugins are provider-aware. Serena and similar MCP plugins resolve for providers that register MCP through the project's `.mcp.json` (Claude and Gemini). For Codex projects, MCP servers are managed through Codex's own global config instead, so plugin entries in **Integrations** are filtered accordingly. The Jira card in Integrations is provider-agnostic and shows for everyone — see the Jira guide.
+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 in your project: your `.mcp.json` (merged surgically), some state under `.specrails/plugins/`, and per-plugin agent fragments at `.claude/agents/custom-<plugin>.md`. These are committable team assets if you want to share an integration with your teammates — the app never blindly overwrites them.
+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/6-agent-chat.md

@@ -22,7 +22,11 @@ Picking a project here **does not** move your dashboard — the agent's target a
 
 ## Provider and model
 
-Just above the message box you choose the **provider** (Claude, Codex or Gemini) and its **model**. Each provider has its own model list, and switching provider starts a fresh session with that provider's default model — so you can, say, drive the app with Claude and switch to Codex for another conversation without anything getting crossed.
+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
 
@@ -37,6 +41,14 @@ 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:
@@ -53,7 +65,7 @@ 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 your yes it creates the spec and — by default — enriches it in the background with a **Contract Layer** (exact file paths, data shapes, invariants) so the implementing agents don’t improvise. Say "no contract layer" to skip the enrichment.
+- **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/pipeline/1-rails-and-jobs.md

@@ -35,8 +35,8 @@ 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` / `Batch` / `Freestyle`) or a custom loop. See the table below. Persisted per rail. |
-| **Profile picker** | Which agent profile runs (Claude rails only). Only appears once the project has at least one profile. |
-| **Engine selector** | Which installed provider runs this rail — Claude, Codex, or Gemini. 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 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). |
 | **▶ Play / ■ Stop** | Start or cancel. |
 
 ### What a rail runs: Loops
@@ -47,11 +47,19 @@ A rail runs a **Loop** — the recipe for the work. Three loops are **built in**
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | One job covering all specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. The everyday default. |
 | **Batch** | `/specrails:batch-implement` | One job that works through the rail's specs sequentially, in dependency-aware waves. Best for several related specs. |
-| **Freestyle** | Freestyle | Claude implements each spec autonomously, **bypassing** the pipeline. One independent job per spec. Claude only. |
+| **Freestyle** | Freestyle | A capable provider implements each spec autonomously, **bypassing** the pipeline. One independent job per spec. Claude and Kimi support it. |
 
-Freestyle is the odd one out: it skips the agent chain and hands Claude the raw spec to work on with its native tools. It's open-ended, so pressing Play opens a confirmation first, and a per-rail model picker lets you choose Haiku / Sonnet / Opus. It only appears when the rail's engine is Claude. A Freestyle run is also the one job that **stays open for you**: chat with it from the Job Detail composer and click **Finalize** when you're satisfied (every other job wraps up on its own).
+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.
 
-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. Those custom loops appear in the same Loop picker. That's the next big idea: [The Loop Builder](the-loop-builder).
+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
 
@@ -81,7 +89,11 @@ Click **■ Stop** on the rail header. The app sends `SIGTERM` to the subprocess
 
 ## 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)) and launch again. Missing Claude or Codex gives a precise "*<provider> CLI not found*" message; missing Gemini surfaces a generic launch error today, but the outcome is the same.
+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
 
@@ -96,4 +108,4 @@ 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.
 - [Batch implement & multi-feature](batch-implement-and-multi-feature) — run several specs at once.
-- [Picking an engine per rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.
+- [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,7 +94,9 @@ 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.
-- **Claude only, for now.** Codex and Gemini jobs run one-shot exactly as before — no composer appears. (Server operators can turn the whole feature off with `SPECRAILS_INTERACTIVE_JOBS=false`.)
+- **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/3-batch-implement-and-multi-feature.md

@@ -83,4 +83,4 @@ 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) — note that Batch runs on any provider; Freestyle is Claude-only.
+- [Picking an engine per rail](picking-an-engine-per-rail) — Batch runs on any provider; Freestyle is available on Claude and Kimi.

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

@@ -1,6 +1,9 @@
 # Picking an engine per rail
 
-Specrails desktop treats **Claude Code**, **Codex CLI**, and **Gemini CLI** as first-class engines. A project can have one, two, or all three installed — and when more than one is present, you choose which engine runs each rail. This page covers the per-rail engine selector and when to reach for each.
+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.
 
 ## When the selector appears
 
@@ -13,30 +16,38 @@ When it does appear, your choice is **per rail and per launch** — different ra
 ## How to pick an engine
 
 1. Make sure the rail's engine selector is showing (project has 2+ providers).
-2. Click it and choose **Claude**, **Codex**, or **Gemini**.
+2. Click it and choose **Claude**, **Codex**, **Gemini**, or **Kimi**.
 3. Launch the rail with **▶ Play**.
 
 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.
 
 ## What each engine is good at
 
-All three run the standard **Implement** and **Batch** pipelines. Here's a practical guide to choosing:
+All four run the standard **Implement** and **Batch** pipelines. Here's a practical guide to choosing:
 
 | Engine | Reach for it when… | Notes |
 |--------|--------------------|-------|
-| **Claude** | You want the full feature set: agent profiles, Freestyle, native cost reporting, the richest tool support. The default for most work. | The only engine that supports **agent profiles**, **Freestyle**, and a few Claude-only spec features (Contract Layer, SMASH). |
+| **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, Batch, 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. |
 
-### The Claude-only features
+### Capability differences
 
-A few things only work on Claude rails — pick Claude if you need them:
+A few things need a provider with the matching capability:
 
-- **Agent profiles** — per-agent model routing. On Codex or Gemini rails the run always uses legacy mode and any selected profile is **ignored**. The profile picker is hidden for non-Claude engines.
-- **Freestyle** — the autonomous, pipeline-bypassing mode. The `Freestyle` segment and its Haiku/Sonnet/Opus model picker only appear when the rail's engine is Claude.
-- **Contract Layer & SMASH** — Claude-only spec-refinement features (these are Add-Spec options, not rail options, but the same constraint applies).
+- **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.
 
-If a project mixes engines, the right sidebar only shows sections **every** installed provider supports — so the **Agents** section disappears entirely on a project that includes any non-Claude provider, because profiles are Claude-specific.
+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
 
@@ -49,12 +60,15 @@ Multi-provider projects shine when you want to **compare** or **cost-tune**:
 ## 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.
-- **Cost is always tracked**, even for engines without native cost reporting — the app falls back to a rate card so Codex and Gemini runs still show up in [analytics](../analytics/tracking-cost).
+- **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.

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

@@ -17,7 +17,7 @@ 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 reasoning effort — *not* the loop's steps. The same loop runs on Claude, Codex or Gemini depending on the rail.
+- 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.
 
@@ -41,6 +41,11 @@ 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:
@@ -57,7 +62,7 @@ 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. Leave it empty for no cap. |
+| **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,6 +2,11 @@
 
 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:
@@ -19,7 +24,11 @@ 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 AI provider installed (any mix of Claude, Codex, and Gemini), an engine selector sits at the top of the dialog so you can choose which one generates this spec. Your choice is remembered per project. Single-provider projects don't show this — there's nothing to choose between.
+**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:
 

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

@@ -37,7 +37,11 @@ Ese es todo el flujo: elige un perfil, lanza, listo. Los rails concurrentes de u
 
 ## Cuando la sección Agentes está en silencio
 
-Los perfiles son una capacidad de Claude. En un proyecto que incluye un proveedor que no es Claude (Codex o Gemini), la sección Agentes se oculta y los rails corren sin perfiles — eso es lo esperado, no un fallo. Los perfiles también requieren un `specrails-core` lo bastante reciente en el proyecto; si es más antiguo, verás un banner amarillo. Los perfiles que crees igualmente se **guardan** — simplemente no afectan al pipeline hasta que se actualice core. Actualiza con el comando que muestra el banner para desbloquearlos.
+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
 

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

@@ -11,21 +11,24 @@ Cada entrada del catálogo muestra para qué sirve el agente y su modelo por def
 
 ## Añadir un agente personalizado
 
-Los agentes personalizados son simples archivos Markdown dentro de tu repositorio, en `.claude/agents/`, con el nombre `custom-<algo>.md`. El archivo contiene las instrucciones del agente (su system prompt) y una pequeña cabecera de frontmatter que incluye un `model:` por defecto.
+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 archivo existe en el proyecto, aparece en el catálogo como agente personalizado, y puedes añadir su id a la cadena de agentes de cualquier perfil (y enrutar tareas hacia él). El id debe coincidir con el nombre del archivo — una entrada para `custom-docs` se corresponde con `.claude/agents/custom-docs.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).**
 
-El espacio de nombres `custom-*` está reservado y protegido: los comandos `init` y `update` de `specrails-core` nunca tocan `.claude/agents/custom-*.md`, así que tus agentes personalizados sobreviven intactos a las actualizaciones de core. (La misma protección cubre los fragmentos aportados por plugins, como `custom-serena.md`.)
+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. Escribe `.claude/agents/custom-<nombre>.md` con instrucciones y un modelo por defecto.
+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.

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

@@ -36,6 +36,7 @@ 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

@@ -23,6 +23,7 @@ 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/4-the-dashboard-tour.md

@@ -26,13 +26,13 @@ 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** — cuánto te está costando tu uso de IA. El gasto desglosado por día, por actividad, por modelo y por ticket, para que no haya sorpresas.
-- **Agentes** — los perfiles de agente de tu proyecto: qué agentes se ejecutan en el pipeline y qué modelos de IA usan. *(Solo en proyectos basados en Claude.)*
-- **Código** — un explorador de archivos de solo lectura con resúmenes de IA en lenguaje sencillo, y chips que muestran qué archivos ha tocado la IA. Ideal para quienes no programan pero quieren seguir el proceso.
+- **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).
 
-> Algunas secciones solo aparecen cuando tienen sentido para los providers que elegiste; por ejemplo, **Agentes** es específica de Claude. Si no ves una sección, simplemente es que no aplica a la configuración de este proyecto.
+> 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
 

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

@@ -1,16 +1,21 @@
-# Proveedores de IA (Claude, Codex, Gemini)
+# Proveedores de IA (Claude, Codex, Gemini, Kimi)
 
-Specrails no está atado a una única IA. Cada parte de la app que habla con una IA —Explore Spec, la spec rápida (Quick), los rails, el chat, AI Edit, el botón «Open AI CLI» del terminal— puede funcionar con cualquiera de los tres proveedores de primera clase. Tú eliges cuáles usa un proyecto, e incluso puedes cambiar de proveedor según la tarea.
+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.
 
-## Los tres proveedores
+## Los cuatro proveedores
 
 | Proveedor | CLI | Creado por | Notas |
 |---|---|---|---|
-| **Claude** | `claude` | Anthropic | El más completo. El único proveedor para Agents (perfiles) y los rails Freestyle, y para Contract Refine. |
+| **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. |
 
-Los tres están **activados por defecto**. Un proveedor aparece en **Añadir proyecto** siempre que su CLI esté instalado y en tu `PATH`. Así que el primer paso es siempre el mismo: instala la CLI que quieras y haz login con ella, exactamente como indica la documentación de esa herramienta. En cuanto `claude --version` (o `codex`, o `gemini`) funcione en tu terminal, Specrails podrá usarlo.
+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`.
 
 ## Instalar un proveedor para un proyecto
 
@@ -25,40 +30,47 @@ Puedes instalar **más de un** proveedor en el mismo proyecto; por ejemplo, Clau
 Algunas cosas que conviene saber sobre los proyectos multiproveedor:
 
 - **Con un solo proveedor todo se comporta exactamente igual que antes.** Si un proyecto tiene un único proveedor, no verás ningún selector de proveedor en ninguna parte: la app se mantiene limpia y sencilla.
-- **La barra lateral derecha solo muestra las secciones que admiten todos los proveedores instalados.** Como Agents (perfiles) es un concepto exclusivo de Claude, la sección **Agents** desaparece en cuanto un proyecto incluye algún proveedor que no sea Claude. Todo lo demás (Specs, Code, Analytics, Integraciones, Terminal, Chat) se mantiene.
+- **Las capacidades gobiernan la interfaz.** Claude y Kimi admiten perfiles
+  separados por proveedor; Codex y Gemini ejecutan los rails en modo legacy.
 - **La elección de proveedor queda bloqueada tras la creación.** En esta versión eliges tus proveedores al añadir el proyecto y no se pueden cambiar después desde Ajustes. Si necesitas una combinación distinta, crea un proyecto nuevo.
 
 ## 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** — un selector de motor te deja explorar o generar una spec en modo rápido (Quick) con el proveedor que prefieras.
+- **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.
 
-## Lo que solo Claude puede hacer
+## Diferencias de capacidades
 
-Un puñado de funciones son específicas de Claude por naturaleza, así que se ocultan o se omiten cuando hay otro proveedor en juego:
+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.
 
-- **Agents (perfiles)** — el catálogo de agentes por proyecto y el enrutado de modelos. Se oculta en cualquier proyecto que incluya un proveedor que no sea Claude.
-- **Rails Freestyle** — siempre se ejecutan con Claude.
-- **Contract Refine** — la pasada adicional de «Contract Layer» sobre una spec confirmada solo se ejecuta cuando el proveedor de la conversación es Claude.
-- **Modos avanzados de Añadir spec** (SMASH / Contract Layer) — se ocultan para los motores que no sean Claude.
-
-Todo lo demás —Explore, la spec rápida (Quick), el pipeline completo de rails, AI Edit, el chat y las analíticas de coste— funciona con los tres.
+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 cada invocación facturable independientemente del proveedor. En los proyectos multiproveedor añade chips de filtro por motor para que puedas comparar el gasto por proveedor. Claude informa de su coste exacto; para Codex y Gemini, Specrails estima el coste a partir de una tarifa interna, así que las cifras son aproximaciones cercanas y no importes facturados.
+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` en un terminal nuevo). La app detecta las CLI de los proveedores a través del `PATH` de tu sistema.
+- **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: la guía de Codex y la guía de Gemini cubren la configuración, lo que funciona y las peculiaridades de cada proveedor.
+Las guías dedicadas a cada proveedor profundizan en cada CLI: consulta
+[Kimi](../../../kimi.md), Codex y Gemini.