specrails-desktop 2.30.2 → 2.31.0

package/docs/internals/adding-a-provider.md

@@ -1,9 +1,9 @@
 # Adding a new AI provider to Specrails
 
-> Last verified against `main` (app 2.8.0), which ships **three** registered
-> providers: **Claude, Codex, and Gemini**. Gemini is the freshest worked
-> example — `server/providers/gemini-adapter.ts` is the cleanest single-file
-> template to copy.
+> Last verified with the Kimi provider change, which ships **four** registered
+> providers: **Claude, Codex, Gemini, and Kimi**. Kimi is the freshest worked
+> example — `server/providers/kimi-adapter.ts` demonstrates multi-event JSONL,
+> per-child environment overrides, native skill commands, and CLI-only resume.
 
 The app is provider-agnostic by design. Every manager that spawns an AI
 CLI consumes a `ProviderAdapter` rather than branching on a hardcoded
@@ -71,10 +71,11 @@ export const exampleAdapter: ProviderAdapter = {
 
 The `ProviderAdapter` interface is documented in
 `server/providers/types.ts`. Read the existing
-`server/providers/{claude,codex,gemini}-adapter.ts` for the patterns —
+`server/providers/{claude,codex,gemini,kimi}-adapter.ts` for the patterns —
 `SpawnAction` shapes per provider, `text-delta` event normalisation
-across native JSONL formats, etc. **`gemini-adapter.ts` is the newest and
-most representative end-to-end exemplar** to copy: it shows the optional
+across native JSONL formats, etc. **`kimi-adapter.ts` is the newest
+end-to-end exemplar** for prompt-mode providers; Gemini remains the example for
+the optional
 `prepareHeadlessSpawn` hook, `systemPromptArg: false` system-prompt folding
 (via the `GEMINI_SYSTEM_MD` env), native OTEL with `nativeCostUsd: false`,
 and a per-action `buildArgs` switch that throws defensively on the
@@ -231,7 +232,7 @@ Two paths, picked by your `nativeOtelEnv` capability flag:
   rail spawn and the CLI exports OTLP/JSON to the app's receiver natively. There
   is no `GEMINI_TELEMETRY_*` env var — Gemini honours the same `OTEL_*` vars as
   Claude.
-- **`nativeOtelEnv: false`** (Codex) ⇒ the synthetic OTEL bridge at
+- **`nativeOtelEnv: false`** (Codex, Kimi) ⇒ the synthetic OTEL bridge at
   `server/codex-otel-bridge.ts` fills the gap. It's provider-neutral despite its
   name — it consumes the canonical `AdapterEvent` stream. As long as your
   adapter's `parseStreamLine` emits `text-delta`, `tool-use`, `session-started`,
@@ -249,10 +250,11 @@ whenever `getAdapter(providerId).mcpRegistration === 'cli-add'`. The
 app-level `PluginManager` already threads `providerId` through every
 relevant method.
 
-For `mcpRegistration === 'project-json'` providers, the existing
-`.mcp.json` surgical-merge path applies — **but only if your CLI actually
-reads claude-style `.mcp.json`**. `project-json` really names that one
-mechanism, and Gemini is the proof it isn't universal: gemini-cli has
+For `mcpRegistration === 'project-json'` providers, the adapter's
+`projectMcpPath()` selects the JSON file for surgical merge: Claude uses
+`.mcp.json`, Kimi uses `.kimi-code/mcp.json`, and Gemini uses
+`.gemini/settings.json`. Never assume a CLI reads Claude's root `.mcp.json`.
+Gemini is the proof it isn't universal: gemini-cli has
 never read `.mcp.json` — its only MCP surface is `mcpServers` in
 `settings.json` (user scope `~/.gemini/`, project scope
 `<cwd>/.gemini/`), and an untrusted cwd suppresses MCP entirely (headless
@@ -260,16 +262,15 @@ runs exit 55 with `FatalUntrustedWorkspaceError`; the app injects
 `GEMINI_CLI_TRUST_WORKSPACE=true` per spawn). The desktop agent chat
 registers its MCP for gemini via `<agent-cwd>/.gemini/settings.json` +
 that trust env (`prepareAgentMcp` in `server/agent-mcp-config.ts`);
-the plugin `.mcp.json` merge path still runs for gemini rails but the
-server silently never loads there — a known deferred gap. Full facts +
-the gap table: [gemini-mcp-registration.md](gemini-mcp-registration.md).
-If your provider has its own config surface, mirror the gemini branch of
-`prepareAgentMcp` rather than assuming `.mcp.json` is enough.
+Full facts are in
+[gemini-mcp-registration.md](gemini-mcp-registration.md). If your provider has
+its own config surface, implement `projectMcpPath()` and mirror the relevant
+`prepareAgentMcp` branch rather than assuming `.mcp.json` is enough.
 
 ### 6. (If the binary needs a spawn-env quirk) add it to cli-prompt.ts
 
 Per-binary spawn quirks live in `server/util/cli-prompt.ts` — the spawn layer
-already special-cases `spawnClaude` / `spawnCodex` / `spawnGemini`, dispatched
+already special-cases `spawnClaude` / `spawnCodex` / `spawnGemini` / `spawnKimi`, dispatched
 by binary name. Gemini needed `GEMINI_CLI_TRUST_WORKSPACE=true` injected into
 every spawn (its "trusted folders" gate otherwise silently disables `--yolo`
 and blocks headless tool calls). If your CLI has an equivalent env that
@@ -281,13 +282,15 @@ providers need nothing here.
 Two distinct version concepts — don't conflate them:
 
 - **`minCliVersion`** is the **binary** floor surfaced by `detectInstalled`
-  (Claude = `null` / none pinned, Codex = `0.128.0`, Gemini = `0.11.0`). It
+  (Claude = `null` / none pinned, Codex = `0.128.0`, Gemini = `0.11.0`,
+  Kimi = `0.27.0`). It
   guards stream-format / flag availability for that one CLI.
-- **`specrails-core@^4.8.0`** (`CORE_PACKAGE_SPEC`, `server/core-package.ts`) is
+- **`specrails-core@^4.12.0`** (`CORE_PACKAGE_SPEC`, `server/core-package.ts`) is
   the single shared package floor the app installs/probes for **all** providers.
   It matters when your provider's **rails** rely on core-side scaffolding: core
   must emit the provider's command/agent/skill tree (e.g. Gemini needed core
-  `4.8.0` to ship the `.gemini/` commands + `sr-*` agents). The desktop adapter
+  `4.8.0` to ship the `.gemini/` commands + `sr-*` agents, while Kimi requires
+  4.12.0 for `.kimi-code/`). The desktop adapter
   alone covers spec / explore / quick; rails need the matching core target.
 
 ## Known gotchas
