specrails-core 5.5.1 → 6.0.0

package/docs/research/mcp-feasibility-analysis.md

@@ -1,382 +0,0 @@
-# MCP Server for specrails-core — Feasibility Analysis
-
-**Date:** 2026-03-21
-**Author:** CTO of Engineering
-**Status:** Research Complete — Recommendation Included
-**Task:** SPEA-480
-
----
-
-## Executive Summary
-
-This document evaluates whether building an MCP (Model Context Protocol) server for specrails-core is strategically sound. After thorough analysis of the current architecture, the MCP protocol capabilities, and the product roadmap, **the recommendation is YES — with a focused, phased scope**.
-
-An MCP server should expose **read-only knowledge access** and **lightweight utility operations**, while the multi-agent orchestration pipeline stays in Claude Code commands. This approach maximizes cross-client reach with minimal maintenance overhead.
-
----
-
-## 1. What is MCP?
-
-The **Model Context Protocol** is Anthropic's open standard for connecting AI models to external data sources and tools. It defines three primitives:
-
-| Primitive | Purpose | Direction |
-|-----------|---------|-----------|
-| **Resources** | Expose read-only data (files, records, configs) | Server → Client |
-| **Tools** | Actions that modify state or compute results | Client → Server → Client |
-| **Prompts** | Parameterized prompt templates | Server → Client |
-
-MCP servers run as local processes (stdio) or remote services (HTTP+SSE). Any MCP-compatible client can connect: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Copilot), Zed, and others.
-
----
-
-## 2. Current specrails-core Architecture (No MCP)
-
-### Distribution & Execution Model
-
-```
-npx specrails-core@latest init    →   install.sh (bash)    →   /specrails:setup (Claude Code command)
-                                        │                         │
-                                        ├── Copy templates        ├── Detect codebase
-                                        ├── Create dirs           ├── Generate agents
-                                        └── Write manifest        └── Substitute placeholders
-```
-
-### Runtime Architecture
-
-```
-Claude Code
-├── Commands (/specrails:implement, /specrails:get-backlog-specs, ...)
-├── Skills (/opsx:new, /opsx:apply, /opsx:ff, ...)
-├── Agents (sr-architect, sr-developer, sr-reviewer, ...)
-├── Rules (.claude/rules/ — layer-specific conventions)
-└── Agent Memory (.claude/agent-memory/ — explanations, failures)
-```
-
-### Key Characteristics
-
-- **Zero-daemon**: No running processes — everything is files + CLI commands
-- **Claude Code-native**: Tight integration with Agent tool, worktrees, Skills API
-- **CLI-based integrations**: GitHub CLI, OpenSpec CLI, npm — no HTTP APIs
-- **Local-first**: All state stored on filesystem (JSON, YAML, Markdown)
-- **12 specialized agents** with orchestrated multi-phase pipeline
-- **80+ template placeholders** for codebase-adaptive generation
-
----
-
-## 3. What Would an MCP Server Expose?
-
-### 3.1 Resources (Read-Only Data)
-
-| Resource | URI Pattern | Description |
-|----------|-------------|-------------|
-| Specs | `specrails://specs/{name}` | OpenSpec specifications (source of truth) |
-| Active Changes | `specrails://changes/{name}` | Active OpenSpec changes with status |
-| Archived Changes | `specrails://changes/archive/{name}` | Historical change records |
-| Personas | `specrails://personas/{name}` | VPC persona profiles (jobs, pains, gains) |
-| Agent Config | `specrails://agents/{name}` | Agent personality & configuration |
-| Layer Rules | `specrails://rules/{layer}` | Per-layer coding conventions |
-| Failure Records | `specrails://memory/failures` | CI failure patterns and prevention rules |
-| Explanations | `specrails://memory/explanations` | Implementation decision records |
-| Project Config | `specrails://config` | CLAUDE.md, integration contract, manifest |
-
-### 3.2 Tools (Actions)
-
-| Tool | Input | Output | Side Effects |
-|------|-------|--------|--------------|
-| `specrails_doctor` | (none) | Health check report | None (read-only) |
-| `specrails_score_feature` | Feature description | VPC scores per persona | None |
-| `specrails_analyze_codebase` | Project root path | Stack, architecture, conventions | None |
-| `specrails_list_changes` | (optional filters) | Active changes with status | None |
-| `specrails_get_change_status` | Change name | Artifact status, task progress | None |
-| `specrails_query_failures` | File glob pattern | Matching failure records | None |
-| `specrails_query_backlog` | (optional filters) | GitHub Issues with VPC scores | None |
-| `specrails_check_compat` | Version string | Integration contract validation | None |
-
-### 3.3 Prompts (Templates)
-
-| Prompt | Parameters | Purpose |
-|--------|------------|---------|
-| `review_with_conventions` | `layer`, `files` | Review prompt with auto-loaded layer rules |
-| `explore_feature` | `description` | VPC-aware feature exploration prompt |
-| `implement_context` | `change_name` | Context bundle for a specific change |
-
----
-
-## 4. Strategic Analysis
-
-### 4.1 Arguments FOR an MCP Server
-
-#### A. Cross-Client Reach (High Impact)
-
-Currently specrails-core **only works inside Claude Code**. An MCP server makes the knowledge layer accessible from:
-
-- **Claude Desktop** — Product managers can query personas and backlog without a terminal
-- **Cursor / Windsurf** — Developers in other IDEs get specrails context
-- **VS Code (Copilot)** — Teams using GitHub Copilot can still access specs and conventions
-- **Custom tooling** — Any MCP client can connect
-
-This dramatically expands the addressable market beyond Claude Code-only users.
-
-#### B. Tool Ecosystem Composability (Medium Impact)
-
-MCP is becoming the standard protocol for AI tool integration. As an MCP server, specrails-core can be **composed** with:
-
-- Database MCP servers (query production data alongside specs)
-- Monitoring MCP servers (correlate failures with system metrics)
-- CI/CD MCP servers (trigger builds with specrails context)
-
-#### C. Structured API for Hub Integration (High Impact)
-
-specrails-hub currently uses a rigid `integration-contract.json` for core↔hub communication. An MCP server provides a **dynamic, structured API** that hub can query:
-
-```
-Current:  Hub reads static JSON contract → spawns CLI commands
-With MCP: Hub connects as MCP client → queries resources, invokes tools
-```
-
-This eliminates the version-coupling problem where hub must know core's CLI interface.
-
-#### D. Separation of Concerns (Medium Impact)
-
-The current architecture tightly couples specrails to Claude Code's command/skill system. MCP creates a clean **knowledge API layer** separate from the **orchestration layer**:
-
-```
-┌─────────────────────────────────────────────┐
-│              MCP Server (Knowledge)          │
-│  Specs, Personas, Memory, Config, Analysis   │
-├─────────────────────────────────────────────┤
-│         Claude Code (Orchestration)          │
-│  /specrails:implement, /specrails:batch-implement, agents  │
-└─────────────────────────────────────────────┘
-```
-
-#### E. Remote/Multi-Repo Scenarios (Future Value)
-
-MCP supports HTTP+SSE transport. A centralized specrails MCP server could:
-
-- Serve specs across multiple repos from one instance
-- Enable cross-repo knowledge queries
-- Power a team-wide development dashboard
-
-### 4.2 Arguments AGAINST an MCP Server
-
-#### A. Current System Works Well
-
-Skills and commands already provide strong Claude Code integration. MCP adds complexity for users who only use Claude Code.
-
-**Counter:** MCP doesn't replace commands/skills — it supplements them with cross-client access.
-
-#### B. Orchestration Can't Move to MCP
-
-The `/specrails:implement` pipeline requires Claude Code's Agent tool (subagent spawning, worktree isolation, background execution). MCP tools are request/response — they can't replicate multi-phase orchestration.
-
-**Counter:** This is exactly why the recommendation is scoped. Orchestration stays in Claude Code; only knowledge access moves to MCP.
-
-#### C. Maintenance Overhead
-
-Two interfaces to maintain (skills + MCP). Template changes could require updates in both.
-
-**Counter:** MCP resources are read-only wrappers around existing files. No template duplication — the MCP server reads the same files that skills read.
-
-#### D. MCP Server Process Overhead
-
-Currently specrails-core is zero-daemon. Adding an MCP server means a running process.
-
-**Counter:** MCP stdio servers start on-demand (launched by the client). No persistent daemon needed. The MCP server binary can ship with the npm package.
-
-#### E. Protocol Maturity
-
-MCP is still evolving. Breaking changes in the protocol could require updates.
-
-**Counter:** MCP has reached stable specification status. Core primitives (resources, tools, prompts) are unlikely to change fundamentally.
-
----
-
-## 5. Competitive Landscape
-
-| Product | MCP Support | Notes |
-|---------|-------------|-------|
-| **Cursor** | MCP client | Users can connect to any MCP server |
-| **Windsurf** | MCP client | Growing MCP ecosystem |
-| **Continue.dev** | MCP client | Open-source IDE extension |
-| **Cline** | MCP client | VS Code extension with MCP |
-| **aider** | No MCP | CLI-only, no extensibility protocol |
-| **Devin** | No MCP | Closed platform |
-| **specrails-core** | **No MCP (current)** | Claude Code-only |
-
-Having MCP support positions specrails-core as the **only product-driven development framework accessible from any MCP client**.
-
----
-
-## 6. Recommended Architecture
-
-### 6.1 Server Design
-
-```
-specrails-core/
-├── src/
-│   └── mcp/
-│       ├── server.ts              # MCP server entry point
-│       ├── resources/
-│       │   ├── specs.ts           # OpenSpec spec resources
-│       │   ├── changes.ts         # Change status resources
-│       │   ├── personas.ts        # VPC persona resources
-│       │   ├── agents.ts          # Agent config resources
-│       │   ├── memory.ts          # Memory/failure resources
-│       │   └── config.ts          # Project config resources
-│       ├── tools/
-│       │   ├── doctor.ts          # Health check tool
-│       │   ├── score-feature.ts   # VPC scoring tool
-│       │   ├── analyze.ts         # Codebase analysis tool
-│       │   ├── query-backlog.ts   # Backlog query tool
-│       │   └── change-status.ts   # Change status tool
-│       └── prompts/
-│           ├── review.ts          # Review with conventions
-│           └── explore.ts         # VPC-aware exploration
-├── bin/
-│   └── specrails-mcp.js           # MCP stdio entry point
-└── package.json                   # Add "specrails-mcp" bin entry
-```
-
-### 6.2 Transport & Distribution
-
-```json
-// Client configuration (e.g., claude_desktop_config.json)
-{
-  "mcpServers": {
-    "specrails": {
-      "command": "npx",
-      "args": ["specrails-core@latest", "mcp"],
-      "env": {
-        "SPECRAILS_PROJECT_ROOT": "/path/to/project"
-      }
-    }
-  }
-}
-```
-
-- **Transport**: stdio (launched by client on-demand)
-- **Distribution**: Ships with existing npm package — no separate install
-- **CLI entry**: `specrails-core mcp` starts the MCP server
-- **Project detection**: Uses `SPECRAILS_PROJECT_ROOT` env var or auto-detects from cwd
-
-### 6.3 Technology Choice
-
-| Option | Pros | Cons |
-|--------|------|------|
-| **TypeScript (recommended)** | Same language as rest of specrails ecosystem, official `@modelcontextprotocol/sdk` package, type safety | Build step required |
-| Python | Official SDK, large MCP community | Different language from rest of stack |
-| Bash | Consistent with install.sh | No MCP SDK, painful to implement |
-
-**Recommendation: TypeScript** using `@modelcontextprotocol/sdk`.
-
----
-
-## 7. Implementation Phases
-
-### Phase 1 — Core Resources (MVP)
-
-**Effort:** ~2-3 days
-**Value:** Immediate cross-client access to specrails knowledge
-
-| Deliverable | Description |
-|-------------|-------------|
-| MCP server scaffold | TypeScript server with stdio transport |
-| Spec resources | Read OpenSpec specs by name |
-| Change resources | List active changes, get status |
-| Persona resources | Read VPC personas |
-| Config resource | Read project CLAUDE.md and layer rules |
-| `specrails-core mcp` CLI | Start MCP server from existing npm package |
-
-### Phase 2 — Tools & Memory
-
-**Effort:** ~2-3 days
-**Value:** Actionable intelligence from any MCP client
-
-| Deliverable | Description |
-|-------------|-------------|
-| `specrails_doctor` | Health check tool |
-| `specrails_score_feature` | VPC scoring tool |
-| `specrails_query_failures` | Failure pattern queries |
-| `specrails_query_memory` | Agent memory search |
-| `specrails_list_changes` | Change listing with filters |
-
-### Phase 3 — Hub Integration
-
-**Effort:** ~3-5 days
-**Value:** Replace rigid integration contract with dynamic MCP API
-
-| Deliverable | Description |
-|-------------|-------------|
-| Hub MCP client | specrails-hub connects as MCP client |
-| Dynamic command discovery | Hub queries available commands via MCP |
-| Real-time spec access | Hub reads specs through MCP resources |
-| Status streaming | Change progress via MCP notifications |
-
-### Phase 4 — Advanced Features
-
-**Effort:** ~3-5 days
-**Value:** Full ecosystem integration
-
-| Deliverable | Description |
-|-------------|-------------|
-| `specrails_analyze_codebase` | Codebase analysis tool |
-| `specrails_query_backlog` | VPC-scored backlog queries |
-| Prompt templates | Review and explore prompts with context |
-| Remote transport | HTTP+SSE for multi-repo scenarios |
-
----
-
-## 8. What Stays in Claude Code (NOT in MCP)
-
-These capabilities require Claude Code's runtime and should NOT be exposed via MCP:
-
-| Capability | Reason |
-|------------|--------|
-| `/specrails:implement` pipeline | Requires Agent tool (subagent spawning) |
-| `/specrails:batch-implement` | Requires git worktree isolation |
-| Agent invocation (sr-*) | Requires Claude Code's Agent subagent system |
-| OpenSpec artifact creation | Interactive, context-heavy (requires conversation) |
-| `/specrails:setup` wizard | Multi-step interactive configuration |
-| Template substitution (write) | Modifies project files, requires user consent |
-
-**Principle:** MCP = knowledge access. Claude Code = orchestration engine.
-
----
-
-## 9. Risk Assessment
-
-| Risk | Probability | Impact | Mitigation |
-|------|-------------|--------|------------|
-| MCP protocol breaking changes | Low | Medium | Pin SDK version, follow changelog |
-| Maintenance burden (two interfaces) | Medium | Low | MCP reads same files as skills — no duplication |
-| User confusion (MCP vs commands) | Medium | Low | Clear docs: "MCP for access, commands for action" |
-| Security (exposing project data) | Low | Medium | Local stdio only (no remote by default), respect .gitignore |
-| Scope creep (adding orchestration to MCP) | Medium | High | Strict scope boundary: no write operations in Phase 1-2 |
-
----
-
-## 10. Success Metrics
-
-| Metric | Target | Measurement |
-|--------|--------|-------------|
-| Cross-client usage | 3+ MCP clients connect in first month | MCP server logs |
-| Hub integration latency | 50% reduction vs CLI spawning | Hub performance metrics |
-| Developer adoption | 20% of users configure MCP alongside commands | npm download analytics |
-| Knowledge query volume | 100+ resource reads/day across users | MCP server telemetry |
-
----
-
-## 11. Conclusion
-
-Building an MCP server for specrails-core is **strategically sound** because:
-
-1. **It opens a new distribution channel** — any MCP client becomes a specrails client
-2. **It improves hub integration** — dynamic API replaces rigid contract
-3. **It positions specrails uniquely** — only product-driven dev framework with MCP support
-4. **It's low-risk** — read-only resources, no orchestration duplication, ships with existing package
-5. **The effort is proportional** — Phase 1 MVP in 2-3 days, full implementation in ~2 weeks
-
-The key insight is that specrails-core has two layers: **knowledge** (specs, personas, memory, config) and **orchestration** (agent pipeline, worktrees, CI). MCP is the perfect fit for the knowledge layer, while Claude Code commands remain the right tool for orchestration.
-
-**Recommendation: Proceed with Phase 1 (Core Resources MVP).**

