specrails-core 4.11.3 → 4.12.1

package/docs/installation.md

@@ -2,19 +2,15 @@
 
 This guide covers the complete installation process in detail. For the quick version, see [Getting Started](getting-started.md).
 
-> ## 🧪 Codex (OpenAI) Support — Coming Soon (in Lab)
->
-> OpenAI Codex integration is currently being **tested in our lab** and **cannot be installed yet**. The installer will refuse any attempt to install with `--provider codex` and will guide you to use Claude Code instead. Codex-specific sections below describe the **planned behaviour** and will be activated when the feature ships.
-
 ## Installation methods
 
-SpecRails supports two distribution channels today, with a third coming soon:
+SpecRails offers a Claude plugin and a provider-independent scaffold:
 
 | Method | Command | Best for |
 |--------|---------|----------|
 | **Claude Code plugin** (recommended) | `claude plugin install sr` | Most projects — no Node.js required, auto-updates |
 | **Claude Code scaffold** | `npx specrails-core@latest init` | Full offline control, custom agent edits |
-| **Codex project** 🧪 _Coming Soon (in lab)_ | `npx specrails-core@latest init` | OpenAI Codex CLI users (not yet available) |
+| **Provider scaffold** | `npx specrails-core@latest init` | Claude, Codex, Gemini, or Kimi Code projects |
 
 ---
 
@@ -59,9 +55,9 @@ The plugin bundles the logic layer — agents, skills, commands, hooks, and refe
 
 | Tool | Why | Install |
 |------|-----|---------|
-| **Node.js 20+** | Required for the installer (macOS, Linux, Windows) | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
+| **Node.js 20.19.0+** | Required for the installer and pinned OpenSpec 1.4.1 CLI (macOS, Linux, Windows) | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
 | **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
-| **Claude Code** or **Codex CLI** | The AI CLI that runs the agents | See [codex-vs-claude-code.md](user-docs/codex-vs-claude-code.md) |
+| **Supported AI CLI** | The runtime that runs the agents | Claude, Codex, Gemini, or [Kimi Code](user-docs/getting-started-kimi.md) |
 
 ### Install
 
@@ -88,7 +84,8 @@ node bin/specrails-core.mjs init --root-dir <your-project>
 The `npx specrails-core@latest init` command now includes a **TUI installer** that runs before copying files:
 
 1. **TUI agent selection** — Interactive terminal UI lets you select which agents to install and choose a model preset (balanced/budget/max). Writes `.specrails/install-config.yaml`.
-2. **Checks prerequisites** — validates Git, Claude Code; optionally installs npm and gh
+2. **Checks prerequisites** — validates Git and the selected provider CLI;
+   optionally installs npm and gh
 3. **Detects existing setup** — warns if SpecRails artifacts already exist
 4. **Installs artifacts:**
    - `.claude/commands/specrails/enrich.md` — the `/specrails:enrich` wizard
@@ -105,12 +102,26 @@ The scaffold installer only copies files. It does not modify your existing code,
 
 ## The Enrich Wizard
 
-After either installation method, open Claude Code (or Codex) in your project and run:
+After either installation method, open the selected AI CLI. Claude and Gemini
+use:
 
 ```
 /specrails:enrich
 ```
 
+Kimi uses:
+
+```text
+/skill:specrails-enrich
+```
+
+That slash form is Kimi TUI syntax. Automated callers use the managed
+`.kimi-code/specrails/run-skill.mjs` helper installed beside the skills; passing
+the slash form directly to `kimi -p` does not activate it in Kimi 0.27.
+Generated multi-role workflows give that helper one structured foreground
+role wave. It owns parallel child processes and reusable worktrees, so no
+Kimi daemon or bundled provider binary is required.
+
 There are three modes:
 
 | Mode | Command | When to use |
@@ -274,28 +285,35 @@ Runs a fully automated installation using `.specrails/install-config.yaml`. No i
 
 ```yaml
 version: 1
-provider: claude        # claude | codex | auto
+provider: claude        # claude | codex | gemini | kimi
 tier: full              # full (requires /specrails:enrich) | quick (agents placed directly)
 agents:
-  selected:             # list of agent names to install
+  selected:             # unique lowercase kebab-case ids (1-64 chars)
     - sr-architect
     - sr-developer
     - sr-reviewer
     - sr-test-writer
     - sr-product-manager
-  excluded: []          # agent names to skip
+  excluded: []          # unique ids to skip; must not overlap selected
 models:
   preset: balanced      # balanced | budget | max
-  overrides: {}         # per-agent overrides: { sr-architect: opus }
+  defaults:
+    model: sonnet       # exact provider model/alias; Kimi defaults to k3
+  overrides: {}         # exact per-agent models: { sr-architect: opus }
 ```
 
 **Model presets:**
 
 | Preset | Description |
 |--------|-------------|
