specrails-desktop 2.30.2 → 2.31.0

package/docs/internals/project-builder.md

@@ -4,6 +4,12 @@
 > idea: a day-0 blueprint conversation, an orchestrated bootstrap commit, and a
 > milestone lifecycle (Launch M1 batch rail, sidebar re-entry, Generate M2+).
 
+> **Kimi capability boundary:** Kimi may be selected as a target provider for
+> the materialized project, and it may launch an already committed milestone
+> through the normal agentic Batch rail. Day-0 blueprint snapshots and M2+
+> milestone generation are pure structured-output actions and therefore fail
+> closed for Kimi 0.27 `-p`; no Kimi process is spawned for them.
+
 ## Entry + builder mode (reskin)
 
 "+ Add Project" shows an **Existing | New** pre-screen (`AddProjectDialog`,
@@ -68,6 +74,11 @@ route).
 
 ## Day-0 chat (no project exists)
 
+The provider selector excludes adapters that cannot enforce the blueprint
+generator's pure-output policy. A direct Kimi request is rejected before
+`BlueprintChatManager` spawns. This does not prevent the approved blueprint
+from declaring Kimi among the new project's target providers.
+
 - **Manager**: `server/blueprint-chat-manager.ts` `BlueprintChatManager` — an
   app-level sibling of `AgentChatManager` reusing `runAiCliInvocation`. Spawns
   from `~/.specrails/builder-cwd/` (`server/builder-cwd-manager.ts`: always
@@ -228,6 +239,11 @@ step 6 it is an ordinary project missing only the remote.
 
 ## Milestone lifecycle
 
+Generating detailed M2+ specs uses the same pure-output capability gate as
+day-0 blueprint generation. Kimi cannot be selected for that generation turn.
+Launching the already committed M1/M2+ tickets is ordinary Batch rail
+execution and can use Kimi.
+
 - **Launch Milestone 1** (`client/src/lib/milestone-launch.ts`
   `launchMilestone`): gather `M1`-labeled `todo` tickets → `POST /rails`
   (server allocates the lowest free index) → `PUT /rails/:i/tickets` → `POST

package/docs/kimi.md

@@ -0,0 +1,291 @@
+# Using Kimi Code with Specrails Desktop
+
+Kimi Code is a first-class, independent provider in Specrails Desktop. Desktop
+launches the external `kimi` CLI directly; it does not bundle a Kimi runtime,
+start `kimi server`, invoke `kimi acp`, or install a persistent service.
+
+## Requirements
+
+- Specrails Desktop with Kimi provider support.
+- `specrails-core` 4.12.0 or newer with the `.kimi-code` framework target.
+- Kimi Code 0.27.0 or newer.
+- A completed Kimi login or a valid user-managed Kimi model configuration.
+
+Install Kimi from its official documentation:
+
+```bash
+# macOS / Linux
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+kimi login
+```
+
+```powershell
+# Windows PowerShell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+kimi login
+```
+
+The official npm package (`@moonshot-ai/kimi-code`) is also supported, but its
+current CLI requires Node.js 22.19 or newer. On Windows, Kimi also requires Git
+for Windows because it uses Git Bash; set `KIMI_SHELL_PATH` when `bash.exe`
+lives outside the standard locations. Specrails never installs any of these
+dependencies for you.
+
+Restart Desktop after changing `PATH`. Setup checks `kimi --version` without
+sending a model prompt. Kimi 0.27 does not provide a non-billing command that
+conclusively proves OAuth readiness, so the first real request may still ask
+you to run `kimi login`.
+
+### Windows prompt transport
+
+Desktop never invokes a Kimi command shim through `cmd.exe`. For the standard
+npm `kimi.cmd`/`kimi.bat`, it launches the package's JavaScript entry with Node
+and carries the complete materialized prompt over `stdin`; multiline text,
+Unicode, and long SpecRails workflows therefore do not consume the Win32
+command-line budget.
+
+A native `kimi.exe` is launched directly with no shell and works for prompts
+whose complete command line is at most 30,000 UTF-16 code units. Kimi 0.27 has
+no equivalent stdin or response-file option for that native executable, so
+Desktop rejects a larger native invocation before spawn instead of truncating
+the workflow. Install the official npm package
+(`npm install -g @moonshot-ai/kimi-code`, Node.js 22.19+) when complete long
+workflows are required on Windows. No Kimi server is involved in either path.
+
+## Add or build a project
+
+Kimi appears in Add Project and Project Builder when the executable is
+available. Selecting it asks Core to materialize:
+
+```text
+.kimi-code/
+├── AGENTS.md
+├── mcp.json
+├── rules/
+└── skills/
+    ├── specrails-*/SKILL.md
+    ├── openspec-*/SKILL.md
+    └── sr-*/SKILL.md
+```
+
+Kimi scans directory-form skills as direct children of the skills root.
+SpecRails therefore keeps roles at `skills/sr-*/SKILL.md` rather than in a
+nested catalog that the stable engine would not discover.
+
+In a multi-provider project, Kimi is an independent engine choice on
+capability-compatible chat, rail, loop, profile, integration, and terminal
+surfaces. Switching to it does not rewrite a Claude, Codex, or Gemini tree.
+Provider membership is fixed when the project is created; re-register the
+project to choose a different set.
+
+## Models and effort
+
+Desktop stores Kimi's public model ids:
+
+| Model id | UI label |
+|----------|----------|
+| `k3` | Kimi K3 |
+| `kimi-for-coding` | Kimi for Coding |
+| `kimi-for-coding-highspeed` | Kimi for Coding Highspeed |
+
+At the CLI boundary only, those three ids map to managed aliases such as
+`kimi-code/k3`. Already-prefixed and custom aliases pass through unchanged.
+
+K3 offers `low`, `high`, and `max` reasoning effort. Those controls are shown
+only when the effective model is `k3` or `kimi-code/k3`; the two
+`kimi-for-coding` models and custom aliases do not inherit K3 effort. Desktop
+defaults K3 to its upstream `high` setting and applies a valid selection to one
+child process through
+`KIMI_MODEL_THINKING_EFFORT` and removes inherited effort otherwise,
+preventing cross-provider or cross-model leakage.
+
+Every Desktop-managed spawn also removes `KIMI_CODE_EXPERIMENTAL_FLAG` from
+the child environment. The integration is qualified against Kimi Code 0.27's
+stable v1 engine and JSONL contract; a user-level opt-in to the experimental v2
+engine must not silently switch Desktop to a different, unqualified runtime.
+It also forces `KIMI_DISABLE_CRON=1`: prompt mode auto-approves tools, while
+Desktop has no scheduler lifecycle or UI for Kimi's persistent `CronCreate`
+facility, so an owned child must not leave scheduled work behind. Background
+task drain/steer behavior inside the live child is unchanged. Finally,
+`KIMI_CODE_NO_AUTO_UPDATE=1` disables Kimi's startup update preflight so a job
+runs the external version that passed Desktop's compatibility check instead of
+self-updating mid-invocation. All three controls replace inherited keys
+case-insensitively.
+
+## Execution and resume
+
+A new Kimi turn uses:
+
+```bash
+kimi -m kimi-code/k3 \
+  -p "<ordinary prompt or Desktop-materialized Kimi skill prompt>" \
+  --output-format stream-json
+```
+
+A subtle but load-bearing distinction applies here. Kimi's interactive TUI and
+ACP client intercept `/skill:<name>` and call the skill-activation API, but the
+0.27 print runner sends `-p` text directly to `session.prompt()`. Desktop
+therefore never relies on a literal `/skill:…` surviving into `-p`. It resolves
+the direct-child `SKILL.md`, substitutes Kimi's argument placeholders, adds the
+same `<kimi-skill-loaded>` envelope used by upstream activation, and then
+passes that materialized prompt to the external CLI. Missing or unsafe skill
+paths fail before process creation instead of becoming a zero-work success.
+The prompt seen by the model matches Kimi's activation format; because print
+mode itself still receives an ordinary user prompt, Kimi does not emit its
+internal `skill.activated`/`skill_invoked` telemetry for this host-side
+materialization. Desktop does not depend on those private events.
+
+On a resume, `${KIMI_SESSION_ID}` can be expanded from the known session value.
+On a fresh print session Kimi creates the ID internally and reveals it only in
+the terminal resume hint, so Desktop rejects a skill that requires that
+placeholder instead of substituting a false value. SpecRails' generated
+workflow and role skills do not use that placeholder.
+
+A known session resumes with the bound `--session=<session-id>` form so even an
+option-shaped value cannot become a new CLI flag. Desktop accepts only Kimi's
+upstream-safe session alphabet (`A-Z`, `a-z`, digits, `.`, `_`, `-`), rejects
+`.`/`..` and ids longer than 128 characters at both JSONL parsing and argv
+construction, and trusts an id only after Kimi emits the terminal
+`session.resume_hint`; it never invents one from process ids or local paths.
+
+Kimi can put assistant text and several function calls in one JSONL record.
+Desktop expands that record into every corresponding UI event, so text,
+activity chips, errors, and session state are not dropped. Unknown future
+events remain diagnostic records instead of crashing the stream.
+
+Cancel, Stop, app shutdown, and project removal terminate the owned process
+tree. There is no server lifecycle to manage.
+
+Kimi Code does ship optional `kimi acp` and `kimi server` entry points. This
+integration deliberately uses the documented `-p` non-interactive contract:
+it already runs tools agentically under Kimi's automatic prompt-mode policy,
+maps cleanly to Desktop's owned-child lifecycle, and avoids installing a
+service, opening a local port, or retaining an extra daemon. “No server
+lifecycle” means Specrails starts and owns no Kimi server; it does not mean the
+upstream CLI lacks that optional subcommand.
+
+## Feature coverage
+
+The important distinction is not “chat versus command”; it is whether a
+surface deliberately launches an **autonomous agent** or requires a
+**pure-output/read-only transform**. `kimi -p` is agentic and automatically
+approves tool use. Desktop therefore enables Kimi where that posture is part
+of the feature, and fails closed where the feature contract promises no tools
+or read-only behavior.
+
+### Available with Kimi
+
+| Surface | Kimi behavior |
+|---|---|
+| Project Chat and Agent Chat | Text, tools, errors, cancellation, session resume, attachments, and proposals use a fresh owned `kimi -p` process per turn. |
+| Explore | Conversation and proposal/draft work are available under Kimi's autonomous prompt-mode policy. It is not a filesystem sandbox. |
+| Quick Launcher | Agentic commands such as `/opsx:ff` are available. This is distinct from the pure-output **Quick Spec** form. |
+| Rails | Implement, Batch, Freestyle, retry/rerun, worktree isolation, cancellation, and ask-first PR delivery use Core's Kimi skills. |
+| Loops | Built-in and custom loops are available when the graph has no **Loop Decider**. AI and shell steps keep their normal agentic semantics. |
+| Project Builder delivery | Selecting Kimi as a target project provider and launching an already committed milestone through its Batch rail are available. Blueprint and milestone generation are not. |
+| Profiles and roles | Provider-scoped profiles, exact Kimi models, per-role routing, and manual `custom-*` role creation/editing/execution are available. |
+| MCP and integrations | Project `.kimi-code/mcp.json`, the Desktop bridge, provider-scoped plugins, and Serena are available through additive merges. |
+| Terminal and attachments | The integrated terminal launches the external CLI. Text and validated image references are available; Kimi reads images with `ReadMediaFile`. |
+| Analytics | Provider, model, duration, outcome, and session metadata are recorded. Unreported tokens and cost remain unavailable. |
+
+### Unavailable and rejected before spawn
+
+| Surface | Why it fails closed for Kimi |
+|---|---|
+| Quick Spec generation | Its structured output contract assumes a hard no-tools/read-only boundary that `kimi -p` cannot express. Use Explore or an agentic Quick Launcher command. |
+| AI Edit / Continue Editing refine | This pure-output rewrite must not be allowed to mutate the workspace with tools. |
+| Contract Refine | Requires an enforceable no-tools transform. |
+| SMASH and Re-SMASH | Structured decomposition requires a safe tool boundary; Re-SMASH is also destructive, so existing children are never deleted before the capability check. |
+| Project Builder blueprint and milestone generation | Day-0 blueprint snapshots and later detailed milestone batches are pure structured output. Kimi can still be a target provider and run a committed milestone rail. |
+| Loop Decider | The `continue`/`stop` verdict must be a constrained pure-output decision. Kimi loops containing a Decider are rejected. |
+| File summaries and construction-story AI | Code Explorer's generated summaries/story are read-only transforms. Existing deterministic/read-only explorer data remains usable. |
+| AI auto-title | No Kimi process is spawned; Desktop uses its deterministic title fallback. |
+| Agent Studio automation | Agent generation, smoke test, and AI Refine require the same boundary. Manual custom roles remain available. |
+
+These are server-side capability gates, not cosmetic UI omissions. A direct
+request that bypasses the hidden/disabled control is rejected before Kimi is
+spawned and, for destructive operations, before any state mutation.
+
+### Serena and provider-scoped plugin state
+
+In a project with more than one AI provider, Integrations asks which provider
+the Serena install targets. A Kimi install:
+
+- merges `mcpServers.serena` into `<project>/.kimi-code/mcp.json`;
+- contributes the managed Serena guidance block to
+  `<project>/.kimi-code/AGENTS.md`;
+- records Kimi independently under
+  `<project>/.specrails/plugins/state.json`;
+- verifies both `uv` and the Kimi MCP registration before committing; and
+- is included only in Kimi rail snapshots.
+
+Claude's `.mcp.json`/`CLAUDE.md`, Codex's isolated MCP registry plus root
+`AGENTS.md`, and Kimi's `.kimi-code/mcp.json` plus
+`.kimi-code/AGENTS.md` remain independent. Removing a provider's Serena
+installation therefore removes only that provider's managed guidance and MCP
+registration.
+
+## Native differences from Claude
+
+Application feature parity does not make unlike CLI protocols identical:
+
+- Kimi has no persistent stdin transport. Interactive conversations resume by
+  spawning a new `kimi -p` process with the recorded session id.
+- Kimi stream JSON has no terminal token/cost result. Desktop records model,
+  duration, status, and session, and leaves cost/tokens unavailable.
+- Kimi has no dedicated image argv; Desktop validates the managed attachment
+  path and includes explicit media-tool guidance in the prompt.
+- Prompt mode runs under Kimi's autonomous permission behavior and cannot be
+  combined with `--auto`, `--yolo`, or `--plan`.
+- Kimi has no per-spawn hard `none`/read-only tool flag. Desktop therefore
+  disables structured transforms that require a no-tools boundary instead of
+  treating prompt wording as a security sandbox.
+- Kimi loads its user-level MCP configuration according to Kimi's own rules.
+  Because Desktop cannot isolate that source per spawn, the user-MCP opt-in
+  control stays unavailable for Kimi; project `.kimi-code/mcp.json` remains
+  supported.
+
+## MCP
+
+Desktop merges its project bridge and integrations into
+`.kimi-code/mcp.json`. Existing server definitions are preserved. Invalid JSON
+fails safely instead of being replaced, and credentials are never copied into
+the project by the provider adapter.
+
+## Troubleshooting
+
+### Kimi is missing from the provider picker
+
+Run `kimi --version` in a fresh terminal, then restart Desktop. On Windows,
+confirm `where kimi` resolves `kimi.cmd`.
+
+### The CLI is too old
+
+Upgrade Kimi using its official installer. Desktop requires 0.27.0 or newer
+because its prompt-mode stream and session contract is the tested baseline.
+
+### Login or model alias error
+
+Run `kimi login`. Managed login creates aliases under `kimi-code/`. If you use
+a custom provider, make sure the exact alias stored in the profile exists in
+your `~/.kimi-code/config.toml`.
+
+### A Kimi project is missing skills
+
+Update Core/framework from Setup. OpenSpec 1.4.1 writes Kimi skills to a legacy
+`.kimi/skills` path; Core normalizes recognized `openspec-*` directories into
+`.kimi-code/skills` while preserving unknown and user-owned files.
+
+### A control is disabled for Kimi
+
+Check the [feature coverage matrix](#feature-coverage). Quick Spec, AI Edit,
+structured decomposition/refinement, blueprint/milestone generation, Loop
+Decider, Code Explorer AI transforms, AI auto-title, and Agent Studio
+automation deliberately do not spawn Kimi 0.27. This is a safety boundary, not
+an installation or authentication error.
+
+## References
+
+- [Kimi Code documentation](https://www.kimi.com/code/docs/en/)
+- [Kimi Code getting started](https://www.kimi.com/code/docs/en/kimi-code-cli/guides/getting-started)
+- [Kimi Code environment variables](https://www.kimi.com/code/docs/en/kimi-code-cli/configuration/env-vars.html)

package/docs/mcp.md

@@ -41,11 +41,11 @@ reading one description. The tools are:
 | `specrails_rails` | Assign tickets to a rail, configure it, and launch the pipeline — rails are dynamic (`create_rail`, up to 12) and `launch_all` starts every ready rail in parallel (worktree-isolated) |
 | `specrails_jobs` | Inspect, stream, and stop pipeline jobs |
 | `specrails_chat` | Explore / sidebar chat conversations and turns |
-| `specrails_agents` | Agent profiles and the agents catalog (Claude-only features) |
+| `specrails_agents` | Provider-scoped agent profiles and catalog (Claude and Kimi execution; Kimi manual roles only) |
 | `specrails_plugins` | The per-project plugin marketplace (install / verify / uninstall) |
 | `specrails_jira` | The Jira integration (connect, sync, outbox) |
 | `specrails_loops` | Saved loop workflows |
-| `specrails_code` | The read-only code explorer (tree, file, summaries, provenance) |
+| `specrails_code` | The code explorer (tree/file/provenance are provider-neutral; AI transforms are capability-gated) |
 | `specrails_setup` | Add-project setup wizard surface |
 | `specrails_analytics` | Per-project spending analytics + budget |
 | `specrails_settings` | App-level settings |
@@ -77,6 +77,13 @@ app's WebSocket bus. An agent gets the actual outcome by calling
 returns the final result. Don't assume success from the acceptance alone — this
 is spelled out in `specrails_guide`.
 
+Provider membership does not bypass capability checks. With Kimi, agentic
+chat/Explore/Quick Launcher/rails/loops without Decider/profiles are
+available, while Quick Spec, AI Edit, Contract Refine, SMASH/Re-SMASH,
+Project Builder generation, Loop Decider, Code Explorer AI transforms, and
+Agent Studio automation are rejected before spawn. Destructive gates run
+before any mutation.
+
 ## The four permission tiers
 
 Every tool declares one tier. The server refuses any tool whose tier is not

package/docs/platforms/macos.md

@@ -43,19 +43,26 @@ You only need this once per build. It does not apply to the notarized installers
 When you add a project, the app checks for the tools it needs and surfaces them in a **prerequisites panel** (in the `Add Project` dialog and the setup wizard). It checks:
 
 - **Bundled tools** — `node`, `npm`, `npx`, `git`.
-- **Provider CLIs** — **Claude Code**, **Codex**, and **Gemini CLI**. All three are always probed via your system `PATH` (never bundled). **At least one of the three must be installed and working** before Add Project is enabled — if none is usable the panel blocks the dialog.
+- **Provider CLIs** — **Claude Code**, **Codex**, **Gemini CLI**, and **Kimi
+  Code**. All four are probed via the system `PATH` and never bundled. At
+  least one must be installed and working before Add Project is enabled.
 
-You don't need all three providers. Install whichever you prefer:
+You don't need all four providers. Install whichever you prefer:
 
 | Provider | Install | Minimum CLI | Auth |
 |---|---|---|---|
 | **Claude Code** | from [claude.com/download](https://claude.com/download) | none pinned | `claude login` |
 | **Codex** | `brew install codex` | `0.128.0` | `codex login` |
 | **Gemini CLI** | `npm i -g @google/gemini-cli` | `0.11.0` | set `GEMINI_API_KEY` (a paid key from Google AI Studio) |
+| **Kimi Code** | official installer or `@moonshot-ai/kimi-code` | `0.27.0` | `kimi login` |
 
-After installing a provider CLI, quit and relaunch Specrails so the new `PATH` is picked up (see [Verifying manually](#verifying-manually)). For full provider setup, see the [Codex guide](../codex.md) and the [Gemini guide](../gemini.md).
+After installing a provider CLI, quit and relaunch Specrails so the new `PATH`
+is picked up. See [Kimi](../kimi.md), [Codex](../codex.md), or
+[Gemini](../gemini.md).
 
-When everything is in order, the panel collapses to a single line: **All required tools detected** (no per-tool rows, no version numbers). The detailed per-tool list — with versions, and including the Claude / Codex / Gemini provider rows (one row per provider you've installed) — only renders when something is **missing**, below its minimum version, or broken.
+When everything is in order, the panel collapses to **All required tools
+detected**. Detailed rows include each installed Claude/Codex/Gemini/Kimi CLI
+only when something is missing, too old, or broken.
 
 ## PATH resolution
 
@@ -113,7 +120,8 @@ This points you at the actual fix (remove the stale link) instead of sending you
       "git": "/usr/bin/git",
       "claude": "/opt/homebrew/bin/claude",
       "codex": null,
-      "gemini": null
+      "gemini": null,
+      "kimi": null
     },
     "nodeEnv": "production",
     "platform": "darwin"
@@ -129,7 +137,7 @@ In the **shipped desktop app** the first segments come from the bundled runtimes
 "loginShellStatus": "skipped"
 ```
 
-`whichResults` is keyed by command name for **every** prerequisite the panel checks, so it includes `claude`/`codex`/`gemini` (and `uv` when probed) on top of the four bundled tools. A `null` value means that command was not found on `PATH` — in the example above, only Claude Code is installed.
+`whichResults` is keyed by command name for **every** prerequisite the panel checks, so it includes `claude`/`codex`/`gemini`/`kimi` (and `uv` when probed) on top of the four bundled tools. A `null` value means that command was not found on `PATH` — in the example above, only Claude Code is installed.
 
 The install-instructions modal exposes a **Copy diagnostics** button that fetches this endpoint and copies the JSON to the clipboard for bug reports. The base endpoint (no `?diagnostic=1`) omits the `diagnostic` field, keeping the regular UI poll small.
 
@@ -144,6 +152,8 @@ After installing or reinstalling Node (or a provider CLI):
 
 ## Known limitations
 
-- **Provider requirement**: at least one provider CLI — Claude Code, Codex, or Gemini — must be installed and on `PATH`; otherwise Add Project stays disabled. (Gemini is enabled by default; to disable it set `SPECRAILS_GEMINI_BETA=0`.)
+- **Provider requirement**: at least one provider CLI — Claude Code, Codex,
+  Gemini, or Kimi — must be installed and on `PATH`; otherwise Add Project
+  stays disabled.
 - **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket; if another process holds the port, the server cannot start.
 - **Terminal panel**: the bottom terminal panel spawns `$SHELL -l -i`, so your `.zshrc` / `.bashrc` loads as it would in a normal login shell. Per-session shell selection is not yet exposed in the UI — set `SHELL` to override the default.

package/docs/platforms/windows.md

@@ -54,7 +54,12 @@ The desktop app ships its own **Node** and **Git** runtimes inside the bundle, s
 
 When the bundle is present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SPECRAILS_BUNDLED_RUNTIMES_PATH`, and the embedded server prepends the bundled `node`/`git` directories to the front of `PATH` so a system install can never shadow them. If a build ships **without** the runtimes (or a partial extraction occurs), the app does not dead-end — it falls back to discovering `node`/`git` on your system `PATH` (probed with Windows `where.exe`) instead of reporting a corrupted bundle.
 
-The **provider CLIs** — **Claude Code**, **Codex**, and **Gemini** — are **never bundled**. All three are probed via your system `PATH`, in every mode (using Windows `where.exe`). Install at least one before adding a project; the prerequisites panel blocks Add Project until one is usable. All three are enabled by default; you can roll one back with `SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0` (each disabled only by the exact string `0`). See the per-provider setup guides: [Codex](../codex.md) and [Gemini](../gemini.md).
+The **provider CLIs** — **Claude Code**, **Codex**, **Gemini**, and **Kimi
+Code** — are **never bundled**. All four are probed through the system `PATH`
+with `where.exe`; install at least one. Kimi 0.27+ requires Git for
+Windows/Git Bash and the npm distribution requires Node 22.19+, both
+user-managed. See [Kimi](../kimi.md), [Codex](../codex.md), and
+[Gemini](../gemini.md).
 
 ## Updates
 
@@ -64,11 +69,11 @@ Note that updates are delivered as the **MSI** (verified by an embedded **minisi
 
 ## Setup wizard
 
-When you add a project, the setup wizard runs `npx specrails-core@^4.8.0 init --from-config` under the hood (the full spawn is `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <tempPath>`, with the app writing a temporary `install-config.yaml`). The wizard has three steps — **Configure / Install / Done**.
+When you add a project, the setup wizard runs `npx specrails-core@^4.12.0 init --from-config` under the hood (the full spawn is `npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <tempPath>`, with the app writing a temporary `install-config.yaml`). The wizard has three steps — **Configure / Install / Done**.
 
 There are two distinct version floors to be aware of:
 
-- The app **installs** `specrails-core@^4.8.0` — the major-pinned range it ships (4.8.0 is the release that adds the Gemini provider target). The exact package spec is the `CORE_PACKAGE_SPEC` constant in `server/core-package.ts`, so it stays verifiable in one place. You need internet access at install time so `npx` can resolve it.
+- The app **installs** `specrails-core@^4.12.0` — the major-pinned range it ships (4.12.0 is the release that adds the Kimi provider target). The exact package spec is the `CORE_PACKAGE_SPEC` constant in `server/core-package.ts`, so it stays verifiable in one place. You need internet access at install time so `npx` can resolve it.
 - The minimum it will **accept** at runtime is **specrails-core ≥ 4.1.0** — the Node-native installer floor (`MIN_NODE_NATIVE_CORE_VERSION`). Anything below that is a legacy bash/python3 installer and cannot run on Windows without WSL.
 
 You can point the app at a local or linked build with the `SPECRAILS_CORE_BIN` environment variable (it overrides the `npx` spec above).
@@ -91,5 +96,5 @@ Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are pres
 
 - [macOS platform guide](./macos.md) — the equivalent guide for Apple Silicon.
 - [Getting started](../getting-started.md) — first run, adding a project, the dashboard tour.
-- [Codex provider setup](../codex.md) and [Gemini provider setup](../gemini.md) — installing and configuring the provider CLIs.
+- [Codex provider setup](../codex.md), [Gemini provider setup](../gemini.md), and [Kimi provider setup](../kimi.md) — installing and configuring the provider CLIs.
 - [CLI reference](../cli.md) — driving Specrails from the command line.

package/docs/running-pipelines.md

@@ -21,7 +21,10 @@ SpecsBoard (left)            Rails (right)
 
 A **rail** is an execution lane. Drag a spec card from the SpecsBoard onto a rail and press **▶ Play** to launch the pipeline. Rails let you organise and queue work into named lanes.
 
-Rails run on **Claude** by default. If your project has more than one provider installed, a per-rail engine selector lets you launch a rail on **Codex** or **Gemini** instead — see [Using Codex](codex.md) and [Using Gemini](gemini.md). Only the **Freestyle** loop is Claude-only; the standard Implement and Batch loops run on any installed provider.
+Rails default to the project's primary provider. If several are installed, a
+per-rail engine selector can launch on **Claude**, **Codex**, **Gemini**, or
+**Kimi** — see [Using Kimi](kimi.md). Implement and Batch run on every
+registered provider; Freestyle is offered by Claude and Kimi.
 
 > **One job at a time per project.** Each project has a single queue, so within a project only one rail job runs at a time; the rest queue behind it. Real parallelism is **across projects** — open two projects and their rails run independently. See [Running multiple rails](#running-multiple-rails).
 
@@ -33,7 +36,8 @@ Each rail has a header with:
 - **Spec list** — the IDs of the specs assigned to this rail. Drag in more, drag out to detach. You can also use the **Move to rail** popover from a spec card; it shows a status dot per rail so you don't push work onto a busy lane.
 - **Loop picker** — the **Loop** this rail runs: a built-in (`Implement`, `Batch`, or `Freestyle`) or one of your published custom loops. See [Loops](#loops).
 - **Profile picker** — which agent profile this rail uses. This only appears once the project has **at least one** profile (create them on the Agents page). When present, `No profile` runs the rail in legacy mode.
-- **Engine selector** — pick which installed provider (Claude, Codex, or Gemini) runs this rail. Only renders on projects with more than one provider installed.
+- **Engine selector** — pick which installed provider (Claude, Codex, Gemini,
+  or Kimi) runs this rail. It renders only for multi-provider projects.
 - **Play / Stop button** — start or cancel.
 
 ### Loops
@@ -44,7 +48,7 @@ A rail runs a **Loop**, picked in the rail header and persisted per rail. The th
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | One job covering all the specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. |
 | **Batch** | `/specrails:batch-implement` | One job that works through the rail's specs sequentially, in dependency-aware waves. |
-| **Freestyle** | (Freestyle) | Claude implements each spec autonomously, **bypassing** the OpenSpec pipeline. One independent job per spec. Claude only. |
+| **Freestyle** | (Freestyle) | A provider with native Freestyle capability implements each spec autonomously, bypassing the OpenSpec pipeline. Claude and Kimi support it. |
 
 Beyond the built-ins, the **Loops** section (left sidebar, above the project list) is a global, n8n-style **visual builder** shared across all your projects. A loop is a graph of typed steps:
 
@@ -55,6 +59,11 @@ Beyond the built-ins, the **Loops** section (left sidebar, above the project lis
 
 Each run is bounded by **max iterations**, a wall-clock **timeout**, and an optional **cost cap** (USD, checked between steps). The builder also has live validation, a dry-run preview (resolve every step's exact text without spawning), import/export to JSON, and copy/paste of steps across loops. **Fork** a built-in to start from a working graph, then **Publish** to make a loop selectable on any rail.
 
+Kimi runs built-in and custom loops whose graph contains AI/shell steps but no
+**Loop Decider**. A Decider's constrained `continue`/`stop` verdict is a
+pure-output action; Kimi 0.27 `-p` cannot enforce the required no-tools
+boundary, so Kimi + Decider is rejected before the loop starts.
+
 > Loop runs stream live in the Jobs view like any rail job — and the Job Detail view groups a loop's log **by step**: a live chip map of the graph on top, one collapsible section per step below, with follow mode tracking the running step. Provider/model/effort are governed by the **rail**, not the loop's steps.
 
 ### Pipeline phases
@@ -65,7 +74,8 @@ Each run is bounded by **max iterations**, a wall-clock **timeout**, and an opti
 Architect ──► Developer ──► Reviewer ──► Ship
 ```
 
-Each phase is a specialised agent invoked by the rail's engine (Claude, Codex, or Gemini) in your project's working directory:
+Each phase is a specialised role invoked by the rail's engine (Claude, Codex,
+Gemini, or Kimi) in an isolated project worktree:
 
 | Phase | Agent | What it does |
 |-------|-------|--------------|
