speclore 0.1.4 → 0.1.7

package/README.en.md

@@ -6,9 +6,9 @@
 [![CI](https://github.com/cheneyzhang93/speclore/actions/workflows/ci.yml/badge.svg)](https://github.com/cheneyzhang93/speclore/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**Product-engineering collaboration for the AI coding era — turn requirements into verifiable BDD specs, and verification into an automated pipeline.**
+**Requirements-driven AI coding tool — turn requirements into verifiable BDD specs, with constrained coding, automated acceptance, and full traceability.**
 
-SpecLore transforms scattered requirements (docs, chats, verbal specs) into structured BDD `.feature` acceptance criteria, generates coding constraints for AI tools like Cursor / Claude Code / Qoder, then runs tests and produces acceptance reports. Seamless collaboration with AI clients via MCP protocol.
+SpecLore solves the core pain points of AI-assisted development: requirements scattered across docs, chats, and verbal specs; AI-generated code lacking business constraints; tests disconnected from requirements. It transforms requirements in any format into structured BDD `.feature` acceptance criteria, generates coding constraints for AI tools like Cursor / Claude Code / Qoder, then runs tests and produces acceptance reports. Seamless collaboration with AI clients via the MCP protocol.
 
 ```
 Requirements (any format) → BDD .feature → AI constraints + test scaffolding → acceptance report
@@ -22,33 +22,92 @@ Requirements (any format) → BDD .feature → AI constraints + test scaffolding
 npm install -g speclore
 ```
 
+> **Prerequisites**: Node.js 18+
+
+---
+
 ## Quick Start
 
-Three steps from zero to acceptance:
+SpecLore offers three ways to work — pick the one that fits your workflow:
+
+| Approach | Best for | Core experience |
+|----------|----------|----------------|
+| **CLI** | Terminal-oriented developers | Manual commands, full control |
+| **MCP + AI Client** (Recommended) | Cursor / Qoder / Claude Code users | Natural language conversation, AI handles the full pipeline |
+| **Hybrid** | Best of both worlds | CLI for setup, AI client for the rest |
+
+### Approach 1: CLI
+
+For developers who prefer terminal operations and precise control over each step.
 
 ```bash
-# 1. Initialize project (auto-detect AI tools, generate config)
+# 1. Initialize project (detect AI tools → write MCP config → generate config files)
 cd your-project && speclore setup
 
 # 2. Generate .feature acceptance criteria from requirements
-speclore spec "Patient registration requires phone verification, support WeChat login"
+speclore spec "Patient registration requires phone verification and WeChat login"
 
 # 3. Generate AI coding constraints + test scaffolding
 speclore code
+
+# 4. After coding in your AI client, run acceptance
+speclore verify
 ```
 
-Then code in your AI client, and run acceptance when done:
+That's it. `setup` runs only once — after that, each new requirement is just `spec` → `code` → `verify`.
+
+### Approach 2: MCP + AI Client (Recommended)
+
+If you use Cursor, Qoder, or Claude Code, this is the most natural way — conversation replaces commands.
+
+**Step 1**: Open your project in the AI client first. `setup` needs to detect the client's marker before writing MCP config (Cursor requires `.cursor/`, Qoder requires `.qoder/`, Claude Code requires `.claude/` or `CLAUDE.md`).
+
+**Step 2**: Run `speclore setup` in your project directory. It auto-detects your AI client and writes the MCP config. You **don't need to manually edit any MCP config**.
+
+**Step 3**: **Restart or reopen** your AI client so it loads the new MCP configuration.
+
+**Step 4**: Start chatting:
+
+> **You**: Help me implement patient registration with phone verification
+
+> **AI** (calls `speclore.spec`): Generated `specs/patient/register.feature` with 3 acceptance scenarios:
+> - Successful phone registration
+> - Reject invalid phone format
+> - Conflict on duplicate phone number
+
+> **AI** (calls `speclore.code`): Generated coding constraints and test scaffolding:
+> - `.qoder/rules/speclore.md` — coding constraints (with business rules)
+> - `tests/patient/register.test.ts` — test scaffolding (3 `it.skip` placeholders)
+
+> **You**: OK, I'll implement the code and tests
+
+> *(AI reads constraint rules while coding; you fill in the `it.skip` test scaffolding)*
+
+> **You**: Run acceptance
+
+> **AI** (calls `speclore.verify`): ✅ 3/3 scenarios passed (100%)
+
+No manual CLI commands needed. The AI calls SpecLore tools directly via MCP, automatically advancing the workflow state.
+
+### Approach 3: Hybrid
+
+Use CLI for initialization and requirement generation, AI client for coding and acceptance:
 
 ```bash
-speclore verify
+# CLI: initialize + generate .feature
+speclore setup
+speclore spec requirements.md
+speclore code
 ```
 
-That's it. You can also complete the entire workflow using natural language in your AI client (Cursor / Qoder / Claude Code) — `setup` already configured MCP automatically.
+Then code in your AI client, and let AI call `speclore.verify` for acceptance.
 
 ---
 
 ## Workflow
 
+SpecLore's workflow is a stateful pipeline — each step has explicit state transitions:
+
 ```
 speclore.status → speclore.spec → speclore.code → (AI codes) → speclore.verify
    check status    generate feature  constraints+scaffold   implement     verify tests
@@ -56,7 +115,7 @@ speclore.status → speclore.spec → speclore.code → (AI codes) → speclore.
    project state   → specified     → constrained     → coding     → verified
 ```
 
-Each tool returns current state and next-step guidance. Out-of-order calls produce clear errors:
+Each tool returns the current state and next-step guidance. Out-of-order calls produce clear errors:
 
 | Out-of-order scenario | Error message |
 |----------------------|---------------|
@@ -66,87 +125,77 @@ Each tool returns current state and next-step guidance. Out-of-order calls produ
 
 ---
 
-## Example
-
-A complete conversation in an AI client for "patient registration":
-
-**You**: Help me implement patient registration with phone verification
-
-**AI** (calls `speclore.spec`): Generated `specs/patient/register.feature` with 3 acceptance scenarios:
-- Successful phone registration
-- Reject invalid phone format
-- Conflict on duplicate phone number
-
-**AI** (calls `speclore.code`): Generated coding constraints and test scaffolding:
-- `.qoder/rules/speclore.md` — coding constraints (with business rules)
-- `tests/patient/register.test.ts` — test scaffolding (3 `it.skip` placeholders)
-
-**You**: OK, I'll implement the code and tests
-
-*(AI reads constraint rules while coding; you fill in the `it.skip` test scaffolding)*
+## Supported Input Formats
 
-**You**: Run acceptance
+SpecLore generates `.feature` files from any requirement source:
 
-**AI** (calls `speclore.verify`): ✅ 3/3 scenarios passed (100%)
+| Format | Example |
+|--------|---------|
+| Markdown | `speclore spec requirements.md` |
+| Word | `speclore spec design.docx` |
+| Excel | `speclore spec specs.xlsx` |
+| PDF | `speclore spec design.pdf` |
+| Image (OCR) | `speclore spec mockup.png` |
+| URL | `speclore spec https://jira.example/123` |
+| Plain text | `speclore spec "Users need password reset"` |
 
 ---
 
-## Supported Input Formats
-
-Markdown · Word · Excel · PDF · Image (OCR) · URL · Plain text
-
-```bash
-speclore spec requirements.md          # Markdown
-speclore spec design.docx              # Word
-speclore spec specs.xlsx               # Excel
-speclore spec mockup.png               # Image
-speclore spec https://jira.example/123 # URL
-speclore spec "Users need password reset"  # Plain text
-```
-
 ## Command Reference
 
 | Command | Purpose |
 |---------|---------|
-| `speclore` | Show project status |
 | `speclore setup` | Initialize project (detect AI tools → write MCP config → generate rules) |
 | `speclore spec <source>` | Requirement source → `.feature` acceptance criteria |
 | `speclore code` | `.feature` → AI coding constraints + test scaffolding |
 | `speclore verify` | Run tests → acceptance report (mapped to .feature scenarios) |
 | `speclore verify --watch` | Watch mode, auto-rerun on file changes |
 | `speclore status` | View project state, workflow progress, recommended actions |
+| `speclore init` | Scan project structure, generate context (optional — auto-runs on first spec/code call) |
 | `speclore migrate` | Migrate existing .feature files to workflow state after upgrade |
-| `speclore init` | Scan project structure, generate context file |
+| `speclore mcp add <client>` | Manually write MCP config for a specific client (cursor \| claude \| qoder) |
+| `speclore mcp remove <client>` | Manually remove MCP config from a specific client |
+| `speclore mcp list` | Show MCP configuration status for all clients |
 | `speclore teardown` | Uninstall cleanup |
 
-## MCP Tools
+---
+
+## MCP Integration
 
-SpecLore provides 4 MCP tools, called by AI clients via MCP protocol:
+SpecLore provides 4 MCP tools that AI clients can call directly:
 
-| Tool | Purpose | State change |
-|------|---------|-------------|
+| MCP Tool | Purpose | State change |
+|----------|---------|-------------|
 | `speclore.status` | Project status + recommended actions | — |
 | `speclore.spec` | Requirements → .feature | → `specified` |
 | `speclore.code` | .feature → constraints + test scaffolding | → `constrained` |
 | `speclore.verify` | Tests → acceptance report | → `verified` |
 
-Every tool response includes a `workflow` field (`currentState` + `nextStep`) to guide AI through the correct sequence.
+`speclore setup` auto-detects your AI client and writes the corresponding MCP config (only for clients actually detected):
+
+| AI Client | Detection marker | MCP Config File |
+|-----------|-----------------|----------------|
+| Cursor | `.cursor/` directory exists | `.cursor/mcp.json` |
+| Claude Code | `.claude/` directory or `CLAUDE.md` exists | `.mcp.json` (project root) |
+| Qoder | `.qoder/` directory exists | `.qoder/mcp.json` |
 
-## Supported AI Clients
+**Manual MCP configuration**: If `setup` did not detect your AI client, configure it manually:
 
-| Client | Config file | Constraint rules file |
-|--------|------------|----------------------|
-| Cursor | `.cursor/mcp.json` | `.cursor/rules/speclore.mdc` |
-| Claude Code | `.mcp.json` | `.claude/rules/speclore.md` |
-| Qoder | `.qoder/mcp.json` | `.qoder/rules/speclore.md` |
+```bash
+speclore mcp add cursor   # Write MCP config for Cursor (auto-creates .cursor/)
+speclore mcp add claude   # Write MCP config for Claude Code
+speclore mcp add qoder    # Write MCP config for Qoder (auto-creates .qoder/)
+speclore mcp remove qoder # Remove MCP config from Qoder
+speclore mcp list         # Show MCP config status for all clients
+```
 
-`speclore setup` auto-detects and configures.
+Every MCP tool response includes a `workflow` field (`currentState` + `nextStep`) to guide the AI through the correct sequence.
 
 ---
 
 ## Configuration
 
-Core config in `.speclore/config.yaml` (generated by `setup`):
+Core config in `.speclore/config.yaml` (generated by `speclore setup`):
 
 ```yaml
 verify:
@@ -198,7 +247,7 @@ verify:
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────┐
+──────────────────────────────────────────────────────┐
 │                  CLI / MCP Server                      │
 ├──────────┬──────────┬──────────┬──────────┬──────────┤
 │ Ingest   │ Feature  │Constraint│ Verify   │ Context  │
@@ -218,11 +267,13 @@ verify:
 
 | Doc | Description |
 |-----|-------------|
-| [Configuration](docs/configuration.md) | Full `config.yaml` reference, Profile modes, all CLI commands |
-| [MCP Tools](docs/mcp-reference.md) | Complete I/O for 4 MCP tools, workflow guards, auto-init & migration |
-| [Test Mapping](docs/test-mapping.md) | Three ways to map test results back to .feature scenarios |
-| [Plugin Development](docs/plugin-guide.md) | Build and publish Reader / Writer / Parser plugins |
-| [Product Spec](docs/product-spec.md) | Full product technical specification |
+| [Getting Started](docs/en/guide/getting-started.md) | Complete tutorial with all three usage approaches |
+| [Workflow](docs/en/guide/workflow.md) | State machine-driven workflow guide |
+| [Configuration](docs/en/reference/configuration.md) | Full `config.yaml` reference, Profile modes, all CLI commands |
+| [MCP Tools](docs/en/reference/mcp-tools.md) | Complete I/O for 4 MCP tools, workflow guards, auto-init & migration |
+| [Test Mapping](docs/en/reference/test-mapping.md) | Three ways to map test results back to .feature scenarios |
+| [Plugin Development](docs/en/advanced/plugin-guide.md) | Build and publish Reader / Writer / Parser plugins |
+| [Product Spec](docs/en/advanced/architecture.md) | Full product technical specification |
 
 ---
 
@@ -231,8 +282,8 @@ verify:
 ```bash
 git clone https://github.com/cheneyzhang93/speclore.git
 cd speclore && pnpm install && pnpm build
-pnpm test       # 333 tests
-pnpm dev        # watch mode
+pnpm test       # Run tests
+pnpm dev        # Watch mode
 ```
 
 ## License

package/README.md

@@ -6,9 +6,9 @@
 [![CI](https://github.com/cheneyzhang93/speclore/actions/workflows/ci.yml/badge.svg)](https://github.com/cheneyzhang93/speclore/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**AI 编码时代的产研协同工具 — 把需求变成可验收的 BDD 规格，把验收变成自动化流水线。**
+**需求驱动的 AI 编码工具 — 把需求变成可验收的 BDD 规格，让 AI 编码有约束、有验收、可追溯。**
 
-SpecLore 将散落在文档、聊天、口头中的需求，转化为结构化的 BDD `.feature` 验收标准，再为 Cursor / Claude Code / Qoder 等 AI 编码工具生成编码约束，最后自动运行测试并生成验收报告。全程通过 MCP 协议与 AI 客户端无缝协作。
+SpecLore 解决 AI 编码时代的核心痛点：需求散落在文档、聊天和口头沟通中，AI 生成的代码缺乏业务约束，测试与需求脱节。它将任意格式的需求转化为结构化 BDD `.feature` 验收标准，为 Cursor / Claude Code / Qoder 等 AI 编码工具生成编码约束，最后自动运行测试并生成验收报告。全程通过 MCP 协议与 AI 客户端无缝协作。
 
 ```
 需求（任意格式）→ BDD .feature → AI 编码约束 + 测试骨架 → 测试验收报告
@@ -22,12 +22,26 @@ SpecLore 将散落在文档、聊天、口头中的需求，转化为结构化
 npm install -g speclore
 ```
 
+> **前提条件**：Node.js 18+
+
+---
+
 ## 快速开始
 
-三步从零到验收：
+SpecLore 提供三种使用方式，根据你的工作习惯选择：
+
+| 方式 | 适合谁 | 核心体验 |
+|------|--------|---------|
+| **方式一：CLI 命令行** | 习惯终端操作的开发者 | 手动执行命令，完全掌控流程 |
+| **方式二：MCP + AI 客户端**（推荐） | 使用 Cursor / Qoder / Claude Code 的开发者 | 用自然语言对话，AI 自动完成全流程 |
+| **方式三：混合使用** | 两者都想要的开发者 | CLI 做初始化，AI 客户端做后续操作 |
+
+### 方式一：CLI 命令行
+
+适合喜欢终端操作、需要精确控制每一步的开发者。
 
 ```bash
-# 1. 初始化项目（自动检测 AI 工具，生成配置）
+# 1. 初始化项目（检测 AI 工具 → 写入 MCP 配置 → 生成配置文件）
 cd your-project && speclore setup
 
 # 2. 从需求生成 .feature 验收标准
@@ -35,20 +49,65 @@ speclore spec "患者注册需要手机号验证，支持微信登录"
 
 # 3. 生成 AI 编码约束 + 测试骨架
 speclore code
+
+# 4. 在 AI 客户端中编码后，运行验收
+speclore verify
 ```
 
-然后在 AI 客户端中编码，完成后运行验收：
+就这么简单。`setup` 只需执行一次，之后每个新需求只需 `spec` → `code` → `verify` 三步。
+
+### 方式二：MCP + AI 客户端（推荐）
+
+如果你使用 Cursor、Qoder 或 Claude Code，这是最自然的方式 — 用对话代替命令。
+
+**第一步**：先用 AI 客户端打开项目。`setup` 需要检测到客户端标志才能写入 MCP 配置（Cursor 需要 `.cursor/`，Qoder 需要 `.qoder/`，Claude Code 需要 `.claude/` 或 `CLAUDE.md`）。
+
+**第二步**：在项目目录运行 `speclore setup`，它会自动检测已打开的 AI 客户端并写入 MCP 配置。你**不需要手动编辑任何 MCP 配置**。
+
+**第三步**：**重启或重新打开** AI 客户端，让它加载新的 MCP 配置。
+
+**第四步**：直接对话：
+
+> **你**：帮我实现患者注册功能，需要手机号验证
+
+> **AI**（自动调用 `speclore.spec`）：已生成 `specs/patient/register.feature`，包含 3 个验收场景：
+> - 手机号注册成功
+> - 手机号格式错误时拒绝
+> - 重复手机号时提示冲突
+
+> **AI**（自动调用 `speclore.code`）：已生成编码约束和测试骨架：
+> - `.qoder/rules/speclore.md` — 编码约束（含业务规则）
+> - `tests/patient/register.test.ts` — 测试骨架（3 个 `it.skip`）
+
+> **你**：好的，我来实现代码和测试
+
+> *（AI 编码时自动读取约束规则，你填充测试骨架中的 `it.skip`）*
+
+> **你**：运行验收
+
+> **AI**（调用 `speclore.verify`）：✅ 3/3 场景通过 (100%)
+
+全程无需手动执行任何 CLI 命令。AI 通过 MCP 协议直接调用 SpecLore 的工具，自动推进工作流状态。
+
+### 方式三：混合使用
+
+用 CLI 做初始化和需求生成，用 AI 客户端做编码和验收：
 
 ```bash
-speclore verify
+# CLI：初始化 + 生成 .feature
+speclore setup
+speclore spec requirements.md
+speclore code
 ```
 
-就这么简单。也可以在 AI 客户端（Cursor / Qoder / Claude Code）中用自然语言完成整个流程 — `setup` 已自动配置好 MCP。
+然后在 AI 客户端中编码，最后让 AI 调用 `speclore.verify` 运行验收。
 
 ---
 
 ## 工作流
 
+SpecLore 的工作流是一个有状态流水线，每个步骤都有明确的状态转换：
+
 ```
 speclore.status → speclore.spec → speclore.code → (AI 编码) → speclore.verify
    查看状态        生成 feature    生成约束+骨架      实现代码      验收测试
@@ -56,7 +115,7 @@ speclore.status → speclore.spec → speclore.code → (AI 编码) → speclore
    项目状态      → specified     → constrained     → coding     → verified
 ```
 
-每个工具调用后返回当前状态和下一步指引，乱序调用自动报错：
+每个工具调用后返回当前状态和下一步指引，乱序调用会自动报错：
 
 | 乱序场景 | 报错信息 |
 |---------|---------|
@@ -66,87 +125,77 @@ speclore.status → speclore.spec → speclore.code → (AI 编码) → speclore
 
 ---
 
-## 示例
-
-以「患者注册」为例，在 AI 客户端中的完整对话：
-
-**你**：帮我实现患者注册功能，需要手机号验证
-
-**AI**（自动调用 `speclore.spec`）：已生成 `specs/patient/register.feature`，包含 3 个验收场景：
-- 手机号注册成功
-- 手机号格式错误时拒绝
-- 重复手机号时提示冲突
-
-**AI**（自动调用 `speclore.code`）：已生成编码约束和测试骨架：
-- `.qoder/rules/speclore.md` — 编码约束（含业务规则）
-- `tests/patient/register.test.ts` — 测试骨架（3 个 `it.skip`）
-
-**你**：好的，我来实现代码和测试
-
-*（AI 编码时自动读取约束规则，你填充测试骨架中的 `it.skip`）*
+## 支持的输入格式
 
-**你**：运行验收
+SpecLore 可以从任意格式的需求来源生成 `.feature` 文件：
 
-**AI**（调用 `speclore.verify`）：✅ 3/3 场景通过 (100%)
+| 格式 | 示例 |
+|------|------|
+| Markdown | `speclore spec requirements.md` |
+| Word | `speclore spec design.docx` |
+| Excel | `speclore spec specs.xlsx` |
+| PDF | `speclore spec design.pdf` |
+| 图片 (OCR) | `speclore spec mockup.png` |
+| URL | `speclore spec https://jira.example/123` |
+| 直接文本 | `speclore spec "用户需要能重置密码"` |
 
 ---
 
-## 支持的输入格式
-
-Markdown · Word · Excel · PDF · 图片 (OCR) · URL · 直接文本
-
-```bash
-speclore spec requirements.md          # Markdown
-speclore spec design.docx              # Word
-speclore spec specs.xlsx               # Excel
-speclore spec mockup.png               # 图片
-speclore spec https://jira.example/123 # URL
-speclore spec "用户需要能重置密码"       # 直接文本
-```
-
 ## 命令速查
 
 | 命令 | 用途 |
 |------|------|
-| `speclore` | 显示项目状态 |
 | `speclore setup` | 初始化项目（检测 AI 工具 → 写入 MCP 配置 → 生成规则） |
 | `speclore spec <source>` | 需求来源 → `.feature` 验收标准 |
 | `speclore code` | `.feature` → AI 编码约束 + 测试骨架 |
 | `speclore verify` | 运行测试 → 验收报告（映射到 .feature 场景） |
 | `speclore verify --watch` | 监听模式，文件变化自动重跑验收 |
 | `speclore status` | 查看项目状态、工作流进度、推荐操作 |
+| `speclore init` | 扫描项目结构，生成上下文（可选，首次 spec/code 时自动执行） |
 | `speclore migrate` | 升级后迁移已有 .feature 文件到工作流状态 |
-| `speclore init` | 扫描项目结构，生成上下文文件 |
+| `speclore mcp add <client>` | 手动为指定客户端写入 MCP 配置（cursor \| claude \| qoder） |
+| `speclore mcp remove <client>` | 手动从指定客户端移除 MCP 配置 |
+| `speclore mcp list` | 查看所有客户端的 MCP 配置状态 |
 | `speclore teardown` | 卸载清理 |
 
-## MCP 工具
+---
+
+## MCP 集成
 
-SpecLore 提供 4 个 MCP 工具，AI 客户端通过 MCP 协议直接调用：
+SpecLore 通过 MCP（Model Context Protocol）为 AI 客户端提供 4 个工具，AI 可以直接调用：
 
-| 工具 | 用途 | 状态变化 |
-|------|------|---------|
+| MCP 工具 | 用途 | 状态变化 |
+|----------|------|---------|
 | `speclore.status` | 项目状态 + 推荐操作 | — |
 | `speclore.spec` | 需求 → .feature | → `specified` |
 | `speclore.code` | .feature → 约束 + 测试骨架 | → `constrained` |
 | `speclore.verify` | 测试 → 验收报告 | → `verified` |
 
-每个工具响应包含 `workflow` 字段（`currentState` + `nextStep`），引导 AI 按正确顺序推进。
+`speclore setup` 会自动检测已打开的 AI 客户端并写入对应的 MCP 配置（只为实际检测到的客户端写入）：
+
+| AI 客户端 | 检测标志 | MCP 配置文件 |
+|-----------|---------|-------------|
+| Cursor | `.cursor/` 目录存在 | `.cursor/mcp.json` |
+| Claude Code | `.claude/` 目录或 `CLAUDE.md` 存在 | `.mcp.json`（项目根目录） |
+| Qoder | `.qoder/` 目录存在 | `.qoder/mcp.json` |
 
-## 支持的 AI 客户端
+**手动配置 MCP**：如果 `setup` 未检测到你的 AI 客户端，可以手动配置：
 
-| 客户端 | 配置文件 | 约束规则文件 |
-|--------|---------|-------------|
-| Cursor | `.cursor/mcp.json` | `.cursor/rules/speclore.mdc` |
-| Claude Code | `.mcp.json` | `.claude/rules/speclore.md` |
-| Qoder | `.qoder/mcp.json` | `.qoder/rules/speclore.md` |
+```bash
+speclore mcp add cursor   # 为 Cursor 写入 MCP 配置（自动创建 .cursor/）
+speclore mcp add claude   # 为 Claude Code 写入 MCP 配置
+speclore mcp add qoder    # 为 Qoder 写入 MCP 配置（自动创建 .qoder/）
+speclore mcp remove qoder # 从 Qoder 移除 MCP 配置
+speclore mcp list         # 查看所有客户端的 MCP 配置状态
+```
 
-`speclore setup` 自动检测并配置。
+每个 MCP 工具响应包含 `workflow` 字段（`currentState` + `nextStep`），引导 AI 按正确顺序推进工作流。
 
 ---
 
 ## 配置
 
-`setup` 生成的 `.speclore/config.yaml` 核心配置：
+`speclore setup` 生成的 `.speclore/config.yaml` 核心配置：
 
 ```yaml
 verify:
@@ -218,11 +267,13 @@ verify:
 
 | 文档 | 说明 |
 |------|------|
-| [配置参考](docs/configuration.md) | `config.yaml` 完整配置、Profile 模式、所有 CLI 命令详细参考 |
-| [MCP 工具参考](docs/mcp-reference.md) | 4 个 MCP 工具完整 I/O、流程强约束、自动初始化与迁移 |
-| [测试映射](docs/test-mapping.md) | 测试结果与 .feature 场景的三种映射方式 |
-| [插件开发](docs/plugin-guide.md) | Reader / Writer / Parser 插件开发与发布 |
-| [产品技术规格](docs/product-spec.md) | 完整产品技术规格书 |
+| [快速开始](docs/guide/getting-started.md) | 完整入门教程，三种使用方式详解 |
+| [工作流](docs/guide/workflow.md) | 状态机驱动的完整工作流说明 |
+| [配置参考](docs/reference/configuration.md) | `config.yaml` 完整配置、Profile 模式、所有 CLI 命令详细参考 |
+| [MCP 工具参考](docs/reference/mcp-tools.md) | 4 个 MCP 工具完整 I/O、流程强约束、自动初始化与迁移 |
+| [测试映射](docs/reference/test-mapping.md) | 测试结果与 .feature 场景的三种映射方式 |
+| [插件开发](docs/advanced/plugin-guide.md) | Reader / Writer / Parser 插件开发与发布 |
+| [产品技术规格](docs/advanced/architecture.md) | 完整产品技术规格书 |
 
 ---
 
@@ -231,7 +282,7 @@ verify:
 ```bash
 git clone https://github.com/cheneyzhang93/speclore.git
 cd speclore && pnpm install && pnpm build
-pnpm test       # 333 tests
+pnpm test       # 运行测试
 pnpm dev        # watch 模式
 ```