-| `balanced` (default) | Opus for architect + PM, Sonnet for all others |
+| `balanced` (default) | Sonnet for all Claude agents |
 | `budget` | Haiku for all agents |
-| `max` | Opus for all agents |
+| `max` | Opus for Claude architect + PM, Sonnet for all others |
+
+Other providers resolve the same preset names within their own catalog. Kimi
+presets default to `k3`; exact official ids and configured aliases are retained.
+Kimi ids must be 1–128 characters matching
+`[A-Za-z0-9][A-Za-z0-9._/:-]*`, the same grammar enforced at process launch.
 
 ---
 

package/docs/plugin-architecture.md

@@ -74,19 +74,22 @@ The scaffold copies the full agent+command set into `.claude/` — you own and v
 
 **Best for:** Teams that want to version the agent prompts themselves, or projects that need full offline control.
 
-### 3. Codex project 🧪 _Coming Soon (in Lab)_
-
-> **Codex installation is not yet available.** OpenAI Codex integration is being tested in our lab and will ship shortly. The block below describes the **planned behaviour** for when the feature is released.
+### 3. Provider scaffold
 
 ```bash
-npx specrails-core@latest init --root-dir .   # same as scaffold (Codex path — not yet available)
-codex                                          # open Codex
-/specrails:enrich                             # configure
+npx specrails-core@latest init --root-dir . --provider codex
+npx specrails-core@latest init --root-dir . --provider gemini
+npx specrails-core@latest init --root-dir . --provider kimi
 ```
 
-Codex does not support the Claude Code plugin system. When Codex support ships, use the scaffold method.
+Codex, Gemini, and Kimi do not use the Claude Code plugin package. The
+scaffold renders their native project surfaces under `.codex/`, `.gemini/`,
+and `.kimi-code/` respectively. Kimi interactive workflows use
+`/skill:specrails-*`; its headless workflows use the managed runner installed
+under `.kimi-code/specrails/`.
 
-**Best for (when available):** OpenAI Codex CLI users.
+**Best for:** Codex, Gemini, or Kimi users and teams that version generated
+provider artifacts.
 
 ## The `/specrails:enrich` wizard
 

package/docs/updating.md

@@ -8,7 +8,8 @@ The update system uses a **manifest-based approach**:
 
 1. During installation, SpecRails generates `.specrails/specrails-manifest.json` — a checksum of every installed file
 2. On update, the new templates from the latest specrails-core release are re-applied
-3. Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are preserved by construction — the installer never touches them
+3. Reserved paths (`.specrails/profiles/**`, provider-specific `custom-*`
+   roles, OpenSpec skills, and user MCP entries) are preserved by construction
 
 ## Running an update
 
@@ -21,9 +22,13 @@ Cross-platform (macOS, Linux, Windows). No bash, no python required — the inst
 ### What happens
 
 1. **Version check** — reads existing `.specrails/specrails-version`; aborts if no specrails install is detected
-2. **Provider resolution** — detects whether the project uses Claude (`.claude/`) or Codex (`.codex/`)
+2. **Provider resolution** — detects Claude (`.claude/`), Codex (`.codex/`),
+   Gemini (`.gemini/`), or Kimi (`.kimi-code/`). In a multi-provider workspace,
+   pass `--provider` to select the tree being refreshed.
 3. **Re-scaffold** — re-applies templates from the latest specrails-core into `.specrails/setup-templates/` and the provider directory
-4. **Reserved paths** — `.specrails/profiles/**` and `.claude/agents/custom-*.md` are skipped; your team profiles and custom agents survive untouched
+4. **Reserved paths** — profiles and provider-specific custom roles are skipped;
+   Kimi also preserves `openspec-*`, unknown skill directories, and existing
+   `.kimi-code/mcp.json` entries
 5. **Manifest refresh** — rewrites `specrails-manifest.json` and `specrails-version` to the new core version
 
 ## Selective updates (`--only`)
@@ -49,6 +54,19 @@ Prints what the update would do without writing any files. Useful for inspecting
 | **Rules** (`.claude/rules/`) | Re-written from latest templates |
 | **Agent memory** (`.claude/agent-memory/`) | Untouched (created on first install only) |
 | **install-config.yaml** | Untouched |