package/docs/testing/test-matrix-codex.md

@@ -1,130 +0,0 @@
-# Test Matrix — specrails Cross-Platform (Claude Code + Codex)
-
-Last updated: 2026-03-21
-Epic: [SPEA-505](/SPEA/issues/SPEA-505) — Codex Compatibility Approach B
-
-## Legend
-
-| Symbol | Meaning |
-|--------|---------|
-| ✅ | Works / tested |
-| ❌ | Not supported |
-| 🔄 | In progress (implementation pending) |
-| ⚠️ | Partial / with caveats |
-| — | Not applicable |
-
----
-
-## Feature Coverage by CLI
-
-### Installation & Provider Detection (SPEA-506)
-
-| Feature | Claude Code only | Codex only | Both CLIs | Neither CLI |
-|---------|:-:|:-:|:-:|:-:|
-| Auto-detect `claude` binary | ✅ | — | ✅ | — |
-| Auto-detect `codex` binary | — | ✅ | ✅ | — |
-| Prompt user to choose CLI (dual) | — | — | 🔄 | — |
-| Exit with clear error message | — | — | — | 🔄 |
-| Output dir `.claude/` created | ✅ | ❌ | 🔄 | — |
-| Output dir `.codex/` created | ❌ | 🔄 | 🔄 | — |
-| `CLAUDE.md` instruction file | ✅ | ❌ | 🔄 | — |
-| `AGENTS.md` instruction file | ❌ | 🔄 | 🔄 | — |
-| `--provider claude` flag override | ✅ | — | 🔄 | — |
-| `--provider codex` flag override | — | ✅ | 🔄 | — |
-
-### Skills & Commands (SPEA-507)
-
-| Feature | Claude Code | Codex |
-|---------|:-:|:-:|
-| Legacy slash commands `.claude/commands/specrails/` | ✅ | ❌ |
-| SKILL.md format `.claude/skills/sr-*/` | ✅ | ✅ |
-| `sr:implement` skill | ✅ | ✅ |
-| `sr:get-backlog-specs` skill | ✅ | ✅ |
-| `sr:compat-check` skill | ✅ | ✅ |
-| `sr:why` skill | ✅ | ✅ |
-| `sr:refactor-recommender` skill | ✅ | ✅ |
-| `sr:batch-implement` skill | ✅ | ✅ |
-| `sr:auto-propose-backlog-specs` skill | ✅ | ✅ |
-| Backward compat: slash commands still invoke correctly | ✅ | — |
-
-### Permissions Configuration (SPEA-508)
-
-| Feature | Claude Code | Codex |
-|---------|:-:|:-:|
-| `.claude/settings.json` generated | ✅ | ❌ |
-| `.codex/config.toml` generated | ❌ | 🔄 |
-| `.codex/rules/default.rules` (Starlark) generated | ❌ | 🔄 |
-| Git permission granted | ✅ | 🔄 |
-| GitHub CLI (gh) permission granted | ✅ | 🔄 |
-| Read/Write filesystem permission | ✅ | 🔄 |
-| Bash tool allowed | ✅ | 🔄 |
-
-### Agent Definitions (SPEA-509)
-
-| Agent | Claude Code (`.md`) | Codex (`.toml`) |
-|-------|:-:|:-:|
-| `sr-architect` | ✅ | 🔄 |
-| `sr-developer` | ✅ | 🔄 |
-| `sr-reviewer` | ✅ | 🔄 |
-| `sr-product-manager` | ✅ | 🔄 |
-| Prompt content identical across formats | ✅ | 🔄 |
-| YAML frontmatter valid (Claude Code) | ✅ | — |
-| TOML frontmatter valid (Codex) | — | 🔄 |
-
-### Hub Integration (SPEA-510, SPEA-511)
-
-| Feature | Claude Code | Codex |
-|---------|:-:|:-:|
-| Hub detects claude binary | ✅ | — |
-| Hub detects codex binary | — | ✅ |
-| `integration-contract.json` v2 schema valid | ✅ | ✅ |
-| Hub invokes CLI with correct args | ✅ | ✅ |
-| Hub dashboard shows CLI badge | ✅ | ✅ |
-| Hub handles "no CLI detected" state | ✅ | ✅ |
-
----
-
-## Edge Case Coverage
-
-| Scenario | Test Coverage | Notes |
-|----------|:-:|-------|
-| User has both CLIs, picks Claude Code | 🔄 | Interactive prompt or `--provider` flag |
-| User has both CLIs, picks Codex | 🔄 | Interactive prompt or `--provider` flag |
-| User has neither CLI | 🔄 | Must print install instructions |
-| Re-install after switch from claude → codex | 🔄 | Old `.claude/` must not corrupt `.codex/` |
-| Re-install after switch from codex → claude | 🔄 | Old `.codex/` must not corrupt `.claude/` |
-| Version upgrade: CLI format unchanged | ✅ | Existing regression suite covers this |
-| Version upgrade: provider mismatch | 🔄 | New behavior in SPEA-506 |
-
----
-
-## Test Files
-
-The shell-based test suite was retired in v4.2.0 when the installer
-moved to native Node. Coverage is now provided by vitest specs
-co-located with the installer source:
-
-| File | Suite | Covers |
-|------|-------|--------|
-| `src/installer/commands/init.test.ts` | Install | init flow end-to-end (Claude + Codex) |
-| `src/installer/commands/update.test.ts` | Update | update flow + reserved paths + --only |
-| `src/installer/commands/doctor.test.ts` | Doctor | health checks against fixture repos |
-| `src/installer/cli.test.ts` | CLI | Argument parsing, dispatch, exit codes |
-| `src/installer/phases/scaffold.test.ts` | Scaffold | template placement, VPC exclusion |
-| `src/installer/phases/manifest.test.ts` | Manifest | sha256 stability, sorted output, exclusions |
-| `src/installer/phases/install-config.test.ts` | Config validation | YAML round-trip + validation errors |
-| `src/installer/phases/provider-detect.test.ts` | Provider | claude vs codex resolution + Codex coming-soon error |
-| `src/installer/phases/prereqs.test.ts` | Prereqs | OSS detection + provider auth |
-| `src/installer/__tests__/reserved-paths.test.ts` | Reserved paths | profile + custom-* survival across init/update |
-
----
-
-## Acceptance Criteria
-
-Before SPEA-505 can be merged and released:
-
-1. `npm run test` — full vitest suite green (currently 168 specs).
-2. CI matrix `[ubuntu, macos, windows] × [node 20, 22]` all green.
-3. No broken placeholders: `grep -r '{{[A-Z_]*}}' .claude/agents/ .codex/agents/ 2>/dev/null` returns empty.
-4. Skills valid: every `SKILL.md` in `.claude/skills/` has required frontmatter.
-5. Agent TOML valid: every `.toml` in `.codex/agents/` is parseable TOML.

