@coralai/sps-cli 0.58.0 → 0.58.1

package/README-CN.md

@@ -60,6 +60,29 @@ sps setup                            # 交互式向导（首次必跑）
 
 要把 sps-cli 作为长驻服务跑（Console 网页 + IM 网关 + 流水线），走**源码构建**部署。下面步骤 AI 或运维照着从头到尾即可完成。
 
+### 装完 npm 包后必补(否则跑不起来)
+
+`npm install -g @coralai/sps-cli` **只给你 `sps` 命令**。要真正跑起来,还得补:
+
+1. **Node ≥ 22**(代码图谱用 `node:sqlite`;CLI 其余 ≥ 18 即可)。
+2. **`claude` CLI 在 PATH** —— worker 后端连的就是它(`sps doctor` 检查 `which claude`):
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   ```
+3. **Claude 鉴权**(三选一):`claude` 登录订阅(Pro / Max → `~/.claude/.credentials.json`)、或设 `ANTHROPIC_API_KEY`、或让 worker 指向第三方 Anthropic 端点 / codex-proxy。
+4. **跑一次 `sps setup`** —— 建 `~/.coral/`、全局装 ACP 传输层 `@agentclientprotocol/claude-agent-acp`、写 `~/.coral/env`。
+5. **git** —— 流水线在目标 repo 里开 worktree/分支。
+
+**模型/订阅配置在包外**(secret,本机自配):官方订阅(`claude` 登录)开箱即用;第三方端点写 `~/.coral/game-platform/providers.json`;worker 默认模型 `~/.coral/agents/smartarrange.json`(可省)。
+
+**自检机器是否就绪**:
+```bash
+sps project init demo
+sps doctor demo --fix     # 查 Node、claude 在不在 PATH、目录、配置——缺啥直接报
+```
+
+按需补(用到才配):ChatGPT 订阅 worker → `sps codex-proxy install && sps codex-proxy auth`;IM 网关 → `~/.coral/im/config.json`;远程 Console → `SPS_CONSOLE_TOKEN`。
+
 ### 依赖
 
 - **Node ≥ 22** + npm（代码图谱用 `node:sqlite` 的 `DatabaseSync`,需 Node ≥ 22;CLI 其余部分 ≥ 18 即可）。

package/README.md

@@ -60,6 +60,29 @@ Re-run safe with `sps setup --force` (keeps existing values as defaults). After
 
 For running sps-cli as long-lived services (Console web UI + IM gateway + pipeline) on a server, deploy **from source**. An AI or operator can follow the steps below end to end.
 
+### After installing the npm package — required extras
+
+`npm install -g @coralai/sps-cli` gives you the `sps` CLI **only**. To actually run it, also provide:
+
+1. **Node ≥ 22** (code-graph uses `node:sqlite`; the rest of the CLI runs on ≥ 18).
+2. **Claude Code CLI in PATH** — the worker backend drives it (`sps doctor` checks `which claude`):
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   ```
+3. **Claude auth** (one of): log in with `claude` (Pro / Max → `~/.claude/.credentials.json`), or set `ANTHROPIC_API_KEY`, or point workers at a third-party Anthropic endpoint / codex-proxy.
+4. **Run `sps setup` once** — scaffolds `~/.coral/`, installs the ACP transport `@agentclientprotocol/claude-agent-acp` globally, writes `~/.coral/env`.
+5. **git** — pipelines run worktrees/branches inside the target repo.
+
+**Model / subscription config lives outside the package** (secrets, per machine): the official subscription (`claude` login) works out of the box; third-party endpoints go in `~/.coral/game-platform/providers.json`; the worker's default model in `~/.coral/agents/smartarrange.json` (optional).
+
+**Verify the box is ready**:
+```bash
+sps project init demo
+sps doctor demo --fix     # checks Node, claude-in-PATH, dirs, config — reports what's missing
+```
+
+Per-feature extras (only if used): ChatGPT-subscription worker → `sps codex-proxy install && sps codex-proxy auth`; IM gateway → `~/.coral/im/config.json`; remote Console → `SPS_CONSOLE_TOKEN`.
+
 ### Dependencies
 
 - **Node ≥ 22** and npm (the code-graph feature imports `node:sqlite` — `DatabaseSync` — which requires Node ≥ 22; the rest of the CLI runs on ≥ 18).