+| **Kimi workflows** (`.kimi-code/skills/specrails-*`) | Re-written from latest templates |
+| **Kimi roles** (`.kimi-code/skills/sr-*`) | Re-written according to the selected agent set |
+| **Kimi custom roles** (`.kimi-code/skills/custom-*`) | **Always preserved** |
+| **Kimi OpenSpec skills** (`.kimi-code/skills/openspec-*`) | Preserved and normalized from legacy `.kimi/skills` when needed |
+| **Kimi MCP config** (`.kimi-code/mcp.json`) | Existing entries preserved; SpecRails-owned entries merged additively |
+| **Kimi headless runner** (`.kimi-code/specrails/`) | Runner, vendored YAML parser, MIT license, and provenance notice are re-written together from the latest trusted Core template; they are managed code, not user skills |
+
+Kimi discovers only immediate child directories of `.kimi-code/skills`.
+Updates therefore migrate the pre-release
+`.kimi-code/skills/rails/custom-*` layout to direct `custom-*` children when
+the destination is free, and regenerate managed `sr-*` roles at the direct
+level. If both legacy and direct versions of a custom role exist, neither is
+overwritten or deleted: `doctor` reports the conflict for manual resolution.
 
 ## Rolling back
 

package/docs/user-docs/cli-reference.md

@@ -1,14 +1,14 @@
 # CLI Reference
 
-> **🧪 Codex (OpenAI) Support — Coming Soon (in Lab).** Codex-specific sections below describe the planned behaviour. Codex installation is currently disabled — only Claude Code is available today.
-
-SpecRails commands are implemented as Skills (`SKILL.md` format) and are designed to run in both Claude Code and Codex. The command syntax is identical on both platforms. Today only the Claude Code runtime is available; Codex support is being tested in our lab and will ship shortly.
+SpecRails installs provider-native workflows for Claude Code, Codex CLI,
+Gemini CLI, and Kimi Code. The workflow names and flags are shared, while each
+provider uses its own activation syntax and project directory.
 
 **Platform support key used in this reference:**
 
 | Badge | Meaning |
 |-------|---------|
-| ✅ Both | Works in Claude Code and Codex |
+| ✅ Providers | Works in Claude Code, Codex CLI, Gemini CLI, and Kimi Code |
 | 🔵 Claude Code | Claude Code only |
 | ⚠️ Limited | Works, but with known limitations (see notes) |
 
@@ -17,13 +17,20 @@ Run commands inside your AI CLI from your project directory:
 ```bash
 claude   # Claude Code
 codex    # Codex
+gemini   # Gemini CLI
+kimi     # Kimi Code
 ```
 
+Claude and Gemini use `/specrails:<command>`. Codex activates the generated
+skill from `.codex/skills/`. Kimi's interactive TUI uses
+`/skill:specrails-<command>`; headless Kimi runs must use the managed
+`.kimi-code/specrails/run-skill.mjs` helper, not a literal `/skill:` prompt.
+
 ---
 
 ## Core workflow
 
-### `/specrails:implement` ✅ Both
+### `/specrails:implement` ✅ Providers
 
 Implement a feature through the full agent pipeline: design → code → tests → docs → review → PR.
 
@@ -62,10 +69,15 @@ A single issue runs sequentially on the current branch. Multiple issues run in p
 
 ---
 
-### `/specrails:telemetry` ✅ Both
+### `/specrails:telemetry` ✅ Providers
 
 Inspect per-agent execution metrics: token usage, estimated API cost, run count, average duration, and success/failure rate.
 