package/docs/updating.md

@@ -1,89 +0,0 @@
-# Updating
-
-SpecRails includes an update system that pulls new templates while preserving your customizations.
-
-## How updates work
-
-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/**`, provider-specific `custom-*`
-   roles, OpenSpec skills, and user MCP entries) are preserved by construction
-
-## Running an update
-
-```bash
-npx specrails-core@latest update
-```
-
-Cross-platform (macOS, Linux, Windows). No bash, no python required — the installer is native Node since v4.2.0.
-
-### What happens
-
-1. **Version check** — reads existing `.specrails/specrails-version`; aborts if no specrails install is detected
-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** — 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`)
-
-The `--only <component>` flag is recognised but currently warns and applies the full scaffold. Granular component selection is tracked as a follow-up — the Node installer's transactional behaviour makes a targeted re-apply almost equivalent to a full one for the common case (core version bump).
-
-## Dry run
-
-```bash
-npx specrails-core@latest update --dry-run
-```
-
-Prints what the update would do without writing any files. Useful for inspecting `previousVersion → currentVersion` before committing.
-
-## What gets preserved
-
-| File type | Behavior |
-|-----------|----------|
-| **Agent prompts** (`.claude/agents/sr-*.md`) | Re-written from latest templates |
-| **Custom agents** (`.claude/agents/custom-*.md`) | **Always preserved** (reserved path) |
-| **Profile JSON** (`.specrails/profiles/**`) | **Always preserved** (reserved path) |
-| **Commands** (`.claude/commands/specrails/`) | Re-written |
-| **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
-
-The Node installer is idempotent: re-running `init` (or pinning an older version with `npx specrails-core@<version> update`) restores the prior layout. Profile and custom-agent files are reserved, so nothing critical is destroyed by a forward-then-backward sequence.
-
-If you need a true point-in-time rollback, the recommended path is git: commit before updating, `git checkout` to revert.
-
----
-
-## What's next?
-
-That's the end of the docs. Here are some useful starting points:
-
-- [Getting Started](getting-started.md) — if you haven't installed yet
-- [Workflows & Commands](workflows.md) — to start using the pipeline
-- [Customization](customization.md) — to make SpecRails yours
-
----
-
-[← Customization](customization.md) · [Back to Docs](README.md)