@@ -298,13 +301,14 @@ Two distinct version concepts — don't conflate them:
   `provider === 'claude'`; everything else falls into the non-claude
   (codex-shaped) branch. A new provider hitting that path would be
   silently parsed as codex — migrate the callsite or extend the branch.
-- **Rail slash-command translation is provider-specific.** In
-  `server/queue-manager.ts` the rail prompt builder rewrites
-  `/specrails:<name>` → `$<name>` for codex (so codex picks up the
-  matching `.codex/skills/<name>/SKILL.md`), while claude passes the
-  command verbatim. A new adapter falls through to the claude branch
-  (verbatim). If your CLI needs a different invocation syntax, add a
-  branch keyed on a capability, not on the provider id.
+- **Rail command translation is provider-specific.** Implement
+  `formatCoreCommand()` on the adapter. Codex maps `/specrails:<name>` to a
+  `$<name>` skill; Claude passes its native slash command unchanged. Kimi is
+  different in headless mode: its TUI/ACP intercept `/skill:<name>`, but
+  `kimi -p` does not. Its hook therefore loads the installed
+  `.kimi-code/skills/<name>/SKILL.md`, expands arguments, and returns the
+  materialized activation prompt. Always pass the execution artifact `cwd` to
+  this hook and fail before spawn when the skill cannot be resolved.
 
 ## Drop a fixture set
 

package/docs/internals/api-reference.md

@@ -4,7 +4,11 @@ REST and WebSocket endpoints exposed by the app server. The server binds to `127
 
 > **New here?** This page is the contract the desktop UI, the CLI, and the mobile gateway all speak to the local server. **You normally never call these endpoints directly — the app does it for you.** Read on only if you are scripting against the server, writing an integration, or debugging. Everything is local-only: there is no cloud API.
 
-The app speaks to three interchangeable AI provider CLIs — **Claude, Codex, and Gemini** — all enabled by default. Endpoints that accept a provider value (`provider` / `aiEngine`) take any of `claude`, `codex`, or `gemini`, validated against the providers the project actually installed. See the [Codex guide](../codex.md) and the [Gemini guide](../gemini.md) for provider specifics.
+The app registers four AI provider CLIs — **Claude, Codex, Gemini, and Kimi**
+— all enabled by default. Endpoints that accept `provider` / `aiEngine` take
+`claude`, `codex`, `gemini`, or `kimi`, validate project membership, then
+enforce the requested surface's adapter capabilities. See the
+[Kimi guide](../kimi.md) for its exact matrix.
 
 ## Authentication
 
@@ -59,7 +63,7 @@ A non-localhost `Origin` header is rejected by the CORS middleware with `403 For
 | Method | Path | Notes |
 |--------|------|-------|
 | `GET` | `/projects` | List registered projects |
-| `POST` | `/projects` | Register a project. Body `{ path, name?, provider?, providers? }`. Each provider value is one of `claude`, `codex`, `gemini` (registry-validated). `providers: string[]` enables a multi-provider project (first entry = primary/default); legacy single `provider` still honoured; omit both to default to `["claude"]`. 409 if the path is already registered. 400 if a provider is unknown, or if a disabled provider is selected: `codex` when `SPECRAILS_CODEX_BETA=0`, `gemini` when `SPECRAILS_GEMINI_BETA=0` (both default-enabled) |
+| `POST` | `/projects` | Register a project. Body `{ path, name?, provider?, providers? }`. Each provider value is one of `claude`, `codex`, `gemini`, `kimi` (registry-validated). `providers: string[]` enables a multi-provider project (first entry = primary/default); legacy single `provider` still honoured; omit both to default to `["claude"]`. 409 if the path is already registered or Kimi fails its executable/version/Core-target checks. 400 if a provider is unknown, or if a disabled provider is selected: `codex` when `SPECRAILS_CODEX_BETA=0`, `gemini` when `SPECRAILS_GEMINI_BETA=0` (both default-enabled). Kimi has no beta flag: it requires a usable `kimi` CLI ≥ 0.27.0 and a Core build that advertises the Kimi target. Kimi 0.27 has no safe non-billing authentication probe, so login/model configuration is confirmed by the first real turn |
 | `DELETE` | `/projects/:id` | Unregister (does not delete the project directory) |
 | `GET` | `/resolve?path=…` | Find a project by **exact** canonical filesystem path. No parent-directory walking — a subdirectory returns 404 |
 
