specrails-core 4.11.3 → 4.12.0

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 |