@@ -80,13 +90,24 @@ In plain terms: the project's **agent profile** decides which AI agent handles e
 
 ### Freestyle
 
-`Freestyle` (mode value `freestyle` on the API — its original name) is a Claude-only loop that skips the Architect → Developer → Reviewer → Ship pipeline entirely. Instead of orchestrating the agent chain, it hands Claude a configurable pre-prompt plus the full spec text and lets it work autonomously with its native tools.
+`Freestyle` (mode value `freestyle` on the API) skips the Architect →
+Developer → Reviewer → Ship pipeline. It hands the selected Freestyle-capable
+provider a configurable pre-prompt plus the full spec and lets it work
+autonomously with native tools.
 
 - **One job per spec.** If the rail has three specs, `Freestyle` launches three independent jobs.
 - **Variable cost.** Because the run is open-ended, pressing Play opens a confirmation dialog before anything spawns.
-- **Model picker.** A per-rail control lets you pick **Haiku / Sonnet / Opus** (default Sonnet) for the Freestyle run.
-- **Claude only.** The Freestyle loop and its model picker are offered only when the rail's engine is Claude. Codex and Gemini rails can't run Freestyle, and agent profiles don't apply to Freestyle rails.
-- **Interactive by default.** Like every Claude job, a Freestyle run is a live session: chat with the running job and send follow-up prompts from the Job Detail composer. What's special about Freestyle is the ending — the session stays open until **you** click **Finalize** (other jobs wrap up on their own once a turn finishes with nothing queued). Can be disabled server-side via `SPECRAILS_INTERACTIVE_JOBS=false`.
+- **Model picker.** A per-rail control uses the selected provider's model
+  catalog. Kimi offers `k3`, `kimi-for-coding`, and
+  `kimi-for-coding-highspeed`; low/high/max effort appears only for K3.
+- **Capability-gated.** Claude and Kimi advertise Freestyle. Codex and Gemini
+  do not. Agent profiles do not apply to Freestyle rails.
+- **Transport-aware interaction.** Claude's persistent-stdin Freestyle run is
+  a live session and waits for **Finalize**. Kimi Freestyle is agentic too,
+  but `kimi -p` has no persistent stdin transport; it follows the owned
+  one-process lifecycle and later conversations resume through a new process
+  only after Kimi has emitted a session hint. Can be disabled server-side via
+  `SPECRAILS_INTERACTIVE_JOBS=false`.
 
 You can customise the Freestyle pre-prompt per project on the [Settings page](customizing.md#freestyle-pre-prompt).
 
@@ -123,7 +144,7 @@ Two panels sit above the streaming log:
 
 Below: the full streaming log with auto-scroll, search, and copy.
 
-**Talk to the running job.** Every Claude job (and every Claude AI step in a loop run) is an interactive session by default: a chat composer sits at the bottom of the Job Detail page — and of the job modal in mission mode — so you can ask the running agent a question or steer it mid-run. Messages sent while the model is streaming queue up and run next; the job keeps following its plan. The composer shows a live `N turns · $X` line summed from each completed turn's real usage (still no estimates). Most jobs finish on their own the moment a turn completes with nothing queued — a subtle **Wrap up now** ends them early; Freestyle jobs instead wait for your explicit **Finalize**. During a loop run your messages reach the currently running AI step (between steps the composer shows a short waiting state, and **Settle this step** advances the loop). Codex and Gemini jobs run one-shot as before. Server kill switch: `SPECRAILS_INTERACTIVE_JOBS=false`.
+**Talk to the running job.** Every Claude job (and every Claude AI step in a loop run) is an interactive session by default: a chat composer sits at the bottom of the Job Detail page — and of the job modal in mission mode — so you can ask the running agent a question or steer it mid-run. Messages sent while the model is streaming queue up and run next; the job keeps following its plan. The composer shows a live `N turns · $X` line summed from each completed turn's real usage (still no estimates). Most jobs finish on their own the moment a turn completes with nothing queued — a subtle **Wrap up now** ends them early; Freestyle jobs instead wait for your explicit **Finalize**. During a loop run your messages reach the currently running AI step (between steps the composer shows a short waiting state, and **Settle this step** advances the loop). Codex, Gemini, and Kimi rail processes do not expose Claude's persistent-stdin transport; Kimi chat surfaces resume a recorded session by spawning a new `kimi -p` process. Server kill switch: `SPECRAILS_INTERACTIVE_JOBS=false`.
 
 ### Cancelling a job
 
@@ -131,7 +152,11 @@ Click **Stop** on the rail header. The app sends `SIGTERM` to the subprocess, wa
 
 ### 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. Install the missing provider CLI — see [Using Codex](codex.md) or [Using Gemini](gemini.md) — then launch again. (Missing Claude or Codex returns a precise "*<provider> CLI not found*" message; missing Gemini surfaces a generic launch error today, but the result is the same — nothing spawns.)
+If you pick an engine whose CLI isn't installed on your machine, the launch
+fails fast instead of starting a broken job. Install the missing provider CLI
+— see [Using Codex](codex.md), [Using Gemini](gemini.md), or
+[Using Kimi](kimi.md) — then launch again. Kimi requires the external
+authenticated `kimi` 0.27+ executable; Desktop never starts a server for it.
 
 ### Diagnostic export
 
@@ -172,7 +197,8 @@ Pick the profile from the **rail header's profile dropdown**. It's preselected t
 
 The **`No profile`** option always exists — use it to run a rail exactly as it did pre-4.1.0. (The dropdown itself only appears once the project has at least one profile.)
 
-> **Profiles apply to Claude rails only.** When a rail's engine is Codex or Gemini, the run always uses legacy mode — any selected profile is ignored. Profiles are a Claude-specific feature.
+> **Profiles apply to providers that advertise role/profile execution.** Claude
+> and Kimi support them. Codex and Gemini currently run in legacy mode.
 
 ### Custom agents (Agent Studio)
 
@@ -208,6 +234,8 @@ Per-project bundled integrations. Click **Integrations** in the project's right
 
 Each plugin tile has:
 
+- **AI provider** — for multi-provider projects, selects the independent
+  Claude, Codex, or Kimi installation to inspect or change.
 - **Status** — `not installed`, `installed`, `orphan` (state file mentions it but `.mcp.json` doesn't), or `degraded` (verify failed).
 - **Preview install** — shows which `mcpServers` entries and agent fragments will land where, so you can sanity-check before clicking.
 - **Install** — applies the changes. Progress streams over the WebSocket (`plugin.install_progress` event).
@@ -218,7 +246,8 @@ Each plugin tile has:
 
 Before each rail spawn, the app:
 
-1. Resolves the project's installed plugins (parallel verify, per-plugin 2 s timeout).
+1. Resolves only the plugins installed for the rail's effective AI provider
+   (parallel verify, per-plugin 2 s timeout).
 2. Classifies them into `active` and `degraded`.
 3. Writes a per-job snapshot to `~/.specrails/projects/<slug>/jobs/<jobId>/plugins.json` (chmod 400).
 4. Injects two env vars into the subprocess: `SPECRAILS_PLUGINS_ACTIVE` (CSV) and `SPECRAILS_PLUGINS_SNAPSHOT` (file path).
@@ -230,6 +259,11 @@ Degraded plugins are **non-blocking** — the rail spawns anyway, but a `plugin.
 The app never wholesale rewrites these files:
 
 - `<project>/.mcp.json` — surgical merge per plugin.
+- `<project>/.kimi-code/mcp.json` — Kimi-native surgical MCP merge.
+- `<project>/CLAUDE.md`, `<project>/AGENTS.md`,
+  `<project>/GEMINI.md`, or `<project>/.kimi-code/AGENTS.md` —
+  provider-native managed instruction blocks. Provider-relative paths remain
+  independent unless two adapters explicitly declare the same path.
 - `<project>/.specrails/plugins/state.json` — install registry.
 - `<project>/.specrails/plugins/snapshots/<jobId>.json` — per-job snapshots.
 - `<project>/.claude/agents/custom-<plugin>.md` — optional fragment per plugin.

package/docs/terminal.md

@@ -32,7 +32,7 @@ You don't have to. You can keep using iTerm/Windows Terminal/Alacritty/whatever
 
 The panel header carries three one-click shortcuts:
 
-- **Open AI CLI** (✨ Sparkles) — spins up a fresh session and types the launch command for you. On a single-provider project it launches the project's provider CLI directly (`claude`, `codex`, or `gemini`); on a multi-provider project it opens a small picker so you choose which CLI to start.
+- **Open AI CLI** (✨ Sparkles) — spins up a fresh session and types the launch command for you. On a single-provider project it launches the project's provider CLI directly (`claude`, `codex`, `gemini`, or `kimi`); on a multi-provider project it opens a small picker so you choose which CLI to start. Kimi launches the CLI itself, not `kimi server`.
 - **Open in browser** (🌐 Globe) — opens the URL from the `browserShortcutUrl` setting (default `https://specrails.dev`). Right-click it to jump to the setting and change the URL.
 - **Paste quick script** (`</>`) — writes the snippet from the `quickScript` setting (which defaults to a personalised `echo "Wake up, <username> …"` reminder, editable in Settings) into the active session. Right-click it to edit the snippet in Settings. Disabled when there's no active terminal or the snippet is empty.