@@ -80,8 +84,8 @@ Example — register a project that uses both Claude and Gemini:
 | Method | Path | Notes |
 |--------|------|-------|
 | `GET` | `/state` | `{ projects, projectCount, …todayStats }` (today's cross-project cost/run aggregates spread into the response) |
-| `GET` | `/cli-status` | Detected AI CLI provider + version (`{ provider, version }`), e.g. `claude`, `codex`, or `gemini` — runs `<binary> --version`. Registry-driven |
-| `GET` | `/available-providers` | Provider catalogue used by the setup wizard. Registry-driven map (`{ claude, codex, gemini, tiers }`) reporting which CLIs are installed. Codex/Gemini are surfaced unless forced off by `SPECRAILS_CODEX_BETA=0` / `SPECRAILS_GEMINI_BETA=0` (both enabled by default) |
+| `GET` | `/cli-status` | Detected AI CLI provider + version (`{ provider, version }`), e.g. `claude`, `codex`, `gemini`, or `kimi` — runs the registered adapter's version probe. Registry-driven |
+| `GET` | `/available-providers` | Provider catalogue used by the setup wizard. Registry-driven map (`{ claude, codex, gemini, kimi, tiers, providerIssues, launchDescriptors }`) reporting which CLIs are usable. Codex/Gemini are surfaced unless forced off by `SPECRAILS_CODEX_BETA=0` / `SPECRAILS_GEMINI_BETA=0` (both enabled by default). Kimi is reported unavailable, with a machine-readable `providerIssues.kimi`, when the CLI is missing/unusable, is older than 0.27.0, or the installed Core lacks the Kimi target. The bounded readiness probe is intentionally non-billing and cannot prove account authentication; a login/configuration problem is surfaced by the first model turn. `launchDescriptors` exposes each external CLI command; the app does not bundle a Kimi daemon/server |
 | `GET` | `/core-compat` | specrails-core version compatibility probe |
 | `GET` | `/setup-prerequisites` | Tool checks (`node`/`npm`/`npx`/`git`, optionally `uv`). Add `?diagnostic=1` to nest a `diagnostic` object: `{ pathSegments, pathSources, loginShellStatus, whichResults, nodeEnv, platform }` |
 
@@ -199,7 +203,11 @@ Example — queue a command on a specific provider:
 | `POST` | `/jobs/:id/finalize` | Finalize a running interactive job (SIGTERM the resident child; final totals + terminal status are stamped when it closes). For a loop run this settles the **current step** and the loop advances. `202` scheduled, `403` interactive jobs disabled, `409` not an active interactive session |
 | `GET` | `/jobs/:jobId/diagnostic` | Stream a diagnostic ZIP (telemetry + profile + plugins snapshots) |
 
-The two interactive endpoints back the in-job chat that is **on by default for every Claude job** — QueueManager jobs (implement / batch / Freestyle / custom commands) and the loop engine's claude ai-steps alike. Two settle modes: Freestyle/freestyle jobs idle until an explicit finalize (`'finalize'`); everything else settles itself on quiescence (`'auto'` — a turn result with nothing queued), where finalize acts as "wrap up now" / "settle this step". Providers without persistent stdin (Codex, Gemini) run one-shot as before and 409 here. Both endpoints 403 when the server has `SPECRAILS_INTERACTIVE_JOBS=false`. As-built detail: [interactive-jobs.md](interactive-jobs.md).
+The two interactive endpoints back Claude's persistent-stdin in-job chat.
+Providers without persistent stdin (Codex, Gemini, and Kimi) run one-shot and
+return 409 here; Kimi chat surfaces resume via a new `kimi --session=<id> -p` child after
+a successful resume hint. Both endpoints return 403 when
+`SPECRAILS_INTERACTIVE_JOBS=false`.
 
 Example — fetch one job:
 
@@ -258,7 +266,8 @@ Example — the Analytics dashboard payload (abridged):
 }
 ```
 
-Cost is **provider-billed and exact for Claude**; for Codex and Gemini it is **estimated from a rate card** (those CLIs do not report a native cost).
+Cost is provider-billed for Claude and estimated for Codex/Gemini. Kimi
+provides no authoritative token/USD envelope, so those values remain null.
 
 ### Budget
 
@@ -280,7 +289,7 @@ Cost is **provider-billed and exact for Claude**; for Codex and Gemini it is **e
 | `POST` | `/tickets/save-as-draft` | Persist an Explore conversation as a draft (idempotent on `conversationId`) |
 | `POST` | `/tickets/from-draft` | Commit a draft (flip-in-place) or insert a new ticket |
 | `POST` | `/tickets/from-prompt` | Create a ticket directly from a prompt |
-| `POST` | `/tickets/:id/contract-refine` | Retry Contract Refine for an existing ticket. `202` scheduled, `404` unknown ticket, `409` when: the project is Codex (`contract_refine_unsupported_for_codex` — Contract Refine is Claude-only), the kill switch is active (`feature_disabled_by_env`), or the ticket has no origin conversation |
+| `POST` | `/tickets/:id/contract-refine` | Retry Contract Refine for an existing ticket. `202` scheduled, `404` unknown ticket, `409` when the effective provider cannot enforce the required tool policy (`contract_refine_unsupported_for_<provider>`; this includes Kimi), the kill switch is active (`feature_disabled_by_env`), or the ticket has no origin conversation. Kimi is rejected before spawn or mutation |
 | `POST` | `/tickets/:id/smash` | SMASH an epic into sub-specs |
 | `POST` | `/tickets/:id/smash/undo` | Undo a SMASH operation |
 | `DELETE` | `/tickets/:id/children` | Delete all children of an epic |
@@ -315,7 +324,7 @@ The setup wizard is a three-step flow (Configure / Install / Done). The `enrich/
 | Method | Path | Notes |
 |--------|------|-------|
 | `POST` | `/setup/install-config` | Write `.specrails/install-config.yaml` to the project |
-| `POST` | `/setup/install` | Run `npx specrails-core init --from-config <file>` (the pinned core release — currently `specrails-core@^4.8.0` — is resolved by SetupManager, overridable via `SPECRAILS_CORE_BIN`) |
+| `POST` | `/setup/install` | Run `npx specrails-core init --from-config <file>` (the pinned core release — currently `specrails-core@^4.12.0` — is resolved by SetupManager, overridable via `SPECRAILS_CORE_BIN`) |
 | `POST` | `/setup/start` | Legacy setup-chat session start |
 | `POST` | `/setup/message` | Legacy setup-chat turn |
 | `POST` | `/enrich/start` | Legacy AI-enrich session start |
@@ -435,16 +444,25 @@ A non-developer-friendly file tree + Monaco viewer with plain-language AI summar
 | `PUT` | `/:railIndex/profile` | Set the rail's default profile |
 | `PUT` | `/:railIndex/engine` | Set the rail's AI engine override. Body `{ aiEngine }` (string — one of the project's providers — or `null` to clear) |
 | `PUT` | `/:railIndex/name` | Set the rail's display name. Body `{ name }` (string or `null` to clear back to the default label); 400 if longer than 60 characters |
-| `POST` | `/:railIndex/launch` | Launch the rail. Body `{ mode?, loopId?, profileName?, aiEngine?, model?, reasoning_effort?, originConversationId?, originSurface?, interactive? }`. `mode` is `implement` / `batch-implement` / `freestyle` / `loop`; a factory `loopId` (`factory:implement` etc.) maps to its canonical rail mode, and a **bare mode with no `loopId`** (MCP / mobile / direct REST) derives the matching factory loop when Loops are enabled, so every launch door gets the same isolation + ask-first PR flow as the dashboard. `model` (haiku/sonnet/opus/fable) applies to freestyle only. The in-job chat is **on by default for every Claude job** — the `interactive` param is accepted and **ignored** (wire compat; the spawn-time gate decides). Returns `202 { jobId, railIndex, mode }`; **`503`** when the Claude or Codex CLI binary is not found (a missing Gemini/other binary surfaces as `500`) |
+| `POST` | `/:railIndex/launch` | Launch the rail. Body `{ mode?, loopId?, profileName?, aiEngine?, model?, reasoning_effort?, originConversationId?, originSurface?, interactive? }`. `mode` is `implement` / `batch-implement` / `freestyle` / `loop`; a factory `loopId` maps to its canonical rail mode. `model` and `reasoning_effort` are validated against the effective adapter/model (Kimi effort is K3-only). Kimi + a loop containing a Decider returns a capability error before the first step. Claude alone advertises persistent in-job stdin; `interactive` remains wire-compatible. Returns `202 { jobId, railIndex, mode }`; a missing provider CLI fails before a job starts. |
 | `POST` | `/:railIndex/stop` | Stop the rail's running job (cancels every job the rail registered) |
 
 ---
 
 ## `/api/projects/:projectId/profiles/*`
 