package/dist/shared/runtimeSchemas.d.ts

@@ -37,8 +37,6 @@ export declare const ProjectConfSchema: z.ZodObject<{
     PROJECT_DIR: z.ZodString;
     PM_TOOL: z.ZodDefault<z.ZodEnum<{
         markdown: "markdown";
-        github: "github";
-        gitlab: "gitlab";
     }>>;
     AGENT_PROVIDER: z.ZodDefault<z.ZodString>;
     MAX_WORKERS: z.ZodDefault<z.ZodString>;

package/dist/shared/runtimeSchemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeSchemas.d.ts","sourceRoot":"","sources":["../../src/shared/runtimeSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,kBAAkB;;;;;;iBAW7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAK9D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAYhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;iBAc5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BhC,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG1B,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAoB3E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBAY7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"runtimeSchemas.d.ts","sourceRoot":"","sources":["../../src/shared/runtimeSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,kBAAkB;;;;;;iBAW7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAK9D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAYhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;iBAgB5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BhC,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG1B,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAoB3E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBAY7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/shared/runtimeSchemas.js

@@ -46,7 +46,9 @@ export const CardFrontmatterSchema = z.object({
 export const ProjectConfSchema = z.object({
     PROJECT_NAME: z.string().min(1),
     PROJECT_DIR: z.string().min(1),
-    PM_TOOL: z.enum(['markdown', 'gitlab', 'github']).default('markdown'),
+    // v0.42+：卡片/PM 只有 markdown 后端(Plane/Trello 已移除;GitLab 是 repo/MR 侧,非 PM)。
+    // 收窄枚举 → 非法值在配置校验期即报错,而非运行时 createTaskBackend 才抛。
+    PM_TOOL: z.enum(['markdown']).default('markdown'),
     AGENT_PROVIDER: z.string().default('claude'),
     MAX_WORKERS: z
         .string()

package/dist/shared/runtimeSchemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeSchemas.js","sourceRoot":"","sources":["../../src/shared/runtimeSchemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtimeSchemas.js","sourceRoot":"","sources":["../../src/shared/runtimeSchemas.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-cli",
-  "version": "0.58.0",
+  "version": "0.58.1",
   "description": "SPS CLI — AI-driven development pipeline orchestrator",
   "type": "module",
   "main": "dist/main.js",
@@ -27,6 +27,8 @@
     "project-template",
     "monitor-skills",
     "profiles",
+    "skills/sps-pipeline",
+    "skills/sps-memory",
     "README.md",
     "README-CN.md"
   ],

package/skills/sps-memory/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: sps-memory
+description: 项目级记忆 —— 续作/动手前召回历史经验,完成时记录可复用精华。统一走 `sps memory` CLI,后端(本地文件 / agentmemory / 自定义)由系统全局配置,你无需关心是哪个。召回触发:任务涉及已有项目、用户说"继续/上次/之前"、涉及代码仓库/部署路径/架构决策、需保持用户偏好。记录触发:产生新架构决策、任务/状态变化、发现新约束、用户纠正了你、产生可复用解决方案。(🪸 Coral SPS)
+---
+
+# 项目记忆(sps-memory)
+
+统一 CLI 读写,**后端无关**(本地文件 / agentmemory / 自定义由系统全局配置)。
+项目名在环境变量 `$SPS_PROJECT`。开工时系统已自动召回一批注入上文;工作中按下列规则**主动**使用。
+
+## 召回(读)
+
+**何时(满足任一,就先召回再动手):**
+- 任务涉及已有项目
+- 用户说"继续 / 上次 / 之前"
+- 涉及代码仓库、部署路径、架构决策
+- 需要保持用户偏好
+
+```bash
+sps memory search "$SPS_PROJECT" "<关键词,如 部署路径 / 某模块架构 / 某引擎的坑>"
+```
+返回相关记忆标题;需要细节再据此深入(读文件 / 再检索)。
+
+## 记录(写)
+
+**何时(满足任一,就记一条):**
+- 产生了新的架构决策
+- 任务 / 状态发生变化
+- 发现了新约束
+- 用户纠正了你
+- 产生了可复用的解决方案
+
+```bash
+sps memory add "$SPS_PROJECT" --type <lesson|decision|convention|reference> \
+  --name "<一句话标题>" --body "<要点>"
+```
+- `decision` 架构/技术决策 · `lesson` 踩过的坑/教训 · `convention` 约定/规范 · `reference` 参考/路径
+- 只记**非显然、可复用**的精华,别记流水账。
+- 写入是**提议**——系统会事后去重和审计,轻微重复不必担心。
+
+## 不要记
+
+代码结构 / 文件路径(Read·Glob 可得)· git 历史 · 临时调试态 · CLAUDE.md/docs 已有的 · 卡/任务状态。
+**不确定就不写** —— 空增长比不增长更糟。
+
+## 诚实
+
+- 不编造;只记用户说过的或你真发现的。
+- 记错了就改 / 删,别在矛盾上再堆一条。
+
+记忆服务不可用时跳过,不阻塞任务。

package/skills/sps-pipeline/SKILL.md

@@ -0,0 +1,476 @@
+---
+name: sps-pipeline
+description: |
+  SPS pipeline & project management — set up projects, configure YAML pipelines, manage
+  task cards, drive worker lifecycle, run web console, monitor health. Use when the user
+  asks to "create a pipeline", "set up a project", "add tasks", "start the pipeline",
+  "open console", "check status", or anything in the SPS workflow. (🪸 Coral SPS)
+---
+
+# SPS Pipeline (v0.51.x — Single-Worker Card Pipeline + Web Console + Wiki)
+
+SPS drives an AI worker through task cards. **One worker, one card at a time, serial
+execution.** Each card walks one or more YAML-defined stages (e.g. `develop → review →
+Done`); failure halts until the user resolves it. v0.50 added a 4-layer service
+architecture; v0.51 added per-project Wiki knowledge base injection.
+
+## Two ways to operate
+
+| Mode | Command | Use when |
+|---|---|---|
+| **Web Console** (preferred) | `sps console` | Daily work — kanban, logs, worker dashboard, project create, conf editor, pipeline editor, chat with agent, all in one UI |
+| **CLI** | `sps tick / card / worker / wiki / …` | Scripting, troubleshooting, headless servers |
+
+Console listens on `127.0.0.1:4311` by default; opens browser auto. Single-instance
+guard via `~/.coral/console.lock`.
+
+---
+
+## 1. First-time setup
+
+```bash
+npm install -g @coralai/sps-cli      # latest (currently 0.51.x)
+sps setup                            # ⭐ MUST RUN: interactive wizard
+```
+
+`sps setup` does:
+1. Creates `~/.coral/` directory tree (`projects/`, `memory/user/`, `memory/agents/`).
+2. Copies bundled skills → `~/.coral/skills/`.
+3. Interactively writes `~/.coral/env` (Git remote token, Matrix credentials, etc.).
+4. Symlinks user skills → `~/.coral/.claude/skills/` and `~/.claude/skills/`.
+5. Installs `@agentclientprotocol/claude-agent-acp` globally if missing.
+
+Re-run safe: `sps setup --force` keeps existing values as defaults.
+
+**No separate console config**. Console reads `~/.coral/env` + per-project conf.
+
+---
+
+## 2. Create a project
+
+### Option A — Console (recommended)
+Open `sps console` → `/projects/new` → fill form → submit. Form provides:
+- Project name + repo path
+- Git toggle (worker commits + pushes? off for non-code projects)
+- **Wiki toggle** (v0.51+): scaffolds `wiki/` + writes `WIKI_ENABLED=true` to conf
+- Merge branch, max workers, ACK timeout, Matrix room
+
+### Option B — Interactive CLI
+```bash
+sps project init <name>      # asks the same questions on tty
+```
+
+### What gets created
+
+```
+~/.coral/projects/<name>/
+├── conf                      # your active settings (private, mode 600)
+├── conf.example              # full reference with comments (read-only docs)
+├── pipelines/
+│   ├── project.yaml          # default 1-stage pipeline (develop → Done)
+│   └── sample.yaml.example   # heavily-commented YAML reference
+├── pipeline_order.json       # active pipeline pointer
+├── runtime/
+│   ├── state.json            # worker slot + active card state (machine-managed)
+│   └── tick.lock             # lock file
+├── logs/                     # per-tick logs
+├── pm_meta/                  # markdown card backend metadata
+└── cards/                    # state subdirs created on first use
+    └── seq.txt
+```
+
+Plus, in the **target repo** (PROJECT_DIR):
+- `.claude/CLAUDE.md` — worker rules + (if wiki=on) wiki SOP block
+- `.claude/skills/` — symlinked from `~/.coral/skills/`
+- `.claude/settings.local.json` — Claude Code local config
+- `wiki/` (if wiki=on) — knowledge base scaffold
+- `ATTRIBUTION.md` (if wiki=on) — borrows declaration
+
+---
+
+## 3. Pipeline YAML
+
+**Location**: `~/.coral/projects/<name>/pipelines/project.yaml`
+
+**Single source of truth** for stages, profiles, transitions. Edit this file (or in
+console at `/projects/<name>` pipeline editor) to customize.
+
+### Critical YAML rules
+
+1. **`mode: project`** — orchestrate cards through states. (`mode: steps` is for
+   one-shot custom pipelines via `sps pipeline run <name>`.)
+2. **`on_complete` of each stage points to the next stage's target state.** No
+   skipping, no looping.
+3. **Last stage's `on_complete: "move_card Done"`.**
+4. **Don't write `agent:` field** — it's accepted for back-compat but ignored.
+   Claude (via ACP) is the only supported worker as of v0.38.0.
+5. **Single worker, serial execution** — set `MAX_CONCURRENT_WORKERS` in conf if
+   you want >1 slot reserved, but cards still run one at a time.
+6. **Failure halts pipeline** by default (`on_fail.halt: true`). Worker labels card
+   `NEEDS-FIX`; user must resolve before next card runs.
+
+### Templates
+
+**Simple (1 stage):**
+```yaml
+mode: project
+git: true
+stages:
+  - name: develop
+    on_complete: "move_card Done"
+    on_fail:
+      action: "label NEEDS-FIX"
+      halt: true
+```
+
+**With review (2 stages):**
+```yaml
+mode: project
+git: true
+stages:
+  - name: develop
+    profile: fullstack
+    on_complete: "move_card Review"
+    on_fail: { action: "label NEEDS-FIX", halt: true }
+  - name: review
+    profile: reviewer
+    on_complete: "move_card Done"
+    on_fail: { action: "label REVIEW-FAILED", halt: true }
+```
+
+**Non-git (data / docs project):**
+```yaml
+mode: project
+git: false
+stages:
+  - name: process
+    profile: tax-worker
+    on_complete: "move_card Done"
+    on_fail: { action: "label PROCESS-FAILED", halt: true }
+```
+
+### YAML field reference
+
+| Field | Required | Notes |
+|---|---|---|
+| `mode` | yes | `project` (state machine) or `steps` (one-shot, run via `sps pipeline run`) |
+| `git` | no | `true` (default) — worker commits + pushes / `false` — no git ops |
+| `stages` | yes | Array |
+| `stages[].name` | yes | Unique within file |
+| `stages[].profile` | no | Skill profile (e.g. `fullstack` / `reviewer` / `tax-worker`); falls back to `DEFAULT_WORKER_SKILLS` in conf |
+| `stages[].on_complete` | yes | `"move_card <NextState>"` |
+| `stages[].on_fail.action` | no | `"label NEEDS-FIX"` etc. |
+| `stages[].on_fail.halt` | no | default `true` |
+| `stages[].on_fail.comment` | no | Comment text |
+| `stages[].timeout` | no | `30s` / `5m` / `2h` (rare) |
+
+`trigger` and `card_state` are auto-derived per stage from the position. Don't set
+manually.
+
+### Custom pipelines (mode: steps)
+
+For one-shot scripted runs (e.g. canary deploy, bulk ingest), use `mode: steps` and
+invoke via `sps pipeline run <pipeline-name> "<prompt>"`. Out of scope for normal
+card pipelines; see `sample.yaml.example` for syntax.
+
+---
+
+## 4. Card state machine
+
+```
+v0.51.9 起：
+
+Backlog → Todo → Inprogress → [QA / Review] → Done
+   ↑↓
+Planning（用户手动暂存；不自动派发）
+                                  ↓ fail
+                            NEEDS-FIX (halt)
+```
+
+Default states (configurable in YAML `pm.card_states`):
+- **Planning** — v0.51.10+：人工暂存 / 草稿。**console "新卡片" 表单**默认入此状态；用户拖到 Backlog 才会跑。
+- **Backlog** — **`sps card add`（CLI / agent）**默认入此状态；StageEngine 抢卡执行。
+- **Todo** — StageEngine 已 prep（建分支 / worktree），下次 tick 派 worker
+- **Inprogress** — worker active
+- **QA** (or **Review**) — code complete, awaiting human/auto verification
+- **Done** — finished
+- **Canceled** — folded into Done view (rare state)
+
+Engines walk this graph each tick. The **active stage** writes a per-slot marker
+file at `~/.coral/projects/<p>/runtime/worker-<slot>-current.json` (v0.50.21+).
+Stop hook reads this to detect which card the worker just finished.
+
+---
+
+## 5. Card management
+
+### Where new cards land — depends on caller (v0.51.10+)
+
+| 调用方 | 默认入场 state | 行为 |
+|---|---|---|
+| **`sps card add`** (CLI / Worker / agent) | **Backlog** | 下次 tick 立即被 StageEngine 抢卡跑 |
+| **Console "新卡片" 表单** | **Planning** | 暂存；用户在看板拖到 Backlog 才会跑 |
+| **`POST /api/projects/<p>/cards`** 直接调 API | **Planning** | 默认人工语义；body 传 `initialState: 'Backlog'` 立即跑 |
+
+**Agent 调 `sps card add` → 卡进 Backlog → 自动跑。** 这是 SPS 的主路径。Worker 在某个卡里需要"派生子任务"时用 `sps card add`，子任务会被下一个 tick 自动 pickup。
+
+```bash
+# Agent / Worker 主路径 — 直接进 Backlog 自动跑
+sps card add <project> "Title" "Description"
+sps card add <project> "T" "D" --skill python,backend
+
+# 想暂存（让用户审核 / 自己稍后拖派发）
+sps card add <project> "Title" "Description" --draft
+                                  # → 卡进 Planning，等手动拖到 Backlog
+```
+
+### View
+
+```bash
+sps card dashboard <project>       # CLI table
+                                   # console: /board?project=<name>
+```
+
+### Lifecycle (machine-managed, but you can intervene)
+
+```bash
+sps card mark-started <p> <seq>    # called by Claude Code UserPromptSubmit hook
+sps card mark-complete <p> <seq>   # called by Claude Code Stop hook
+sps reset <p>                      # reset all non-Done
+sps reset <p> --card 5,6,7         # reset specific seq
+sps reset <p> --all                # full reset incl. Done
+```
+
+注：`sps reset` 把卡退回 **Planning**（不是 Backlog） — 重置 = 退回人工控制，需手动拖回 Backlog 才会再跑。这是 v0.51.9 起的语义。
+
+### Card label vocabulary
+
+| Label | Meaning | Who sets |
+|---|---|---|
+| `AI-PIPELINE` | "SPS pipeline 卡" 的标记（v0.51.9+ 不再触发任何自动行为，仅识别） | `sps card add` 自动加 |
+| `STARTED-<stage>` | ACK signal — Claude received the prompt | UserPromptSubmit hook |
+| `COMPLETED-<stage>` | Worker finished a stage | Stop hook |
+| `CLAIMED` | StageEngine reserved a worker slot | Engine |
+| `NEEDS-FIX` | Worker failed; pipeline halted | Engine |
+| `BLOCKED` | External dep; pipeline skips | User |
+| `WAITING-CONFIRMATION` | Worker waiting on user input | Engine |
+| `STALE-RUNTIME` | Inprogress > timeout | MonitorEngine |
+| `ACK-TIMEOUT` | Claude never ACK'd within `WORKER_ACK_TIMEOUT_S` | MonitorEngine |
+| `skill:<name>` | Force-load specific skill | User on card |
+| `conflict:<domain>` | Serial-with-others-in-same-domain | User |
+
+---
+
+## 6. Pipeline lifecycle commands
+
+```bash
+# Run continuously (one tick spawns next via cron-like loop)
+sps tick <project>                 # foreground tick(s) — Ctrl+C to stop
+sps pipeline start <project>       # alias for tick
+sps pipeline stop <project>        # graceful stop
+sps stop <project>                 # CLI alias for stop
+sps stop --all                     # stop all running ticks
+
+# Status
+sps status                         # all projects
+sps pipeline status                # alias
+sps doctor <project>               # health check
+sps doctor <project> --fix         # auto-repair drift
+
+# One-off ticks (each engine separately, useful for cron / debugging)
+sps scheduler tick <p>             # v0.51.9 起为 no-op（dormant，保留接口）
+sps pipeline tick <p>              # full StageEngine pass
+sps qa tick <p>                    # QA → Done finalization
+sps monitor tick <p>               # health probe (ACK timeout, stale runtime)
+sps pm scan <p>                    # rebuild card index from disk
+```
+
+### Worker control
+
+```bash
+sps worker ps <project>            # list slots + PIDs
+sps worker dashboard <project>     # rich UI (also in console)
+sps worker kill <project> <seq>    # SIGKILL one slot
+sps worker launch <project> <seq>  # manual spawn (debugging)
+```
+
+### Logs
+
+```bash
+sps logs <project>                 # follow mode (default)
+sps logs <project> --err           # stderr only
+sps logs <project> --lines 50 --no-follow
+                                   # console: /logs?project=<name> (live SSE)
+```
+
+---
+
+## 7. Web Console (`sps console`)
+
+Single binary launches the web UI:
+
+```bash
+sps console                        # opens http://127.0.0.1:4311
+sps console --port 5000
+sps console --no-open
+sps console --kill                 # stop running console
+sps console --dev                  # vite dev server (development)
+```
+
+Pages:
+- `/projects` — list, summary cards
+- `/projects/new` — create project (with Wiki toggle, v0.51)
+- `/projects/<n>` — pipeline editor + conf editor + delete
+- `/board` — kanban (with **per-column scrolling**, v0.51.1+)
+- `/workers` — aggregate worker dashboard (all projects)
+- `/logs` — live SSE log viewer
+- `/skills` — user-level skill management
+- `/system` — global settings, daemon status
+- `/chat` — agent chat (multi-session, persistent)
+
+---
+
+## 8. Memory & Wiki (auto-injected into Worker prompts)
+
+| | **Memory** (`sps-memory` skill) | **Wiki** (`wiki-update` skill) |
+|---|---|---|
+| Purpose | Ad-hoc facts, user prefs, decisions, gotchas | Structured project knowledge: modules, concepts, decisions, lessons |
+| Path | `~/.coral/memory/{user,agents,projects/<p>}/` | `<repo>/wiki/` (per-project, in repo) |
+| Schema | Markdown + YAML frontmatter (`type: convention/decision/lesson/reference`) | 5 page types with zod-validated frontmatter |
+| Cross-link | None (flat index) | `[[type/Title]]` wikilinks |
+| Auto-inject | `buildFullMemoryContext` → prompt's `knowledge` section | `wikiRead` 5-layer → prompt's `wikiContext` section (only when `WIKI_ENABLED=true`) |
+| When to use | Personal style notes, "remember X" requests | Project knowledge that benefits future cards |
+
+If you're configuring a project that needs structured knowledge accumulation,
+**enable Wiki** at create time. For ad-hoc facts only, memory alone is enough.
+
+CLI helpers:
+```bash
+sps memory list <p>
+sps memory context <p>             # preview what gets injected
+sps memory add <p> --type convention --name "title" --body "content"
+
+sps wiki init <p>                  # scaffold (auto when WIKI_ENABLED=true)
+sps wiki update <p>                # source diff
+sps wiki update <p> --finalize     # flush manifest after pages written
+sps wiki check <p>                 # lint
+sps wiki read <p> "<query>"        # preview prompt injection
+sps wiki list/get/add/status       # browse / inspect
+```
+
+---
+
+## 9. Conf reference (essentials)
+
+Live at `~/.coral/projects/<name>/conf` (shell `export VAR="value"` syntax).
+
+| Field | Default | Notes |
+|---|---|---|
+| `PROJECT_NAME` | (required) | Internal id |
+| `PROJECT_DIR` | (required) | Repo absolute path |
+| `GITLAB_PROJECT` | — | `user/repo` (optional, for GitLab API) |
+| `GITLAB_MERGE_BRANCH` | `main` | Worker pushes here |
+| `PM_TOOL` | `markdown` | **Only `markdown` supported as of v0.42.0**. Plane/Trello removed. Cards live in `~/.coral/projects/<n>/cards/<state>/<seq>.md` |
+| `PIPELINE_LABEL` | `AI-PIPELINE` | Marker label auto-added by `sps card add` — identifies SPS-managed cards. v0.51.9+ 不再触发自动状态提升（卡按入场 state 决定是否跑） |
+| `MR_MODE` | `none` | `none` (push direct) / `create` (open MR; needs `GITLAB_PROJECT_ID`) |
+| `WORKER_TRANSPORT` | `acp-sdk` | Fixed; do not change |
+| `MAX_CONCURRENT_WORKERS` | `1` | Slot count; cards still serial within a project |
+| `MAX_ACTIONS_PER_TICK` | `3` | New tasks claimable per tick |
+| `INPROGRESS_TIMEOUT_HOURS` | `2` | After this, MonitorEngine flags STALE-RUNTIME |
+| `WORKER_ACK_TIMEOUT_S` | `300` | Wait for STARTED-<stage> label after dispatch (5min, raised in v0.50.24) |
+| `WORKER_ACK_MAX_RETRIES` | `1` | ACK timeout retry count |
+| `MONITOR_AUTO_QA` | `true` | Auto-advance to QA on stale runtime |
+| `CONFLICT_DEFAULT` | `serial` | Fallback for cards without `conflict:` label |
+| `MATRIX_ROOM_ID` | — | Project-level Matrix override |
+| `WORKTREE_DIR` | `~/.coral/worktrees/<p>` | Worker scratch space |
+| `DEFAULT_WORKER_SKILLS` | — | Comma-separated skill list when no `profile:` and no `card.skills` |
+| `ENABLE_MEMORY` | `true` | Set `false` to skip memory write instructions in prompt |
+| **`WIKI_ENABLED`** | unset (off) | **v0.51+**: `true` enables wiki context injection + reminder block |
+| `COMPLETION_SIGNAL` | `done` | Word the Stop hook listens for |
+
+Full reference: `~/.coral/projects/<n>/conf.example` (auto-generated, comment-rich).
+
+---
+
+## 10. Architecture (4-layer, v0.50+)
+
+```
+Delivery (commands/, console/routes/)
+  → execute* / HTTP routes; thin
+Service (services/)
+  → ProjectService / ChatService / PipelineService / SkillService — Result<T> + DomainEvent
+Domain (engines/)
+  → SchedulerEngine / StageEngine / MonitorEngine / EventHandler
+Infrastructure (manager/, providers/, daemon/)
+  → WorkerManager (single worker), ACPWorkerRuntime, sessionDaemon
+```
+
+### Engines
+
+- **SchedulerEngine** — v0.51.9 起 dormant（卡 add 直接进 Backlog，无需提升）
+- **StageEngine** — drives card through stages; builds prompt (skill + projectRules
+  + memory + **wikiContext** + task description + **wikiUpdateReminder**); kicks
+  Worker via ACP
+- **MonitorEngine** — ACK timeout detection, stale runtime, auto-QA promotion
+- **CloseoutEngine / EventHandler** — finalize completed cards
+
+### Single worker is intentional
+
+v0.37.2 deleted multi-worker concurrency code by design. Don't propose "add a
+parallel mode" — the architecture relies on serial execution for state coherence.
+For higher throughput, run multiple projects in parallel (each its own tick loop).
+
+---
+
+## 11. Troubleshooting
+
+```bash
+sps doctor <project> --fix         # ★ first thing to try
+sps logs <project> --err           # stderr / errors
+sps reset <project> --card <seq>   # nuke a stuck card
+sps reset <project> --all          # full project reset (worktrees, branches, state)
+
+# Worker / daemon issues
+sps worker ps <project>
+sps agent daemon status            # is the chat daemon up?
+sps agent daemon stop && sps agent daemon start    # restart daemon (clears stale cwd)
+
+# Wiki issues (v0.51+)
+sps wiki check <project>           # lint
+sps wiki status <project>          # source / manifest / pages diff
+```
+
+Common issues:
+
+- **Pipeline halted with NEEDS-FIX** — open the failed card, fix the issue, remove
+  the label. Console makes this 2 clicks.
+- **Worker not starting** — `sps worker ps`, then check `sps logs --err`. Often
+  Claude API key missing or `claude-agent-acp` adapter not installed (`sps setup`
+  reinstalls it).
+- **Cards stuck in Planning (v0.51.9+)** — Planning 是人工暂存。**Console 表单建卡默认到这里**，需手动拖到 Backlog 派发。Agent / `sps card add` 默认进 Backlog 自动跑（不会卡在 Planning）。
+- **ACK timeout on every card** — Claude cold-start is slow with many skills/memory
+  files. Raise `WORKER_ACK_TIMEOUT_S` in conf (default 300s as of v0.50.24).
+- **Console shows stale data** — SSE may have dropped; reload page; if persistent,
+  `sps console --kill && sps console`.
+- **Wiki context not injecting** — verify `WIKI_ENABLED=true` in conf and
+  `wiki/WIKI.md` exists. StageEngine logs a warning if conf says yes but scaffold
+  is missing.
+
+---
+
+## 12. Skill ↔ project linkage
+
+User-level skills live in `~/.coral/skills/`. To use one in a specific project:
+
+```bash
+sps skill list                             # what's available + project status
+sps skill add <name> --project <p>         # symlink into <repo>/.claude/skills/
+sps skill remove <name> --project <p>
+sps skill freeze <name> --project <p>      # symlink → real copy (allow project edits)
+sps skill unfreeze <name> --project <p>    # back to symlink
+sps skill sync                             # ① bundled (npm pkg) → ~/.coral/skills/
+                                           # ② ~/.coral/skills/ → ~/.claude/skills/
+```
+
+**After upgrading sps-cli**, run `sps skill sync` to pick up new bundled skills
+(e.g. `wiki-update` added in v0.51.0).