+Kimi reads persisted `usage.record` events for real input/output/cache token
+counts and session duration. Its logs do not contain an authoritative USD rate
+or role outcome, so the Kimi dashboard reports cost and success rate as
+unavailable instead of applying another provider's rate card.
+
 ```
 /specrails:telemetry
 /specrails:telemetry --period today
@@ -81,11 +93,11 @@ Inspect per-agent execution metrics: token usage, estimated API cost, run count,
 | `--period <filter>` | Time window: `today`, `week` (default), or `all` |
 | `--agent <name>` | Focus on a single agent (e.g. `sr-developer`) |
 | `--format <fmt>` | Output format: `markdown` (default) or `json` |
-| `--save` | Write a snapshot to `.claude/telemetry/` after display |
+| `--save` | Write a snapshot under the active provider directory after display |
 
 ---
 
-### `/specrails:merge-resolve` ✅ Both
+### `/specrails:merge-resolve` ✅ Providers
 
 Resolve git conflict markers using AI-powered context analysis.
 
@@ -107,7 +119,7 @@ Reads OpenSpec context bundles from the features that produced each conflict, in
 
 ---
 
-### `/specrails:retry` ✅ Both
+### `/specrails:retry` ✅ Providers
 
 Resume a failed `/specrails:implement` run from the last successful phase.
 
@@ -128,7 +140,7 @@ Resume a failed `/specrails:implement` run from the last successful phase.
 
 **Valid `--from` values:** `architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci`
 
-Pipeline state is saved to `.claude/pipeline-state/<feature-name>.json` after each phase.
+Pipeline state is saved under the active provider directory after each phase.
 
 ---
 
@@ -148,7 +160,7 @@ Each feature gets its own worktree, its own agent pipeline, and its own PR. Use
 
 ## Product and backlog
 
-### `/specrails:get-backlog-specs` ✅ Both
+### `/specrails:get-backlog-specs` ✅ Providers
 
 View your prioritized product backlog, ranked by VPC persona fit and estimated effort.
 
@@ -161,7 +173,7 @@ Reads GitHub Issues labeled `product-driven-backlog`. Produces a ranked table pe
 
 ---
 
-### `/specrails:auto-propose-backlog-specs` ✅ Both
+### `/specrails:auto-propose-backlog-specs` ✅ Providers
 
 Generate new feature ideas through product discovery and create GitHub Issues.
 
@@ -176,7 +188,7 @@ The Product Manager researches your competitive landscape, generates 2–4 featu
 
 ## Analysis and inspection
 
-### `/specrails:refactor-recommender` ✅ Both
+### `/specrails:refactor-recommender` ✅ Providers
 
 Scan the codebase for refactoring opportunities, ranked by impact/effort ratio.
 
@@ -188,7 +200,7 @@ Identifies duplicates, overly long functions, large files, dead code, outdated p
 
 ---
 
-### `/specrails:compat-check` ✅ Both
+### `/specrails:compat-check` ✅ Providers
 
 Analyze the backwards-compatibility impact of a proposed change.
 
@@ -205,7 +217,7 @@ The Architect runs this automatically as part of every `/specrails:implement` pi
 
 ---
 
-### `/specrails:why` ✅ Both
+### `/specrails:why` ✅ Providers
 
 Search agent explanation records in plain language.
 
@@ -215,11 +227,13 @@ Search agent explanation records in plain language.
 /specrails:why "why is pagination implemented this way"
 ```
 
-Agents write decision rationale to `.claude/agent-memory/explanations/` as they work. `/specrails:why` searches these records semantically. Useful for onboarding, code review, and revisiting past decisions.
+Agents write decision rationale under the active provider's `agent-memory/`
+directory as they work. `/specrails:why` searches these records semantically.
+Useful for onboarding, code review, and revisiting past decisions.
 
 ---
 
-### `/specrails:vpc-drift` ✅ Both
+### `/specrails:vpc-drift` ✅ Providers
 
 Detect when your VPC personas have drifted from what your product actually delivers.
 
@@ -234,7 +248,7 @@ Compares persona Jobs/Pains/Gains against your backlog, implemented features, an
 
 ---
 
-### `/specrails:memory-inspect` ✅ Both
+### `/specrails:memory-inspect` ✅ Providers
 
 Inspect and clean up agent memory directories.
 
@@ -252,11 +266,18 @@ Inspect and clean up agent memory directories.
 | `--stale <days>` | Flag files older than N days |
 | `--prune` | Delete stale files (prompts for confirmation) |
 
-Agent memory lives in `.claude/agent-memory/sr-*/` (Claude Code) or `.codex/agent-memory/sr-*/` (Codex).
+Agent memory lives below the provider root:
+
+| Provider | Memory root |
+|----------|-------------|
+| Claude Code | `.claude/agent-memory/` |
+| Codex CLI | `.codex/agent-memory/` |
+| Gemini CLI | `.gemini/agent-memory/` |
+| Kimi Code | `.kimi-code/agent-memory/` |
 
 ---
 
-### `/specrails:propose-spec` ✅ Both
+### `/specrails:propose-spec` ✅ Providers
 
 Explore a feature idea and produce a structured proposal ready for the OpenSpec pipeline.
 
@@ -272,7 +293,7 @@ Produces: problem statement, proposed solution, out-of-scope items, acceptance c
 
 OpenSpec is the structured design-to-code workflow. Use these commands when you want explicit control over each artifact: proposal → design → tasks → implementation.
 
-All OpenSpec commands work on both Claude Code and Codex (✅ Both).
+OpenSpec commands are generated for all four providers (✅ Providers).
 
 ### `/opsx:ff` — Fast Forward
 
@@ -400,7 +421,7 @@ The `npx specrails-core@latest init` command accepts:
 |------|--------|
 | `--root-dir <path>` | Install into this directory (default: current directory) |
 | `--yes` / `-y` | Skip confirmation prompts |