-Gated by `SPECRAILS_AGENTS_SECTION !== 'false'`. Rails force legacy (no-profile) mode whenever the chosen engine is not Claude, and the Agents section is hidden in multi-provider projects; profile env-injection itself works for any provider whose adapter advertises `profileEnvSupport`.
+Gated by `SPECRAILS_AGENTS_SECTION !== 'false'`. Profiles are provider-scoped;
+Claude and Kimi advertise profile execution, while Codex and Gemini force
+legacy mode. CRUD requests may carry the effective provider so same-named
+Claude/Kimi profiles do not collide.
 
-> **Provider capability notes.** A few behaviours are not the same across all three providers: **Contract Refine** is Claude-only; **rails force no-profile mode** for any non-Claude engine; **Freestyle rails** are Claude-only; the **Serena plugin** (and other `project-json` plugins) work for Claude and Gemini but are filtered out for Codex; and **cost is exact only for Claude** (estimated from a rate card for Codex and Gemini). See the [Codex guide](../codex.md) and [Gemini guide](../gemini.md).
+> **Provider capability notes.** Claude and Kimi support provider-scoped
+> profiles and Freestyle; integration state/health is also provider-scoped.
+> Kimi agentic surfaces are available, but pure-output/read-only actions
+> (Quick Spec, AI Edit, Contract Refine, SMASH/Re-SMASH, Project Builder
+> generation, Loop Decider, Code Explorer AI, and Agent Studio automation)
+> reject Kimi before spawn. Kimi tokens/USD cost remain null. See the
+> [Kimi guide](../kimi.md).
 
 ### Profile CRUD
 
@@ -498,10 +516,15 @@ Gated by `SPECRAILS_AGENTS_SECTION !== 'false'`. Rails force legacy (no-profile)
 
 Gated by `SPECRAILS_PLUGINS_SECTION !== 'false'`.
 
+Every route accepts an optional provider target. Read and delete routes use
+`?provider=<id>`; mutation routes accept `{ "provider": "<id>" }`. The value
+must belong to the project's configured `providers`; omission preserves the
+legacy behaviour and targets the primary `project.provider`.
+
 | Method | Path | Notes |
 |--------|------|-------|
 | `GET` | `/` | List bundled plugins with installed/orphan/degraded state |
-| `GET` | `/:name/preview-install` | Diff of what would be added to `.mcp.json` and `agents/` |
+| `GET` | `/:name/preview-install` | Provider-native MCP/instructions diff |
 | `POST` | `/:name/install` | Install (streams progress over WS) |
 | `DELETE` | `/:name` | Uninstall or remove an orphan |
 | `POST` | `/:name/activate` | Activate (post-install) |
@@ -729,7 +752,8 @@ The app uses standard HTTP status codes. Notable conventions:
 - `413` — payload too large (code-explorer edit over the 2 MB cap)
 - `415` — unsupported media type (code-explorer edit of binary content)
 - `500` — unhandled exception (logged to stdout)
-- `503` — the Claude or Codex CLI binary was not found when launching a rail job (a missing Gemini/other-provider binary falls through to `500`)
+- `503` / launch error — the selected provider CLI was not found; no job is
+  allowed to start with a missing executable
 
 Error responses are `{ "error": "<message>" }`.
 

package/docs/internals/architecture.md

@@ -248,7 +248,7 @@ App-level messages (no `projectId`) are processed by all handlers.
 
 ## Process spawning and concurrency
 
-`QueueManager` and `ChatManager` spawn the project's provider CLI (`claude`, `codex`, or `gemini`) as subprocesses, always with `cwd` set so the process runs in the correct directory. The exact binary and argv are chosen by the resolved `ProviderAdapter` — managers never branch on the provider id (see [Multi-provider adapters](#feature-subsystems)).
+`QueueManager` and `ChatManager` spawn the project's provider CLI (`claude`, `codex`, `gemini`, or `kimi`) as subprocesses, always with `cwd` set so the process runs in the correct directory. The exact binary and argv are chosen by the resolved `ProviderAdapter` — managers never branch on the provider id (see [Multi-provider adapters](#feature-subsystems)).
 
 - **Within a project, jobs run strictly one at a time.** Each `ProjectContext` has exactly one `QueueManager` with a single `_activeJobId`; `_drainQueue()` early-returns while a job is active, so the next rail job queues behind the current one.
 - **Parallelism is across projects only** — each project has its own `QueueManager`, so jobs in different projects run simultaneously. There is no "max concurrent jobs" setting; the only automatic queue-pause is budget-based (daily budget / per-job cost alert).
@@ -264,9 +264,9 @@ The app is more than the job pipeline. Each subsystem owns its modules; this is
 
 | Subsystem | Server modules | Notes |
 |-----------|---------------|-------|
-| **Multi-provider adapters** | `server/providers/{types,claude-adapter,codex-adapter,gemini-adapter,registry,index}.ts`, `server/provider-selection.ts` | **Three first-class providers — Claude, Codex, and Gemini — all enabled by default** behind a `ProviderAdapter` contract. Claude has full native support (native cost + native OTEL + `--system-prompt`); Codex (`≥ 0.128.0`) has estimated cost and OTEL synthesized by the app; Gemini (`≥ 0.11.0`) has estimated cost but **native OTEL** (it honours the standard `OTEL_*` env vars QueueManager injects — no synthetic bridge), folds its system prompt into `GEMINI.md`, uses `project-json` MCP registration, defaults to `gemini-3.5-flash`, and uniquely implements the optional `prepareHeadlessSpawn()` hook to pre-acknowledge subagents for headless rail spawns. A project can install any subset; `providers[]` is a JSON column, the first entry is primary. Per-invocation provider is late-bound. Provider availability is gated by `SPECRAILS_CODEX_BETA` / `SPECRAILS_GEMINI_BETA` (set either to `0` to disable; both default-enabled, see [`configuration.md`](configuration.md)). See [`adding-a-provider.md`](adding-a-provider.md), [`../codex.md`](../codex.md), and [`../gemini.md`](../gemini.md). |
+| **Multi-provider adapters** | `server/providers/{types,claude-adapter,codex-adapter,gemini-adapter,kimi-adapter,registry,index}.ts`, `server/provider-selection.ts` | **Four first-class providers — Claude, Codex, Gemini, and Kimi — enabled by default** behind a `ProviderAdapter` contract. Claude reports native cost and supports persistent stdin; Codex (`≥ 0.128.0`) and Gemini (`≥ 0.11.0`) expose estimated usage; Kimi (`≥ 0.27.0`) runs CLI-only prompt-mode JSONL, resumes through terminal hints, uses `.kimi-code` skills/MCP, and leaves absent cost/tokens unavailable. A project can install any subset; `providers[]` is a JSON column, the first entry is primary. Per-invocation provider is late-bound. Provider availability is gated by executable detection, Core target compatibility, and the existing Codex/Gemini emergency switches. See [`adding-a-provider.md`](adding-a-provider.md), [`../codex.md`](../codex.md), [`../gemini.md`](../gemini.md), and [`../kimi.md`](../kimi.md). |
 | **Spending analytics** | `server/spending.ts`, `server/ai-invocations.ts`, `server/pricing.ts` | `recordInvocation` writes an `ai_invocations` row per AI CLI call across six surfaces (`job`, `quick-spec`, `explore-spec`, `ai-edit`, `smash`, `file-summary`); powers the Analytics page and `spending.invalidated`. |
