specrails-desktop 2.30.2 → 2.31.0

package/docs/codex.md

@@ -1,20 +1,20 @@
 # Using Specrails with the Codex CLI
 
-Specrails supports **three AI providers** — Claude, Codex, and Gemini —
-and they are interchangeable. This guide covers OpenAI's
+Specrails supports **four AI providers** — Claude, Codex, Gemini, and Kimi.
+This guide covers OpenAI's
 [Codex CLI](https://developers.openai.com/codex). For the others, see
 [Claude Code](https://claude.com/claude-code) and the
-[Gemini guide](gemini.md).
+[Gemini guide](gemini.md) or [Kimi guide](kimi.md).
 
 > **Just want to get going?** Install the `codex` CLI, log in, then in
 > the app click **Add Project → check Codex → Submit**. The rest of the
 > app (specs, rails, chat, analytics) works the same as it does for
 > Claude. Everything below is detail for when you need it.
 
-You pick one, two, or all three providers when you add a project — and
+You pick any subset of the four providers when you add a project — and
 you can mix them in a single project too (see [Running more than one
 provider in one project](#running-more-than-one-provider-in-one-project)
-below). All three are enabled by default.
+below). All four are registered by default.
 
 > The codex path is enabled by default. To temporarily disable it
 > (e.g. as an emergency rollback), set `SPECRAILS_CODEX_BETA=0` in the
@@ -41,15 +41,15 @@ binary isn't on `PATH`; it shows install commands if you click "More info".
 1. Open the app UI and click **Add Project**.
 2. Pick the project's path.
 3. In the **AI providers** row, check **Codex** (you can check
-   **Claude** and/or **Gemini** too — see [Running more than one
+   **Claude**, **Gemini**, and/or **Kimi** too — see [Running more than one
    provider in one project](#running-more-than-one-provider-in-one-project)).
    The first provider you select becomes the project default.
 4. Submit. The app writes `.specrails/install-config.yaml` (with
    `provider: codex` and `tier: quick` as YAML keys) and spawns
-   `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <file>`
+   `npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <file>`
    — the provider and tier live in the YAML, not as CLI flags. (The app
-   pins `specrails-core@^4.8.0`; that floor is the version that ships the
-   per-provider targets, including the Codex skill set.) The install
+   pins `specrails-core@^4.12.0`; that floor is the version that ships the
+   current provider targets, including Kimi and the Codex skill set.) The install
    produces:
    - `.codex/config.toml` — model, reasoning effort, sandbox mode, and
      approval policy (all top-level keys per the codex 0.128.0+ schema).
@@ -72,8 +72,8 @@ the choice later.
 
 ## Running more than one provider in one project
 
-A single project can install **any combination** of Claude, Codex, and
-Gemini. In the **Add Project** dialog the **AI providers** control is a
+A single project can install **any combination** of Claude, Codex, Gemini, and
+Kimi. In the **Add Project** dialog the **AI providers** control is a
 multi-select — check the ones you want and the app runs each provider's
 install sequentially. The first provider you select is the
 **primary/default**; the helper text spells this out: *"The engines will
@@ -90,43 +90,38 @@ Once more than one is installed:
   to choose.
 - The **selected engine is remembered per project** (it defaults to the
   primary), so you don't have to re-pick on every spawn.
-- **Capability intersection.** The right sidebar only shows sections
-  that *every* installed provider supports. Because Codex has no agent
-  profiles, the **Agents** section is **hidden** whenever a non-Claude
-  provider is installed. The **Integrations** section stays **visible** —
-  it hosts the provider-agnostic Jira card. What gets filtered there is
-  the **Serena plugin** entry, which needs a Claude-style project MCP
-  registration (so it shows for Claude and Gemini, but not for Codex).
-  See [Plugins and MCP on codex projects](#plugins-and-mcp-on-codex-projects).
-  Single-provider projects are unaffected.
+- **Provider-scoped capabilities.** Claude and Kimi expose independent
+  profile catalogs; Codex and Gemini run rails in legacy/no-profile mode.
+  Integration entries and health are resolved for the effective provider:
+  Serena supports Claude, Codex, and Kimi through each provider's native MCP
+  registration, while Jira is provider-agnostic.
 
 When only one provider is installed the app behaves byte-identically to
 a single-provider project — no engine pickers, no provider persisted on
 spawns, no overrides.
 
-## What's different vs Claude (and Gemini)
-
-The table below puts Codex side by side with Claude, plus a Gemini column
-so you can see where each provider lands. (For the full Gemini picture see
-the [Gemini guide](gemini.md).)
-
-| Surface | Claude | Codex | Gemini |
-|---|---|---|---|
-| **CLI** | `claude` | `codex` | `gemini` |
-| **Min CLI version** | none pinned | `0.128.0` | `0.11.0` |
-| **Project dir** | `.claude/` | `.codex/` | `.gemini/` |
-| **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` |
-| **Default model** | `sonnet` | `gpt-5.5` (catalog includes the GPT-5.6 family: `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`) | `gemini-3.5-flash` |
-| **Reasoning efforts** | `low`–`xhigh` | `minimal`–`ultra` (`xhigh`/`max`/`ultra` ship with GPT-5.6; `ultra` is Sol-only upstream) | none |
-| **Agent format** | `.claude/agents/<id>.md` with `model:` frontmatter | `.codex/skills/<id>/SKILL.md` Skill format | `.gemini/` command + agent target |
-| **Agent profiles** | Full support (rail `RailProfileSelector`) | **None** — rails force the profile to `null` | **None** — rails force the profile to `null` |
-| **Pipeline rails** | ✅ all rail types | ✅ (except Freestyle) | ✅ (except Freestyle) |
-| **Freestyle rails** (mode `freestyle`) | ✅ Claude-only | ❌ rejected (`Freestyle requires the Claude provider`) | ❌ rejected |
-| **Contract Refine** | Claude-only (it `--resume`s the Explore session and runs `/specrails:contract-refine`) | **Skipped** — toggling "Enrich with Contract Layer" is a no-op | **Skipped** |
-| **MCP registration** | Surgical merge of `<project>/.mcp.json` | `codex mcp add` against per-project `CODEX_HOME=~/.specrails/projects/<slug>/codex-home/` (isolated) | Project `.mcp.json` (so Serena-style plugins **do** resolve) |
-| **Session resume** | `--resume <session_id>` | `exec resume <thread_id>` | `--resume` |
-| **Native cost report** | `result.total_cost_usd` from `--output-format stream-json` | None — cost is **estimated** by the app from `turn.completed.usage` and the local pricing table at `server/pricing.ts` | None — **estimated** the same way as Codex |
-| **Telemetry** | `OTEL_EXPORTER_OTLP_*` env vars consumed by claude itself | **Synthesised** by the app from `codex exec --json` events and POSTed to the same in-process OTLP receiver | **Native** OTLP — Gemini honours the same `OTEL_*` env vars Claude does (no synthetic bridge) |
+## What's different across providers
+
+The table below includes all four registered providers. See the
+[Kimi guide](kimi.md) for its full safety matrix.
+
+| Surface | Claude | Codex | Gemini | Kimi |
+|---|---|---|---|---|
+| **CLI** | `claude` | `codex` | `gemini` | `kimi` |
+| **Min CLI version** | none pinned | `0.128.0` | `0.11.0` | `0.27.0` |
+| **Project dir** | `.claude/` | `.codex/` | `.gemini/` | `.kimi-code/` |
+| **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` | `AGENTS.md` |
+| **Default model** | `sonnet` | `gpt-5.5` | `gemini-3.5-flash` | `k3` |
+| **Reasoning efforts** | `low`–`xhigh` | model-dependent | none | `low`/`high`/`max`, K3 only |
+| **Agent format** | `.claude/agents/<id>.md` | `.codex/skills/<id>/SKILL.md` | `.gemini/` target | `.kimi-code/skills/<id>/SKILL.md` |
+| **Agent profiles** | ✅ | legacy | legacy | ✅ provider-scoped |
+| **Implement / Batch** | ✅ | ✅ | ✅ | ✅ |
+| **Freestyle** | ✅ | ❌ | ❌ | ✅ |
+| **Pure-output transforms** | capability-dependent | capability-dependent | capability-dependent | ❌ fail closed |
+| **MCP registration** | `.mcp.json` | isolated `CODEX_HOME` | `.gemini/settings.json` | `.kimi-code/mcp.json` |
+| **Session resume** | `--resume` | `exec resume` | `--resume` | bound `--session=<id>` after resume hint |
+| **Native cost report** | exact | estimated | estimated | unavailable |
+| **Telemetry** | native | synthesized | native | unavailable |
 
 A few Codex-specific behaviours worth calling out:
 
@@ -135,9 +130,9 @@ A few Codex-specific behaviours worth calling out:
   a rail can read and write anywhere in the project. This is intentional —
   rails need to apply edits across the repo — but it's worth knowing if
   you're surprised by a rail touching files outside the working tree.
-- **Freestyle rails are Claude-only.** Launching a Freestyle rail (mode
-  `freestyle`) on a Codex (or Gemini) engine is rejected with a 400
-  (`Freestyle requires the Claude provider`). Pick Claude for that rail.
+- **Freestyle rails require a capable provider.** Launching a Freestyle rail
+  (`mode: freestyle`) on Codex or Gemini is rejected before spawn. Pick Claude
+  or Kimi for that autonomous rail mode.
 
 ## Estimated cost
 
@@ -166,24 +161,16 @@ ship an out-of-band update to `server/pricing.ts`.
 
 ## Plugins and MCP on codex projects
 
-The **Integrations** section stays **visible** on codex projects — it hosts
-the provider-agnostic **Jira** integration, which works for any provider.
-What's filtered out is the **Serena plugin**: it requires a project-level
-`.mcp.json` registration that Codex doesn't use (Codex registers MCP servers
-via `codex mcp add`, Claude and Gemini use the project `.mcp.json`). So a
-codex-only project still has the Integrations tab and the Jira card, but no
-Serena plugin entry.
-
-> Why: the right sidebar shows the capability intersection (sections every
-> installed provider supports). Only **Agents** is Claude-only; **Integrations**
-> is not. The per-provider filter lives inside the Integrations page
-> (`client/src/pages/IntegrationsPage.tsx`, `showPlugins` requires a
-> Claude-style provider), not in the section-level intersection
-> (`provider-capabilities.ts`).
-
-To give a codex project MCP servers, register them with `codex mcp add` from your
-terminal: codex chat / Explore turns spawn with your own environment and read your global
-`~/.codex/config.toml`, so those servers are available natively — no extra plumbing required.
+The **Integrations** section stays visible on Codex projects. Serena is
+provider-aware and registers its server with `codex mcp add` in Specrails'
+isolated per-project `CODEX_HOME`; Claude uses `.mcp.json`, and Kimi uses
+`.kimi-code/mcp.json`. Install state and health are scoped to the selected
+provider, so one provider's entry never masquerades as another's. Jira remains
+provider-agnostic.
+
+For MCP servers outside the managed plugin catalog, use Codex's native
+configuration flow. Codex chat and Explore turns inherit the appropriate Codex
+environment and read that MCP configuration.
 
 ## Troubleshooting
 

package/docs/creating-specs.md

@@ -2,7 +2,12 @@
 
 A **spec** in specrails-desktop is a description of work you want done — what the AI agents will read and act on. This guide walks through every way you can create, refine, compare, and organise them.
 
-Specs are engine-agnostic: depending on how the project was set up, they can be generated by **Claude, Codex, or Gemini** — whichever providers you installed for the project. The flows below are identical no matter which one you use; only the engine picker and the default model differ.
+Specs are engine-agnostic: depending on how the project was set up, they can
+be shaped by **Claude, Codex, Gemini, or Kimi**. Engine selectors show only
+providers that advertise the surface's required capability. Kimi is available
+for agentic Explore/proposal work, but its `-p` mode cannot enforce the
+no-tools/read-only boundary required by Quick Spec and the structured
+transforms listed below.
 
 ## Creating a spec
 
@@ -12,12 +17,20 @@ Open the Dashboard and click **Add** (the Plus button on the SpecsBoard toolbar)
 - **Explore** — you converse with the AI and shape the spec turn by turn.
 - **Raw** — your prompt is saved verbatim as a spec, with **no AI** involved.
 
-If the project has **more than one provider installed** — any combination of Claude, Codex, and Gemini — an **AI engine** selector sits at the top of the dialog so you can pick which engine generates this spec. The choice is remembered per project. Projects with a single provider don't show the selector; it would have nothing to choose between.
+If the project has **more than one compatible provider installed**, an **AI
+engine** selector sits at the top of the dialog. The choice is remembered per
+project. Projects with a single compatible provider don't show the selector;
+Kimi is not offered for Quick Spec even when it is installed.
 
 ### Quick mode
 
 For when you already know what you want. Type your idea; the AI generates the full spec. This is usually a single turn — but it runs multi-turn when you give it the full codebase (the context slider's higher presets) or attach files, so it can read what it needs first.
 
+> **Kimi:** Quick Spec is unavailable. The server rejects a direct Kimi
+> request before spawning because this form is a pure-output action. This is
+> separate from the agentic **Quick Launcher**, where commands such as
+> `/opsx:ff` can run with Kimi. Use Explore, Raw, or that launcher instead.
+
 **Controls:**
 
 - **Engine + model** — the engine selector (multi-provider only) and a model picker. The model defaults to a sensible choice for the engine and can be overridden per spec.
@@ -36,6 +49,11 @@ For when you already know what you want. Type your idea; the AI generates the fu
 
 Your last choice for this toggle is remembered per project.
 
+Contract Layer enrichment requires a provider that can enforce the structured
+action's safe tool policy. It is hidden for Kimi because Kimi 0.27 prompt mode
+auto-approves tools and has no per-spawn no-tools boundary. A direct request
+fails before spawn.
+
 While the spec is being generated, a toast in the corner shows the project name, a truncated copy of your idea, and the **elapsed time** ("Generating… 0:12"). When it finishes it switches to "Generated in <time>" with a **View** action that jumps straight to the new spec.
 
 ### Explore mode
@@ -55,11 +73,15 @@ For when the spec needs shaping. You converse with the AI; a live draft updates
 
 Rich and Max both load the full codebase — they differ only in whether the Contract Layer pass runs. The decision is per-conversation (saved on `chat_conversations.context_scope`) so it doesn't bleed into other Explore sessions.
 
+Kimi supports the agentic Explore conversation and proposal flow. It does not
+offer the Max Contract Layer pass. Its prompt mode may use tools
+autonomously—Explore is not a read-only sandbox.
+
 The **Desktop** preset is Explore-only — Quick mode caps the slider at **Max** (no project/approved MCPs), as noted under [Quick mode](#quick-mode) above.
 
 Click **Fine-tune** to set the flags individually. One toggle only appears here:
 
-- **My approved MCPs** — loads the MCP servers you've already approved locally (`claude mcp add` / `codex mcp add`) without changing where the spawn runs. Explore-only; disabled in Quick mode. On a **Gemini** project, Gemini reads your own approved MCP servers from its native config (`~/.gemini`) automatically, so this toggle isn't needed there.
+- **My approved MCPs** — loads the MCP servers you've already approved locally (`claude mcp add` / `codex mcp add`) without changing where the spawn runs. Explore-only; disabled in Quick mode. On a **Gemini** project, Gemini reads your own approved MCP servers from its native config (`~/.gemini`) automatically, so this toggle isn't needed there. Kimi's user-global MCP source cannot be isolated per spawn, so this opt-in is unavailable for Kimi; project `.kimi-code/mcp.json` remains supported.
 
 **Buttons in the shell:**
 
@@ -128,6 +150,11 @@ Got an epic that's clearly too big? Open it and click **SMASH Spec into Sub-Spec
 
 Inside the epic's modal you'll see an **Epic Family Sidebar** listing all children. Inside each child's modal, an **Epic Breadcrumb** lets you jump back to the parent. If the epic already has children, the button reads **Re-SMASH** and regenerates the family (after a confirmation).
 
+SMASH and Re-SMASH are unavailable for Kimi: both require a constrained
+structured transform, and Re-SMASH can delete existing children. Desktop
+checks the capability before any spawn or deletion, so a direct Kimi request
+leaves the existing family untouched.
+
 ## Continue Editing — refine an existing spec
 
 For any spec with status `draft`, `todo`, or `backlog`, the detail modal shows a **Continue Editing** button. Click it and:
@@ -140,6 +167,10 @@ For any spec with status `draft`, `todo`, or `backlog`, the detail modal shows a
 
 Continue Editing works from the dashboard or from inside a split-view comparison — triggering it from a split-view panel collapses the comparison automatically because the shell needs the full screen.
 
+The AI Edit/refine operation is unavailable for Kimi because its output-only
+rewrite contract must not be able to mutate the workspace through tools.
+Manual edits and a separate Kimi Explore proposal remain available.
+
 The Contract Layer (if a spec has one) is shown inside the detail modal as a collapsible disclosure with an `N/5 populated` badge. You can re-run the enrichment for a single ticket from there.
 
 ## Status visuals
@@ -197,7 +228,7 @@ You don't need this to use the feature, but it's nice to know:
 
 - Specs live in `<project>/.specrails/local-tickets.json` (a JSON store).
 - A file watcher catches external edits (e.g. when an agent flips a spec to `in_progress`) and broadcasts a WebSocket event, so the board updates instantly.
-- Every AI CLI invocation that creates or refines a spec is recorded in your analytics under one of these surfaces:
+- Every AI CLI invocation that actually creates or refines a spec is recorded in your analytics under one of these surfaces:
   - `quick-spec` — Quick mode generation (and the Quick-mode Contract Refine pass).
   - `explore-spec` — every Explore conversation turn (and the Explore Contract Refine pass).
   - `ai-edit` — Continue Editing / AI Edit refine turns.
@@ -209,3 +240,4 @@ You don't need this to use the feature, but it's nice to know:
 - [Tracking cost](tracking-cost.md) — see what each spec is costing you.
 - [Customising the app](customizing.md) — set a daily budget so you can stop worrying.
 - [Using Codex](codex.md) / [Using Gemini](gemini.md) — provider-specific notes if you generate specs with Codex or Gemini.
+- [Using Kimi](kimi.md) — agentic spec surfaces and the structured actions that fail closed.

package/docs/customizing.md

@@ -67,7 +67,7 @@ A custom instruction appended to every **Implement** and **Batch-implement** rai
 
 ### Freestyle pre-prompt
 
-The instruction sent to Claude for **Freestyle** rails (Claude-only). Freestyle skips the OpenSpec pipeline — it hands Claude this pre-prompt plus the spec text and lets it implement autonomously. The spec text is appended automatically after the pre-prompt. Leave it blank to use the built-in default.
+The instruction sent to the selected provider for **Freestyle** rails. Freestyle skips the OpenSpec pipeline — it hands that provider this pre-prompt plus the spec text and lets it implement autonomously. Claude and Kimi currently advertise Freestyle support. The spec text is appended automatically after the pre-prompt. Leave it blank to use the built-in default.
 
 ### Telemetry
 
@@ -130,9 +130,9 @@ The app binds to `127.0.0.1` only, so it's never exposed to your network. To rot
 
 ## Providers
 
-The app works with **three interchangeable AI providers — Claude, Codex, and Gemini — all enabled by default.** When you add a project you pick which provider(s) to install (you can install any subset; the first one becomes the project's default). The engine pickers on Add Spec, the rail header, and the terminal's "Open AI CLI" button appear automatically whenever more than one provider is installed.
+The app works with **four AI providers — Claude, Codex, Gemini, and Kimi — all enabled by default.** When you add a project you pick which provider(s) to install (you can install any subset; the first one becomes the project's default). The engine pickers on Add Spec, the rail header, and the terminal's "Open AI CLI" button appear automatically whenever more than one provider is installed.
 
-You normally don't configure anything here — providers are selected per project in the UI. The only knobs are the **emergency rollback** env vars below (one per provider), which force a provider back to "unavailable" without redeploying. See [codex.md](codex.md) and [gemini.md](gemini.md) for each provider's setup, auth, and limitations.
+You normally don't configure anything here — providers are selected per project in the UI. Codex and Gemini have the emergency rollback env vars below; Kimi availability follows executable/version detection and Core compatibility. See [codex.md](codex.md), [gemini.md](gemini.md), and [kimi.md](kimi.md) for setup, authentication, and limitations.
 
 ## Environment variables
 
@@ -148,7 +148,7 @@ Most settings live in the UI. A few app-level switches are env-only because they
 
 | Variable | Effect |
 |----------|--------|
-| `SPECRAILS_CORE_BIN` | Override the `specrails-core` binary (default: `npx --yes --prefer-online specrails-core@^4.8.0` — the 4.8.0 floor is the release that ships the Gemini provider target) |
+| `SPECRAILS_CORE_BIN` | Override the `specrails-core` binary (default: `npx --yes --prefer-online specrails-core@^4.12.0` — the 4.12.0 floor is the release that ships the Kimi provider target) |
 | `SPECRAILS_TECH_URL` | Override the specrails-tech proxy base URL |
 | `SPECRAILS_AGENTS_SECTION=false` | Hide the Agents section from every project |
 | `SPECRAILS_PLUGINS_SECTION=false` | Hide the Integrations section from every project |
@@ -162,7 +162,7 @@ Most settings live in the UI. A few app-level switches are env-only because they
 | `SPECRAILS_SMASH=0` | Kill switch for SMASH spec decomposition (`0` / `false` / `off`; endpoints return 409) |
 | `SPECRAILS_EXPLORE_CONTRACT_REFINE=0` | App-wide kill switch for Contract Refine (auto-fire + retry endpoint; accepts `0` / `false` / `off`) |
 | `SPECRAILS_EXPLORE_LEGACY_CWD=1` | Force every Explore spawn to use the project root instead of the app-managed `explore-cwd/` or a relocated workspace |
-| `SPECRAILS_FILE_SUMMARY_MODEL` | Override the model used for Code-section file summaries. Per-provider overrides take precedence: `SPECRAILS_FILE_SUMMARY_MODEL_CLAUDE` (Claude) and `SPECRAILS_FILE_SUMMARY_MODEL_CODEX` (Codex); the generic var is the fallback |
+| `SPECRAILS_FILE_SUMMARY_MODEL` | Override the model used for Code-section file summaries. Per-provider overrides take precedence: `SPECRAILS_FILE_SUMMARY_MODEL_CLAUDE` (Claude) and `SPECRAILS_FILE_SUMMARY_MODEL_CODEX` (Codex); the generic var is the fallback. Kimi file summaries and construction-story AI are capability-gated off, so this variable never enables them for Kimi. |
 | `SPECRAILS_ALLOW_LOCAL_WEBHOOKS=1` | Allow outbound webhooks to target loopback / private-network addresses |
 
 ### Client-side (Vite — set at build time)

package/docs/gemini.md

@@ -1,11 +1,10 @@
 # Using Specrails with the Gemini CLI
 
-Specrails supports **three AI providers**: Anthropic's
+Specrails supports **four AI providers**: Anthropic's
 [Claude Code](https://claude.com/claude-code), OpenAI's
 [Codex CLI](https://developers.openai.com/codex), and Google's
-[Gemini CLI](https://github.com/google-gemini/gemini-cli). You pick one,
-two, or all three when you add a project, and the rest of the app behaves
-the same across them.
+[Gemini CLI](https://github.com/google-gemini/gemini-cli), plus
+[Kimi Code](kimi.md). You pick any compatible subset when you add a project.
 
 > **Gemini is enabled by default** (parity with Claude and Codex). It shows
 > up in **Add Project** and is selectable whenever the `gemini` CLI is on
@@ -16,8 +15,8 @@ the same across them.
 
 **What works with Gemini:** Explore Spec, Quick spec, AI Edit, the terminal
 "Open AI CLI" launcher, cost analytics, **and the full rails pipeline**
-(`/specrails:implement`, `batch-implement`). The one exception is
-**Freestyle rails**, which remain Claude-only.
+(`/specrails:implement`, `batch-implement`). Gemini does not advertise
+**Freestyle rails**; choose Claude or Kimi for that autonomous rail mode.
 
 ## Prerequisites
 
@@ -25,12 +24,13 @@ the same across them.
 |---|---|---|
 | `gemini` CLI ≥ 0.11.0 | Earlier versions lack `--output-format stream-json` + headless `--resume`, which the app relies on | `npm i -g @google/gemini-cli` · check with `gemini --version` |
 | A Gemini API key | The app spawns Gemini headlessly, so it needs non-interactive auth | Set `GEMINI_API_KEY` to a paid Gemini Developer API key from [Google AI Studio](https://aistudio.google.com/apikey) |
-| `specrails-core` ≥ 4.8.0 in the project | 4.8.0 ships the Gemini provider target (`.gemini/` commands + agents) that the rails pipeline needs | The Add-Project install flow uses `specrails-core@^4.8.0` automatically |
+| `specrails-core` ≥ 4.8.0 in the project | 4.8.0 ships the Gemini provider target (`.gemini/` commands + agents) that the rails pipeline needs | The current Add-Project install flow uses `specrails-core@^4.12.0` automatically |
 | `git`, `node`, `npm`, `npx` | Same as Claude — needed for `specrails-core init` | Use your usual installer |
 
 > **Two different minimums.** The `gemini` **binary** floor is **0.11.0**.
-> The `specrails-core` **package** floor is **4.8.0** (a single shared
-> version for all providers). They are separate things — the binary on your
+> The current Desktop `specrails-core` **package** floor is **4.12.0** (a
+> single shared version for all providers, including Kimi). They are separate
+> things — the binary on your
 > machine vs. the artifacts installed into the project.
 
 **On the API key.** The free OAuth "Login with Google" tier exists, but it
@@ -52,7 +52,7 @@ the Gemini provider checkbox with a "not found" hint when the binary isn't on
    project](#running-multiple-providers-in-one-project)). The first provider
    you select becomes the project default.
 4. Submit. The app writes `.specrails/install-config.yaml` and spawns
-   `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <file>`.
+   `npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <file>`.
    The install produces the `.gemini/` artifacts (commands + `sr-*` agents),
    plus a `GEMINI.md` instructions file.
 
@@ -79,7 +79,7 @@ these pickers don't render — there's nothing to choose.
 
 ## Running multiple providers in one project
 
-A single project can install **Claude, Codex, and Gemini** in any
+A single project can install **Claude, Codex, Gemini, and Kimi** in any
 combination. In **Add Project** the **AI providers** control is a
 multi-select; check the ones you want and the app runs each provider's
 install sequentially. The first you select is the **primary/default**.
@@ -88,31 +88,26 @@ Once more than one is installed:
 
 - **Engine pickers** (above) appear on Add Spec, the rail header, and the
   terminal launcher.
-- **Capability intersection.** The right sidebar only shows sections that
-  *every* installed provider supports. Because Gemini and Codex have no
-  agent profiles, the **Agents** section is **hidden** on a mixed project.
-  The **Integrations** section stays visible (it hosts the
-  provider-agnostic Jira card); only the Serena **plugin** entry inside it
-  is filtered per-provider. In the Add Spec dialog, the SMASH and Contract
-  Layer options are hidden when the selected engine is Gemini.
+- **Capabilities are provider-scoped.** Gemini/Codex rails run in legacy
+  profile mode; Claude/Kimi profiles stay independent. Integration
+  state/health and structured-action selectors follow the effective provider.
 
 When only one provider is installed the app behaves byte-identically to a
 single-provider project — no engine pickers, no provider persisted on spawns.
 
 ## What's different vs Claude
 
-| Capability | Claude | Codex | Gemini |
-|---|---|---|---|
-| **CLI / project dir** | `claude` / `.claude/` | `codex` / `.codex/` | `gemini` / `.gemini/` |
-| **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` |
-| **Native cost report** | ✅ `total_cost_usd` | ❌ estimated | ❌ estimated |
-| **Native OTEL** | ✅ | 🔧 synthesized by the app | ✅ native (no bridge) |
-| **`--system-prompt` flag** | ✅ | ❌ folded into prompt | ❌ folded into prompt |
-| **Rails pipeline** | ✅ | ✅ | ✅ |
-| **Freestyle rails** | ✅ | ❌ Claude-only | ❌ Claude-only |
-| **Agent profiles on rails** | ✅ | ❌ forced legacy | ❌ forced legacy |
-| **SMASH / Contract Refine** | ✅ | ❌ Claude-only | ❌ Claude-only |
-| **Plugins (Serena)** | ✅ | ❌ | ⚠️ offered, doesn't load (known gap) |
+| Capability | Claude | Codex | Gemini | Kimi |
+|---|---|---|---|---|
+| **CLI / project dir** | `claude` / `.claude/` | `codex` / `.codex/` | `gemini` / `.gemini/` | `kimi` / `.kimi-code/` |
+| **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` | `AGENTS.md` |
+| **Native cost report** | ✅ exact | ❌ estimated | ❌ estimated | ❌ unavailable |
+| **Native OTEL** | ✅ | 🔧 synthesized | ✅ native | ❌ |
+| **Rails pipeline** | ✅ | ✅ | ✅ | ✅ |
+| **Freestyle rails** | ✅ | ❌ | ❌ | ✅ |
+| **Agent profiles on rails** | ✅ | ❌ legacy | ❌ legacy | ✅ provider-scoped |
+| **Pure-output transforms** | capability-dependent | capability-dependent | capability-dependent | ❌ fail closed |
+| **Plugins (Serena)** | ✅ | ✅ provider-scoped | ❌ not declared | ✅ provider-scoped |
 
 A few of these deserve a fuller explanation:
 
@@ -128,23 +123,16 @@ A few of these deserve a fuller explanation:
   non-Explore actions the system prompt is folded into the user prompt.
   Explore turns stay user-only and trust the app-managed `GEMINI.md` in the
   explore cwd.
-- **Agent profiles aren't selectable for Gemini rails.** The rails router
-  forces the profile to `null` (legacy mode) for any non-Claude engine. (UI
-  limitation: the rail header may still render a profile picker for a Gemini
-  rail, but the server ignores the selection.)
-- **Plugins are offered but don't actually load (known gap).** Gemini is
-  declared a `project-json` MCP provider, so the Integrations page offers
-  plugins such as **Serena** and installing one writes
-  `<project>/.mcp.json` — but gemini-cli has **never read `.mcp.json`**
-  (a Claude convention). Its only MCP surface is `mcpServers` in
-  `settings.json` (`~/.gemini/` or `<cwd>/.gemini/`), so the plugin's MCP
-  server silently never loads in Gemini rail spawns. Fixing this means
-  writing into the repo's `.gemini/settings.json`, which conflicts with
-  the keep-the-repo-pristine policy — it's a deliberate deferred change.
-  (The desktop **Agent Chat** registers its own Specrails MCP for Gemini
-  correctly, via `.gemini/settings.json` in the app-owned agent cwd plus
-  `GEMINI_CLI_TRUST_WORKSPACE=true`; there Gemini sees the tools with an
-  FQN prefix, `mcp_specrails_<name>`.) Details:
+- **Agent profiles aren't selectable for Gemini rails.** Gemini does not
+  advertise profile support, so the rails router forces legacy/no-profile mode.
+  Claude and Kimi keep independent provider-scoped profile catalogs.
+- **Serena is not offered for Gemini.** Plugin entries are filtered by the
+  manifest's provider support. Gemini CLI has never read Claude's `.mcp.json`;
+  its MCP surface is `mcpServers` in `settings.json`, so silently installing a
+  Claude-style entry would be incorrect. The desktop **Agent Chat** registers
+  its own Specrails MCP for Gemini correctly, via `.gemini/settings.json` in
+  the app-owned agent cwd plus `GEMINI_CLI_TRUST_WORKSPACE=true`; there Gemini
+  sees the tools with an FQN prefix, `mcp_specrails_<name>`. Details:
   [internals/gemini-mcp-registration.md](internals/gemini-mcp-registration.md).
 
 ## How rails work headlessly (`prepareHeadlessSpawn`)

package/docs/getting-started.md

@@ -4,7 +4,7 @@ This guide walks you from "I just heard about specrails-desktop" to "I just ship
 
 ## What you'll need
 
-- **An AI CLI signed in** — [Claude Code](https://claude.com/claude-code) (via Claude subscription login or an `ANTHROPIC_API_KEY`), the [Codex CLI](codex.md) (`codex` ≥ 0.128.0), or the [Gemini CLI](gemini.md) (`gemini` ≥ 0.11.0, with `GEMINI_API_KEY` set). You can mix and match — install Claude, Codex, Gemini, or any combination.
+- **An AI CLI signed in** — [Claude Code](https://claude.com/claude-code), the [Codex CLI](codex.md) (`codex` ≥ 0.128.0), the [Gemini CLI](gemini.md) (`gemini` ≥ 0.11.0), or [Kimi Code](kimi.md) (`kimi` ≥ 0.27.0). You can install any compatible combination.
 - A project you want to work on (any Git repository works)
 
 If you install with **npm** (Option 2 below) you'll also need **Node.js 20+** and **`git`** on your PATH. The **desktop app** bundles its own Node and Git runtimes, so you don't need those installed separately.
@@ -43,7 +43,7 @@ There are two ways. Pick whichever feels natural.
 
 1. Click **+** in the left sidebar.
 2. Enter the absolute path to your project (e.g. `/Users/you/repos/my-app`).
-3. Pick your **AI providers**. Check **Claude**, **Codex**, **Gemini**, or any combination — the first one in the list (Claude, then Codex, then Gemini) that you check becomes the project default. The provider set is fixed once the project is created.
+3. Pick your **AI providers**. Check **Claude**, **Codex**, **Gemini**, **Kimi**, or any combination — the first checked provider becomes the project default. The provider set is fixed once the project is created.
 4. The prerequisites panel verifies `node`, `npm`, `npx`, `git`. If anything's missing, the panel surfaces OS-aware install commands you can copy.
 5. Click **Add**.
 
@@ -54,14 +54,14 @@ specrails-desktop add /path/to/your/project
 specrails-desktop list   # verify
 ```
 
-> Heads-up: if you run a spec from the CLI while no app server is running, the offline fallback always invokes `claude` — regardless of the project's primary provider — and records nothing to Analytics. Start the app (or `specrails-desktop start`) to use Codex or Gemini and to capture cost tracking.
+> Heads-up: if you run a spec from the CLI while no app server is running, the offline fallback always invokes `claude` — regardless of the project's primary provider — and records nothing to Analytics. Start the app (or `specrails-desktop start`) to use Codex, Gemini, or Kimi and to capture analytics.
 
 ### If the project doesn't have specrails-core yet
 
 The setup wizard runs automatically. Three steps:
 
 1. **Configure** — choose which agents to install (the baseline trio `sr-architect`, `sr-developer`, `sr-reviewer` is always selected; optional agents like Test Writer or Security Reviewer are opt-in). Pick a model preset (Balanced / Budget / Max) and optionally override the model per agent.
-2. **Install** — the app runs the installer (`npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <config>`) non-interactively and streams the output live. The version is pinned to the core release the app ships with — it never silently jumps to a new major.
+2. **Install** — the app runs the installer (`npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <config>`) non-interactively and streams the output live. The version is pinned to the core release the app ships with — it never silently jumps to a new major.
 3. **Done** — a summary tells you how many agents and commands landed. Click **Continue to project**.
 
 That's the whole onboarding. No tier picker, no second wizard. You can manage agents and their per-agent models later from the **Agents** page (Profiles tab).
@@ -74,12 +74,17 @@ A "spec" is a description of work you want done. specrails-desktop gives you two
 
 When you already know what you want:
 
-1. On the Dashboard, click **+ Add Spec → Quick**.
+1. On the Dashboard, click **+ Add Spec → Quick**. Quick Spec is offered
+   only for providers with the required pure-output safety boundary; Kimi uses
+   Explore or the agentic Quick Launcher instead.
 2. Type a one-line title (e.g. *"Add a webhook retry with exponential backoff"*).
-3. (Optional) toggle **Enrich with Contract Layer** to get a structured block of names, data shapes, invariants, and a file touch list appended to the description. (Contract Layer enrichment is a Claude-only feature — on Codex and Gemini projects the toggle is shown but the refinement step is skipped.)
+3. (Optional) toggle **Enrich with Contract Layer** to get a structured block of names, data shapes, invariants, and a file touch list appended to the description. This structured action is Claude-only; providers without an enforceable no-tools boundary, including Kimi, do not offer it.
 4. Hit Enter.
 
-Your AI CLI generates the full spec in one turn. A small toast at the bottom right shows the project, the spec title, and live elapsed time ("Generating… 0:12") — it turns into a success or failure toast (with a **View** action) when generation finishes.
+A compatible AI CLI generates the full spec in one turn. A small toast at the
+bottom right shows the project, the spec title, and live elapsed time
+("Generating… 0:12") — it turns into a success or failure toast (with a
+**View** action) when generation finishes.
 
 ### Explore mode — converse with the AI
 
@@ -104,7 +109,7 @@ The right pane of the Dashboard is your **Rails** — execution lanes:
 
 The rail flips to running. The Jobs page (right sidebar) streams the AI's output live. When the slash command defines them, you'll see the pipeline phases progress: Architect → Developer → Reviewer → Ship.
 
-Token usage, duration, and cost are tracked per turn and surface in:
+Duration, outcome, and available usage/cost are tracked per turn and surface in. Kimi's stream does not report tokens or native USD cost, so those fields remain unavailable rather than appearing as zero:
 
 - **Jobs page** — each job has a status panel with live counters and a `JobTicketHeader` chip for every ticket the job touched (click to open).
 - **Analytics page** — burn rate, top tickets, daily timeline (see [Tracking cost](tracking-cost.md)).
@@ -117,6 +122,7 @@ Token usage, duration, and cost are tracked per turn and surface in:
 - **[Tracking cost](tracking-cost.md)** — analytics deep dive and CSV exports.
 - **[Codex](codex.md)** — using the Codex CLI as a provider, alongside or instead of Claude.
 - **[Gemini](gemini.md)** — using the Gemini CLI as a provider, alongside or instead of Claude.
+- **[Kimi](kimi.md)** — using Kimi Code, including its CLI-only execution and truthful usage limitations.
 - **[Terminal panel](terminal.md)** — the built-in per-project terminal (toggle with `Cmd/Ctrl+J`).
 - **[Customising the app](customizing.md)** — themes, terminal settings, kill switches.
 - **[CLI reference](cli.md)** — drive specrails-desktop from the terminal.
@@ -131,7 +137,7 @@ specrails-desktop stop                # stops the running server cleanly
 lsof -i :4200    # macOS / Linux
 ```
 
-**Your AI CLI (`claude`, `codex`, or `gemini`) isn't found inside the app**
+**Your AI CLI (`claude`, `codex`, `gemini`, or `kimi`) isn't found inside the app**
 
 On macOS, this usually means the app was launched from Finder/Dock and didn't pick up Homebrew/Volta paths. The app resolves PATH at startup automatically, but if it still fails, see [platforms/macos.md](platforms/macos.md).
 

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

@@ -37,7 +37,11 @@ Das ist der ganze Ablauf: Profil wählen, starten, fertig. Gleichzeitig laufende
 
 ## Wenn der Agents-Bereich still ist
 
-Profile sind eine Claude-Fähigkeit. Bei einem Projekt, das einen Nicht-Claude-Provider (Codex oder Gemini) enthält, ist der Agents-Bereich ausgeblendet und Rails laufen ohne Profile – das ist so gewollt, kein Fehler. Außerdem setzen Profile ein hinreichend aktuelles `specrails-core` im Projekt voraus; ist es älter, siehst du ein gelbes Banner. Die von dir erstellten Profile werden trotzdem **gespeichert** – sie wirken sich nur erst auf die Pipeline aus, wenn core aktualisiert ist. Aktualisiere mit dem im Banner gezeigten Befehl, um sie freizuschalten.
+Profile sind provider-spezifisch. Claude und Kimi unterstützen Profile/Rollen;
+Codex und Gemini laufen im Legacy-Modus. Gleiche Namen können in gemischten
+Projekten nicht zwischen Claude und Kimi übergreifen. Kimi erlaubt manuelle
+Rollen, aber Agent-Studio-Generierung, Smoke-Test und AI Refine werden vor dem
+Spawn abgelehnt. Kimi benötigt `specrails-core` 4.12.0 oder neuer.
 
 ## Wie es weitergeht
 

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

@@ -11,21 +11,24 @@ Jeder Katalogeintrag zeigt, wofür der Agent da ist und welches Standardmodell e
 
 ## Einen Custom-Agent hinzufügen
 
-Custom-Agents sind schlichte Markdown-Dateien in deinem Repository unter `.claude/agents/`, benannt als `custom-<etwas>.md`. Die Datei enthält die Anweisungen des Agents (seinen System-Prompt) und einen kleinen Frontmatter-Header mit einem Standard-`model:`.
+Rollen sind provider-native Assets: Claude nutzt
+`.claude/agents/custom-<name>.md`, Kimi nutzt
+`.kimi-code/skills/custom-<name>/SKILL.md`.
 
-Sobald die Datei im Projekt existiert, erscheint sie im Katalog als Custom-Agent, und du kannst ihre id zur Agent-Kette jedes Profils hinzufügen (und Aufgaben an sie routen). Die id muss zum Dateinamen passen – ein Eintrag für `custom-docs` verweist auf `.claude/agents/custom-docs.md`.
+Sobald das Asset existiert, erscheint es im Katalog dieses Providers und seine id kann einem Profil desselben Providers hinzugefügt werden. `custom-docs` verweist bei Claude auf `.claude/agents/custom-docs.md`, bei Kimi auf `.kimi-code/skills/custom-docs/SKILL.md`; beide bleiben getrennt.
 
 Weil sie in deinem Repo leben, sind Custom-Agents **committfähige Team-Assets**: Committe die Datei, und dein ganzes Team bekommt den Agent. Das spiegelt die Kernidee, die sich durch den gesamten Agents-Bereich zieht –
 
 > **Agent-Definitionen sind geteilt (sie leben im Repo und reisen mit `git` mit). Die Modellkonfiguration ist projektbezogen (sie lebt in Profilen).**
 
-Der `custom-*`-Namespace ist reserviert und geschützt: Die Befehle `init` und `update` von `specrails-core` fassen `.claude/agents/custom-*.md` nie an, sodass deine Custom-Agents Core-Upgrades unangetastet überstehen. (Derselbe Schutz gilt für von Plugins beigesteuerte Fragmente wie `custom-serena.md`.)
+Core schützt beide Formate. Kimi erlaubt manuelles Erstellen/Bearbeiten und
+Ausführung; Generate, Test und AI Refine werden vor dem Spawn abgelehnt.
 
 ## Einen Custom-Agent einsetzen
 
 Der typische Ablauf:
 
-1. Schreibe `.claude/agents/custom-<name>.md` mit Anweisungen und einem Standardmodell.
+1. Erstelle das native Claude-Asset oder den Kimi Skill mit gültigen Anweisungen/Modell.
 2. Stelle sicher, dass er unter **Agents → Katalog** im Bereich Custom auftaucht.
 3. Füge den Agent unter **Agents → Profile** zur Kette eines Profils hinzu (und überschreibe optional sein Modell für dieses Profil).
 4. Ergänze eine Routing-Regel, damit Aufgaben mit den passenden Tags ihn erreichen – oder verlasse dich auf die Reihenfolge der Kette.

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

@@ -36,6 +36,7 @@ specrails arbeitet mit den großen KI-Programmier-CLIs zusammen:
 - **Claude** (Claude Code)
 - **Codex** (Codex CLI)
 - **Gemini** (Gemini CLI)
+- **Kimi** (Kimi Code)
 
 Nimm einfach den, den du ohnehin schon nutzt – oder installiere mehrere und wähle pro Aufgabe. Ein Projekt kann mit einem einzelnen Provider oder mit mehreren gleichzeitig laufen, sodass du dich nie festlegen musst.