-| `--provider <claude\|codex>` | Force a specific AI CLI (default: auto-detect) |
+| `--provider <claude\|codex\|gemini\|kimi>` | Force a specific AI CLI (default: auto-detect) |
 
 ---
 

package/docs/user-docs/codex-vs-claude-code.md

@@ -1,10 +1,8 @@
 # Codex vs Claude Code
 
-> # 🧪 Codex Support — Coming Soon (in Lab)
->
-> OpenAI Codex integration is currently being **tested in our lab** and is not available for installation. The installer only accepts Claude Code at this time. This document describes the planned behaviour and will be activated when the feature ships.
-
-SpecRails supports **Anthropic Claude Code** as an AI agent runtime, with **OpenAI Codex** support coming soon. This page explains the differences so you can choose the right setup for your team when Codex ships.
+SpecRails supports both **Anthropic Claude Code** and **OpenAI Codex** as AI
+agent runtimes. Gemini CLI and Kimi Code are also supported; this page focuses
+only on the Claude/Codex comparison.
 
 ---
 
@@ -12,7 +10,7 @@ SpecRails supports **Anthropic Claude Code** as an AI agent runtime, with **Open
 
 | | Claude Code | Codex |
 |--|-------------|-------|
-| **Support status** | Stable | Beta |
+| **Support status** | Supported | Supported |
 | **CLI** | `claude` | `codex` |
 | **Config directory** | `.claude/` | `.codex/` |
 | **Agent instructions** | `CLAUDE.md` | `AGENTS.md` |
@@ -113,7 +111,11 @@ Skills themselves are the same — only the CLI invocation differs.
 - Different team members use different tools
 - You want to benchmark agents across platforms
 
-When both CLIs are installed, the SpecRails installer detects which is active. You can override with `CLI_PROVIDER=claude` or `CLI_PROVIDER=codex`.
+When several CLIs are installed, pass `--provider` to choose explicitly:
+
+```bash
+npx specrails-core@latest init --provider codex
+```
 
 ---
 
@@ -129,8 +131,8 @@ Generating config in .codex/
 To override:
 
 ```bash
-CLI_PROVIDER=codex npx specrails-core@latest init --root-dir .
-CLI_PROVIDER=claude npx specrails-core@latest init --root-dir .
+npx specrails-core@latest init --provider codex --root-dir .
+npx specrails-core@latest init --provider claude --root-dir .
 ```
 
 ---

package/docs/user-docs/faq.md

@@ -12,7 +12,7 @@ The plugin method (`claude plugin install sr`) installs logic into Claude Code's
 
 **Do I need Node.js if my project is not JavaScript?**
 
-Not for the plugin method (`claude plugin install sr`). Node.js 20+ is only required for the scaffold method (`npx specrails-core@latest init`). Once installed, SpecRails works with any language or framework, on macOS, Linux, or Windows.
+Not for the plugin method (`claude plugin install sr`). Node.js 20.19.0+ is only required for the scaffold method (`npx specrails-core@latest init`), because its pinned OpenSpec 1.4.1 CLI uses that runtime floor. Once installed, SpecRails works with any language or framework, on macOS, Linux, or Windows.
 
 **Do I need GitHub Issues?**
 

package/docs/user-docs/getting-started-codex.md

@@ -1,12 +1,9 @@
 # Getting Started with SpecRails + Codex
 
-> # 🧪 Coming Soon — Currently in Lab
->
-> **OpenAI Codex support is being tested in our lab and is not yet available for installation.** The installer will refuse to install Codex and will ask you to use Claude Code. This document describes the planned behaviour and will be activated when the feature ships.
->
-> **Current status:** Preview / documentation only. For now, use [Claude Code](https://claude.ai/download) — see the [standard installation guide](installation.md).
-
-This guide gets you running SpecRails using OpenAI Codex as your AI agent. If you are using Claude Code instead, see the [standard installation guide](installation.md).
+This guide gets you running SpecRails using OpenAI Codex as your AI agent.
+Claude Code, Gemini CLI, and Kimi Code are also supported; see the
+[standard installation guide](installation.md) or the
+[Kimi-specific guide](getting-started-kimi.md).
 
 ---
 
@@ -14,7 +11,7 @@ This guide gets you running SpecRails using OpenAI Codex as your AI agent. If yo
 
 | Tool | Version | Notes |
 |------|---------|-------|
-| **Node.js** | 18+ | Required for the installer |
+| **Node.js** | 20.19.0+ | Required for the installer and pinned OpenSpec 1.4.1 CLI |
 | **Codex CLI** | Latest | `npm i -g @openai/codex` |
 | **Git** | Any | Your project must be a git repository |