-| **Agent profiles** | `server/profile-manager.ts`, `server/profiles-router.ts` | Declarative JSON in `.specrails/profiles/*.json`, snapshot-per-job, `SPECRAILS_PROFILE_PATH` env injection. Requires `specrails-core ≥ 4.1.0` **in the project** (distinct from the app-wide install floor of `^4.8.0` — see [Setup wizard flow](#setup-wizard-flow)). Claude-only: the rails router force-nulls the profile for any non-Claude engine. |
+| **Agent profiles** | `server/profile-manager.ts`, `server/profiles-router.ts` | Declarative JSON in `.specrails/profiles/*.json`, snapshot-per-job, `SPECRAILS_PROFILE_PATH` env injection. Requires `specrails-core ≥ 4.1.0` in general and the Core 4.12 Kimi target for Kimi roles (the app-wide install floor is `^4.12.0`). Claude and Kimi advertise profile support; other adapters force legacy/no-profile mode. |
 | **Plugins (Integrations)** | `server/plugin-manager.ts`, `server/plugins/` | Bundled-only, MCP-based, additivity invariant, surgical `.mcp.json` merge, `plugin.*` WS events. Serena ships today. |
 | **Terminal panel** | `server/terminal-manager.ts` | `node-pty` sessions over the dedicated `/ws/terminal/:id` socket, OSC shell-integration marks. See [`../terminal.md`](../terminal.md). |
 | **Code explorer** | `server/code-explorer-router.ts`, `server/file-provenance.ts`, `server/file-summary-manager.ts` | A non-developer-friendly file tree + Monaco viewer with plain-language AI summaries and *touched-by-AI* provenance chips per ticket/job, plus opt-in in-app editing of existing files (overwrite-only via `PUT /file` — no create/rename; refuses binaries `415`, enforces a 2 MB cap `413`, `404` on a missing path, respects deny-list/`.gitignore`). |
@@ -285,7 +285,7 @@ Most client feature sections are gated by VITE flags, and they share one polarit
 When a project is added without specrails-core, the setup wizard runs. The client renders a **3-step** indicator: **Configure → Install → Done**.
 
 1. **Configure** — confirm path and pick provider(s) and model presets. (Multi-provider projects get one Configure step per provider.)
-2. **Install** — the app writes `.specrails/install-config.yaml` and runs `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <tempPath>`, streaming the log. The package spec is the constant `CORE_PACKAGE_SPEC` — a deliberately pinned major range (the floor is `4.8.0`, the release that ships the Gemini provider target), so a future core `5.x` doesn't auto-land. Override the binary locally with `SPECRAILS_CORE_BIN`. For multi-provider projects each provider's install runs sequentially.
+2. **Install** — the app writes `.specrails/install-config.yaml` and runs `npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <tempPath>`, streaming the log. The package spec is the constant `CORE_PACKAGE_SPEC` — a deliberately pinned major range (the floor is `4.12.0`, the release that ships the Kimi provider target), so a future core `5.x` doesn't auto-land. Override the binary locally with `SPECRAILS_CORE_BIN`. For multi-provider projects each provider's install runs sequentially.
 3. **Done** — per-provider completion summary.
 
 `SetupManager` (server) owns wizard state; `DesktopProvider` (client) tracks which projects are in setup via `setupProjectIds`. The wizard does spawn a real AI CLI for the `/setup` chat, but that spawn is deliberately left uninstrumented (it writes no `ai_invocations` row).
@@ -340,6 +340,6 @@ macOS desktop builds are signed + notarized. Windows builds (x64 and arm64) ship
 - [Configuration](configuration.md) — env vars, feature flags, app/project settings
 - [Agent profiles](profiles.md) — profile schema, resolution order, snapshot-per-job
 - [Adding a provider](adding-a-provider.md) — the `ProviderAdapter` contract
-- [Codex](../codex.md) / [Gemini](../gemini.md) — per-provider user guides
+- [Codex](../codex.md) / [Gemini](../gemini.md) / [Kimi](../kimi.md) — per-provider user guides
 - [OpenSpec workflow](openspec-workflow.md) — the spec-driven change lifecycle
 - [Operations runbook](operations-runbook.md) — running, upgrading, and recovering the app

package/docs/internals/bundled-framework-build-plan.md

@@ -145,7 +145,7 @@ Para el caso standalone, el framework viene del propio paquete npm de core (no d
 ### 4.1 Bundle de templates en la app (espeja el patrón runtimes **verbatim**)
 
 - **`tauri.conf.json`**: añadir `"framework/**/*"` a `bundle.resources` (junto a `"runtimes/**/*"`, hoy en línea 46). Forma glob para preservar la estructura anidada.
-- **CI (`desktop-release.yml`)**: paso que ensambla `src-tauri/framework/` antes de `tauri build` — copia `templates/**`, `commands/{enrich,doctor}.md`, y genera los providerDir materializados (claude/codex/gemini) + `setup-templates/`. Es el mismo patrón que ensambla `runtimes/`. `src-tauri/framework/` gitignored con `.gitkeep`.
+- **CI (`desktop-release.yml`)**: paso que ensambla `src-tauri/framework/` antes de `tauri build` — copia `templates/**`, `commands/{enrich,doctor}.md`, y genera los providerDir materializados (claude/codex/gemini/kimi) + `setup-templates/`. Es el mismo patrón que ensambla `runtimes/`. `src-tauri/framework/` gitignored con `.gitkeep`.
 - **`scripts/build-sidecar.mjs`**: si algún asset del framework debe resolverse en filesystem real (no dentro del snapshot pkg), copiarlo igual que `node-pty`. La mayoría son ficheros de texto estáticos → bajo riesgo (ver §9).
 - **`lib.rs`** (espejo de líneas 181-215): resolver `<resource_dir>/framework`, gate por existencia (`framework/.../claude/agents` existe y no vacío), y exportar `SPECRAILS_BUNDLED_FRAMEWORK_PATH` al sidecar. **Existence-gated** como los runtimes: si no hay framework empaquetado → fallback al `npx` legacy (no dead-end).
 
@@ -154,7 +154,7 @@ Para el caso standalone, el framework viene del propio paquete npm de core (no d
 - `materialize()`: copia `SPECRAILS_BUNDLED_FRAMEWORK_PATH` → `~/.specrails/framework/<version>/` si esa versión no existe. Idempotente (skip si manifest hash coincide).
 - `swapCurrent(version)`: `renameSync` atómico de `~/.specrails/framework/current` (reusa `atomicWrite`/rename de artifact-registry.ts:213-227). Crea `current.tmp` → rename.
 - `versionCheck()`: en **first-run** y **post-update**, compara la versión bundleada con `current` → materializa + swap si difiere.
-- Multi-provider: materializa por provider; el swap de `current` cambia **todos los providers a la vez** (un solo `current` por versión que contiene los 3 providerDirs).
+- Multi-provider: materializa por provider; el swap de `current` cambia **todos los providers a la vez** (un solo `current` por versión que contiene los 4 providerDirs).
 
 ### 4.3 Extender `ensureWorkspace` para enlazar el framework
 
@@ -261,4 +261,4 @@ Cada fase independientemente testeable + verde, con gates de cobertura (**80% se
 - **Framework PER PROVIDER**: `.claude/.codex/.gemini` difieren (path rewrites, frontmatter, ports de codex skills). `<version>/` sub-keyeado por provider; el swap de `current` cambia todos los providers juntos.
 - **`codex-config.toml MODEL_NAME`** hardcodeado (scaffold.ts:1091): si la selección de modelo se vuelve per-project, la copia compartida de codex necesitaría un overlay, no un link raw. **Hoy**: constante, compartible.
 - **Windows copy fallback**: la optimización "un swap actualiza todos" no aplica en copy → update O(proyectos). Aceptable v1.
-- **`setup-templates/` (input de enrich)** hoy se copia per-project (scaffold.ts:299). Al compartirse, `/specrails:enrich` debe leerlo del framework dir, no del workspace. **Validar la resolución de rutas de enrich antes de reubicarlo** (Fase 2).
+- **`setup-templates/` (input de enrich)** hoy se copia per-project (scaffold.ts:299). Al compartirse, `/specrails:enrich` debe leerlo del framework dir, no del workspace. **Validar la resolución de rutas de enrich antes de reubicarlo** (Fase 2).

package/docs/internals/code-explorer-story.md

@@ -4,6 +4,10 @@
 > covers the per-file **construction story** — the narrative layer that tells a
 > non-developer, for any file, HOW it was built: which specs intervened and what
 > each one contributed.
+>
+> Kimi 0.27 `-p` does not advertise an enforceable read-only tool policy.
+> `FileStoryManager.explain` and file-summary generation therefore reject Kimi
+> before spawn. Deterministic provenance/stats/log views remain provider-neutral.
 
 ## Problem
 

package/docs/internals/configuration.md

@@ -4,13 +4,16 @@ Reference for configuring specrails-desktop: app-wide settings, per-project sett
 
 Everything here is verified against `main`. The app server binds to `127.0.0.1` only and rejects any non-localhost origin, so all of this is local-first by design.
 
-> **Providers at a glance.** A project can run **Claude, Codex, Gemini, or any combination** of them. All three are enabled by default and are chosen when you add the project (see [Project settings](#project-settings)). Each has its own default model, resolved at spawn time:
+> **Providers at a glance.** A project can run **Claude, Codex, Gemini, Kimi,
+> or any compatible combination**. All four are enabled by default and chosen
+> when you add the project. Each has its own adapter default:
 >
 > | Provider | CLI binary | Default model | Emergency rollback |
 > |----------|-----------|---------------|--------------------|
 > | Claude Code | `claude` | `sonnet` | — |
 > | Codex CLI | `codex` | `gpt-5.5` | `SPECRAILS_CODEX_BETA=0` |
 > | Gemini CLI | `gemini` | `gemini-3.5-flash` | `SPECRAILS_GEMINI_BETA=0` |
+> | Kimi Code | `kimi` | `k3` | — |
 >
 > The provider set is **immutable after the project is created**.
 
@@ -52,7 +55,9 @@ The Global Settings page is organised into the sections below (it also surfaces
 | **Code section** | Plain-language file-summary language (`en` / `es`) and the monthly summary budget cap. | `summary_language` = `en`, `summary_monthly_budget_usd` = `5.00` |
 | **Terminal Panel** | App-wide defaults for the integrated terminal (font, render mode, copy-on-select, shell integration, image rendering, long-command threshold). | `terminal.*` keys |
 
-> There is **no** "Claude model", "Max concurrent jobs", "Job timeout", or "Authentication token" app setting. Within a project, jobs run one at a time (see [Architecture](architecture.md)); the only automatic queue pause is budget-based. The default model is each provider's adapter default (e.g. `sonnet` for Claude, `gpt-5.5` for Codex, `gemini-3.5-flash` for Gemini), resolved at spawn time — it is not a stored setting.
+> There is **no** global provider-model setting. The default is the adapter
+> default (`sonnet`, `gpt-5.5`, `gemini-3.5-flash`, or Kimi `k3`) resolved at
+> spawn time. Kimi low/high/max effort is valid only for K3.
 
 **Port is not a live setting.** `desktop_settings` does store a `port` value, but it is display-only. The port the server actually binds is taken from the `--port` argv (default `4200`); changing the stored value does not rebind a running server. Set the port with `--port <n>` on `specrails-desktop start`.
 
@@ -66,11 +71,14 @@ Project settings apply to a single project. Open them from the project's **Setti
 |---------|------------------|
 | **Pipeline Telemetry** | Opt-in toggle that injects OpenTelemetry env vars into pipeline job spawns so they emit OTLP signals back to the app. Off by default. |
 | **Rail Pre-prompt** | Text prepended to every rail launch for this project. |
-| **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (the Claude-only autonomous rail mode). |
+| **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (Claude and Kimi advertise this autonomous rail mode). |
 | **Budget** | Per-project daily spend cap (with queue auto-pause) and a per-job cost alert threshold. |
 | **Terminal Settings** | Per-project overrides for the terminal panel defaults (project override → app default → built-in). |
 
-> The project's **provider(s)** — **Claude, Codex, Gemini, or any combination** — are chosen when you add the project and are **immutable after creation**. All three are enabled by default; there is no provider switch in Project Settings. There is also **no** Name edit, Path row, or model-override field on this page. See [Customising the app](../customizing.md) for how to disable a provider app-wide via its rollback gate.
+> The project's **provider(s)** — **Claude, Codex, Gemini, Kimi, or any
+> compatible combination** — are chosen when you add the project and are
+> **immutable after creation**. All four are enabled by default; there is no
+> provider switch in Project Settings.
 
 ---
 
@@ -144,7 +152,11 @@ Both extra providers are **enabled by default** and only need these levers if yo
 
 A disabled provider stops appearing in Add Project and is rejected by the create-project API; existing projects that already use it are unaffected on disk.
 
-`ANTHROPIC_API_KEY` is **not** read by the app. Each provider's CLI authenticates on its own — Claude via a subscription login or its own API-key configuration, Codex via `codex login`, Gemini via `GEMINI_API_KEY` (a Google AI Studio key) — so you do not set provider keys for the app itself. See the [Codex](../codex.md) and [Gemini](../gemini.md) guides for per-provider auth.
+Provider credentials are not stored by Desktop. Each CLI authenticates on its
+own: Claude through its login/config, Codex via `codex login`, Gemini through
+its native key/config, and Kimi via `kimi login` or user-managed
+`~/.kimi-code/config.toml`. See [Kimi](../kimi.md), [Codex](../codex.md), and
+[Gemini](../gemini.md).
 
 For the full catalogue of feature flags and kill switches (`SPECRAILS_*` server gates, `VITE_FEATURE_*` client flags, `SPECRAILS_CODEX_BETA`, `SPECRAILS_GEMINI_BETA`, `SPECRAILS_EXPLORE_*`), see [../customizing.md](../customizing.md#environment-variables).
 

package/docs/internals/global-artifacts-alignment-contract.md

@@ -76,7 +76,7 @@ Esta es la pieza central. `registry.json` es la **única fuente de verdad inspec
 | `profilesDir` | sí | `.specrails/profiles/` relocalizado. El snapshot por job sigue ganando vía `SPECRAILS_PROFILE_PATH`; este es el fallback standalone. |
 | `pluginsStateDir` | desktop-only | `.specrails/plugins/`. Core ignora plugins; presente por completitud/inspeccionabilidad. |
 | `fileSummariesDir` | desktop-only | `.specrails/file-summaries/`. Propiedad de desktop (Code explorer). |
-| `providers` | sí | `["claude","codex","gemini"]`. Espejo de `desktop.sqlite projects.providers`. Permite a core detectar el provider desde el registry en vez de sondear `.claude`/`.codex`/`.gemini` bajo el repo (ahora vacío). |
+| `providers` | sí | `["claude","codex","gemini","kimi"]`. Espejo de `desktop.sqlite projects.providers`. Permite a core detectar el provider desde el registry en vez de sondear `.claude`/`.codex`/`.gemini`/`.kimi-code` bajo el repo (ahora vacío). |
 | `primaryProvider` | sí | `providers[0]`. Espejo de `desktop.sqlite projects.provider`. |
 | `coreVersion` | sí | El pin `specrails-version` (nombre y formato **congelados** — desktop lo regex-matchea; solo su ubicación se mueve). |
 | `createdAt` | no | Primera asignación de la entrada. |

package/docs/internals/operations-runbook.md

@@ -43,7 +43,7 @@ The two forms print different output. The `status` **subcommand** prints `server
 
 > `specrails-desktop --jobs` is **not** functional against the running server — the server does not expose a cross-project `/api/jobs` route, so the command prints a message that jobs history requires a manager with SQLite persistence and exits `1`. Browse job history per project in the app's **Jobs** page instead.
 
-> **Offline CLI fallback.** When you run a command and no manager is up, the CLI prints `manager not running — invoking claude directly` and spawns a local `claude` process to handle it. This fallback **always uses `claude`** — it never spawns `codex` or `gemini`, regardless of a project's primary provider — and it writes **nothing** to Analytics (no `ai_invocations` row; cost/tokens are only echoed to your terminal). Start the manager (`specrails-desktop start`) to route through your project's real provider and capture the run.
+> **Offline CLI fallback.** When you run a command and no manager is up, the CLI prints `manager not running — invoking claude directly` and spawns a local `claude` process to handle it. This fallback **always uses `claude`** — it never spawns `codex`, `gemini`, or `kimi`, regardless of a project's primary provider — and it writes **nothing** to Analytics (no `ai_invocations` row; cost/tokens are only echoed to your terminal). Start the manager (`specrails-desktop start`) to route through your project's real provider and capture the run.
 
 ## App data location
 

package/docs/internals/profiles.md

@@ -27,17 +27,14 @@ Dashboard/Jobs/Analytics/Settings).
 When the project has no profiles yet, the empty state offers two entry
 points:
 
-- **Migrate from current agents** — reads your existing
-  `.claude/agents/` frontmatter models and creates a `default` profile
-  mirroring today's behavior (zero-loss). It requires the baseline trio
+- **Migrate from current agents** — reads the primary provider's native role
+  catalog (`.claude/agents/` or `.kimi-code/skills/`) and creates a
+  `default` profile mirroring today's behavior. It requires the baseline trio
   `sr-architect`, `sr-developer`, and `sr-reviewer` to be present — the
-  server rejects the migration if any is missing. On a project whose
-  primary provider is **not** Claude (Codex or Gemini), the frontmatter
-  model aliases aren't in that provider's catalog, so the migration stamps
-  the project's `provider` onto the profile and substitutes that provider's
-  default model — the resulting `default` profile still validates and is
-  ready to edit (though it only takes effect on Claude rails — see
-  [Multi-provider rails](#multi-provider-rails-claude-codex-and-gemini)).
+  server rejects the migration if any is missing. Provider-specific model
+  identifiers are retained only when they are in that provider's catalog;
+  otherwise migration uses its default and stamps the provider into the saved
+  profile.
 - **Blank profile** — start from scratch.
 
 ## 2. Saved profiles vs selection
@@ -71,26 +68,19 @@ wizard. Each rail header has a compact profile dropdown
 The "No profile" option is always available — use it to run a
 rail exactly as it did pre-4.1.0.
 
-### Multi-provider rails (Claude, Codex, and Gemini)
+### Multi-provider rails
 
-**Profiles apply only to Claude rails.** specrails-desktop supports three
-interchangeable AI providers — Claude, Codex, and Gemini — but agent
-profiles are a Claude-only concept (Codex and Gemini have no equivalent).
+Profiles apply to **Claude and Kimi** rails. Kimi profiles use exact Kimi
+model ids for both the parent orchestrator and every routed role; Core executes
+role skills through separate Kimi processes so a role can select a different
+model from its parent.
 
-When a rail's AI engine is **anything other than Claude** (Codex or
-Gemini), the app force-nulls the profile and runs the rail in legacy mode.
-The rails router enforces this server-side for *any* non-Claude engine, so
-no profile env var is ever injected on a Codex or Gemini rail regardless of
-what the UI shows.
+Codex and Gemini currently advertise no profile capability. Selecting either
+engine force-nulls the rail profile server-side and the client hides the
+selector. A profile whose `provider` does not match the effective rail provider
+is rejected rather than silently translating model aliases.
 
-> **Known UI limitation.** The client currently only hides the profile
-> selector for **Codex** rails. On a **Gemini** rail the selector can still
-> appear — but the server ignores any profile you pick there (it always
-> falls back to legacy mode). Picking a profile on a Gemini rail therefore
-> has no effect; treat it as a no-op until the selector is hidden for all
-> non-Claude engines.
-
-Provider availability itself is gated separately (both default-enabled): set
+Codex/Gemini availability itself is gated separately (both default-enabled): set
 `SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0` to disable a provider
 app-wide. See [../codex.md](../codex.md) and [../gemini.md](../gemini.md).
 
@@ -101,18 +91,20 @@ From the Catalog tab, create a new custom agent via:
 - **Template** — start from one of ~50 curated templates spanning many
   categories (engineering, product, data, security, …) — for example
   Security Reviewer, Performance Profiler, Data Engineer, or UI/UX Polisher.
-- **Generate** — describe the agent in natural language; Claude drafts the
-  full `.md` for you to review and edit before saving.
+- **Generate** — describe the agent in natural language; a provider with the
+  required no-tools policy drafts it. Kimi does not offer this action.
 - **Blank** — start from a minimal template.
 - **Duplicate** — copy any existing agent (upstream or custom).
 
-Custom agents live at `.claude/agents/custom-*.md` and are never touched
-by `specrails-core`'s installer/update scripts. Every save appends a new
-version row; open **History** in the Studio to browse and restore.
+Custom agents live at `.claude/agents/custom-*.md` for Claude or
+`.kimi-code/skills/custom-*/SKILL.md` for Kimi and are never touched by
+`specrails-core`'s installer/update scripts. Every save appends a new version
+row; open **History** in the Studio to browse and restore.
 
-Click **Test** in the Studio to run the current draft against a sample
-task in an isolated `claude` invocation — no files are written, and you
-see output, token count, and duration inline.
+Click **Test** in the Studio to run the current draft against a sample task
+only when the selected provider can enforce the smoke test's safe tool policy.
+Kimi generation, Test, and AI Refine are rejected before spawn; manual blank/
+template/duplicate/edit and rail execution remain available.
 
 ## 5. Observe
 
@@ -127,15 +119,15 @@ see output, token count, and duration inline.
 ## 6. Troubleshooting
 
 - **Upgrade banner on Agents page** — run
-  `npx specrails-core@^4.8.0 update` in the project to bring it up to date
-  (profiles need ≥ 4.1.0; the version the app installs is `^4.8.0`).
+  `npx specrails-core@^4.12.0 update` in the project to bring it up to date
+  (profiles need ≥ 4.1.0; the version the app installs is `^4.12.0`).
 - **Save disabled with "N issues to resolve"** — the live validator
   enforces the baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`)
   and routing ordering. Among the rules: a `default: true` routing rule (if
   present) must be the **last** entry in `routing` and must target
   `sr-developer`. Fix the listed issues and Save re-enables.
 - **"agent 'xyz' already exists" (409)** — the name collides with an
-  existing file in `.claude/agents/`. Pick a different name.
+  existing provider role. Pick a different name.
 - **The whole Agents section is missing** — it can be disabled server-side
   with `SPECRAILS_AGENTS_SECTION=false`, which 404s the entire
   `/profiles` router. Unset it (or leave it at its default) to restore the
@@ -148,6 +140,7 @@ see output, token count, and duration inline.
 
 - `.specrails/profiles/**` — your profile catalog.
 - `.claude/agents/custom-*.md` — your custom agents.
+- `.kimi-code/skills/custom-*/**` — your custom Kimi roles.
 
 Everything else under `.specrails/` (install-config, specrails-version,
 setup-templates) is managed by the installer and may be overwritten on
@@ -160,16 +153,15 @@ A few internals worth knowing if you're working on this surface:
 - **Version gate.** Profile-aware spawns are gated by
   `projectSupportsProfiles()` (`server/queue-manager.ts`), which reads the
   project's `.specrails/specrails-version` and requires
-  `specrails-core >= 4.1.0`. Below that, the rail spawns in legacy mode and
-  no profile env var is injected. The same is true on any non-Claude rail:
-  the rails router force-nulls the profile for Codex/Gemini engines, so the
-  `SPECRAILS_PROFILE_PATH` injection below only ever takes effect on a
-  Claude rail.
+  `specrails-core >= 4.1.0`; Kimi additionally requires the Core 4.12 target.
+  Below the applicable floor, the rail spawns in legacy mode and no profile
+  env var is injected. The rails router also force-nulls profiles for adapters
+  that do not advertise profile support (currently Codex/Gemini).
 - **Snapshot per job.** When a rail launches with a profile, the resolved
   profile is written to
   `~/.specrails/projects/<slug>/jobs/<jobId>/profile.json` (chmod `400`, so
-  mid-run edits are impossible) before the `claude` process spawns. The
-  spawn env then carries `SPECRAILS_PROFILE_PATH` pointing at that file.
+  mid-run edits are impossible) before the provider process spawns. The spawn
+  env then carries `SPECRAILS_PROFILE_PATH` pointing at that file.
   The same snapshot is persisted to the `job_profiles` table for the Usage
   analytics.
 - **REST surface.** All profile operations live under