@coralai/sps-cli 0.52.3 → 0.53.1

package/README.md

@@ -1,218 +1,547 @@
-# SPS CLI
+# SPS CLI — AI Agent Harness & Development Pipeline
 
-[![npm](https://img.shields.io/npm/v/@coralai/sps-cli)](https://www.npmjs.com/package/@coralai/sps-cli) [![license](https://img.shields.io/npm/l/@coralai/sps-cli)](./LICENSE)
+[![npm](https://img.shields.io/npm/v/@coralai/sps-cli)](https://www.npmjs.com/package/@coralai/sps-cli) [![license](https://img.shields.io/npm/l/@coralai/sps-cli)](../../LICENSE)
 
-> 中文文档：[README-CN.md](./README-CN.md)
+> **中文文档**：[README-CN.md](./README-CN.md)
 
-## 1. Introduction
+**v0.51.3**
 
-SPS (Smart Pipeline System) is an open-source **AI-agent harness** that turns a single-line task into reviewed, committed, deployable output. It drives an underlying agent through a card-based pipeline — plan, execute, review, ship — with a per-project knowledge base auto-injected into every prompt.
+SPS (Smart Pipeline System) drives a Claude Code worker through task cards — code, commit, push, QA, merge, all automated. Three modes:
 
-### 24/7 unattended software development
+| Mode | Command | When |
+|---|---|---|
+| **Harness** | `sps agent` | Zero-config — one-shot or multi-turn chat with Claude. No project, no PM. |
+| **Pipeline** | `sps tick <project>` | Automated card-driven workflow with YAML-configurable stages. |
+| **Console** | `sps console` | Web UI — kanban, logs, workers, projects, chat (since v0.44). |
 
-Drop tasks into the backlog and the harness runs them around the clock — planning, coding, testing, committing, opening MRs, escalating only when truly blocked. While you sleep, the pipeline ticks; your morning standup reads the merged commits. SPS exists so a single human can run a development team's worth of work without sitting in front of a chat window.
+The headline feature in v0.51 is the **Wiki Knowledge Base** — opt-in per project, structured cross-linked pages (modules / concepts / decisions / lessons / sources), 5-layer retrieval auto-injected into worker prompts. See [doc-28](../../docs/design/28-wiki-system.md) and [`ATTRIBUTION.md`](./ATTRIBUTION.md).
 
-### Beyond software — extensible to any domain via skills
+---
 
-The pipeline, skills, and knowledge layer are intentionally generic. Any process that can be expressed as "task in → reviewed output out" can be wired up by swapping the skill bundle:
+## Table of contents
 
-- **Accounting** — invoice intake → categorization → ledger reconciliation → period close
-- **Self-media** — topic research → drafting → review → publishing
-- **AI video generation** — script → storyboard → render → cut → review
-- **Writing** — research → outline → draft → revise → publish
-- **Any other workflow** — define stages in YAML, write skills in markdown; the harness runs them
+- [Install & setup](#install--setup)
+- [Harness mode (`sps agent`)](#harness-mode-sps-agent)
+- [Console mode (`sps console`)](#console-mode-sps-console)
+- [Pipeline mode (`sps tick`)](#pipeline-mode-sps-tick)
+- [Card lifecycle](#card-lifecycle)
+- [Memory + Wiki](#memory--wiki)
+- [Skills](#skills)
+- [Command reference](#command-reference)
+- [Project config (conf)](#project-config-conf)
+- [Project layout](#project-layout)
+- [Architecture](#architecture)
+- [Troubleshooting](#troubleshooting)
 
-One CLI, one console, one filesystem-driven workflow. No vendor lock-in.
+---
 
-![CLI](docs/screenshots/01-cli-banner.png)
+## Install & setup
 
-## 2. Core Concepts
+```bash
+npm install -g @coralai/sps-cli      # latest 0.51.x
+sps setup                            # interactive wizard (must run once)
+```
 
-### Harness
-A long-running shell around the AI agent: daemon, supervisor, transport, profile management, file-system task lifecycle. The agent focuses on writing code; the harness owns the infrastructure.
+`sps setup`:
+1. Creates `~/.coral/` directory tree (`projects/`, `memory/{user,agents}/`).
+2. Copies bundled skills → `~/.coral/skills/`.
+3. Asks for `GITLAB_URL` / `GITLAB_TOKEN` / `MATRIX_*` (optional) → writes `~/.coral/env`.
+4. Symlinks user skills → `~/.claude/skills/`.
+5. Installs `@agentclientprotocol/claude-agent-acp` globally.
 
-### Pipeline
-Each task is a **card** that flows through stages: `Backlog → Planning → Todo → Inprogress → QA → Done`. Every stage has its own prompt, allowed tools, exit gates — all configurable in YAML.
+Re-run safe with `sps setup --force` (keeps existing values as defaults). After upgrading sps-cli later, run **`sps skill sync --force`** to pull updated skill SOPs (default sync is non-destructive — won't overwrite existing skills).
 
-### Skills
-Stages dispatch atomic **skills** to drive each task — `sps-pipeline`, `wiki-update`, `git-commit`, persona skills, and 24 dev skills bundled. Skills compose without ballooning the system prompt; the harness loads only what the current stage needs.
+**Prerequisites**: Node ≥ 18; an Anthropic API key (or Claude Pro / Max subscription); `claude` CLI in PATH.
 
-### Memory
-A 3-layer markdown-on-disk persistence for **non-obvious, reusable facts** that should survive across sessions. Lives entirely under `~/.coral/memory/`; auto-injected into every pipeline worker prompt by `StageEngine`.
+---
 
-| Layer | Path | Scope |
-|---|---|---|
-| **User** | `~/.coral/memory/user/` | Cross-project preferences (style, language, workflow habits) |
-| **Agent** | `~/.coral/memory/agents/<id>/` | Per-agent observations (communication patterns specific to one agent ↔ user pair) |
-| **Project** | `~/.coral/memory/projects/<name>/` | Per-project conventions, architecture decisions, lessons, references |
+## Harness mode (`sps agent`)
+
+Direct one-shot or multi-turn chat with Claude. No project, no PM, no Git.
+
+```bash
+# One-shot
+sps agent "Explain this repo"
+sps agent --output summary.md "Summarize the architecture"
+
+# Multi-turn (daemon-backed, persistent sessions)
+sps agent --chat                              # interactive REPL
+sps agent --chat --name reviewer              # named session, resume later
+sps agent status                              # list active sessions
+sps agent close --name reviewer
+
+# Profile + context files
+sps agent --profile reviewer "Review this module" --context src/auth.ts --context src/auth.test.ts
+sps agent --system "You are a release engineer" "Plan the v0.52 cut"
+
+# Verbose
+sps agent --verbose "Why did this build fail?"
+```
 
-Four entry types — `convention` (never decays), `decision` (slow), `lesson` (30-day decay), `reference` (never decays). Each layer keeps a flat directory of `*.md` files plus a `MEMORY.md` index. The agent reads it on demand and writes back when it discovers something worth keeping — a sparse, private drift; complementary to the dense, shared Wiki below.
+**`--profile <name>`**: looks up `~/.coral/skills/dev-worker/references/<name>.md`, injects as system prompt. (Different from `sps skill add` — that's for project-level skill linking.)
 
-### Knowledge Base — LLM Wiki
+**Built-in agent**: `claude` only (Codex / Gemini support removed in v0.38). Workers communicate via ACP JSON-RPC over stdio with `claude-agent-acp`.
 
-Inspired by Andrej Karpathy's "LLM Wiki": instead of re-reading source code from scratch every session, the agent **distills** project knowledge into a persistent, structured wiki that primes every future prompt.
+**Agent skills auto-loaded by Claude Code**: `~/.claude/skills/` is scanned by `claude` itself — including `sps-pipeline`, `sps-memory`, `wiki-update`, and the 24 dev/persona skills. Skill descriptions trigger lazy load; no SPS prompt injection needed for harness mode.
 
-**The problem**: An AI agent re-discovering your codebase on every task burns tokens, misses non-obvious decisions, and walks into the same gotcha twice. Most of the knowledge in a codebase is implicit — in commit context, in design tradeoffs, in incident postmortems that never made it back into the source.
+**Daemon cwd caveat**: `sps console` and `sps agent --chat` start a session daemon (`~/.coral/sessions/daemon.sock`) that captures `process.cwd()` at startup and uses it as the default working directory for all chat workers. To switch the chat's working directory, restart the daemon: `sps agent daemon stop && sps agent daemon start` from the desired cwd.
 
-**The wiki**: Workers continuously distill code, design docs, and completed cards into atomic, cross-linked pages:
+---
 
-| Page type | What it captures |
+## Console mode (`sps console`)
+
+Local web UI bundled into the binary. Single-instance guard via `~/.coral/console.lock`.
+
+```bash
+sps console                          # opens http://127.0.0.1:4311
+sps console --port 5000
+sps console --no-open                # don't auto-open browser
+sps console --kill                   # stop running console
+sps console --dev                    # vite dev server (development)
+```
+
+Pages:
+
+| Path | Purpose |
 |---|---|
-| `modules/` | What each component does and how it's used |
-| `concepts/` | Recurring patterns and architectural primitives |
-| `decisions/` | Why a specific choice was made (with version anchor) |
-| `lessons/` | Non-obvious gotchas surfaced from incidents |
-| `sources/` | Distilled summaries of external materials added to `.raw/` (PDFs, articles, transcripts) |
+| `/projects` | List all projects with status |
+| `/projects/new` | Create project (form has Wiki toggle, v0.51+) |
+| `/projects/<n>` | Pipeline editor + conf editor + delete |
+| `/board` | Kanban (per-column scrolling, v0.51.1+) |
+| `/workers` | Aggregate worker dashboard across projects |
+| `/logs` | Live SSE log viewer |
+| `/skills` | User-level skill management |
+| `/system` | Global settings + daemon status |
+| `/chat` | Agent chat (multi-session, persistent) |
+
+Tech: Hono server on `127.0.0.1:4311`, chokidar watchers pushing SSE to React 19 + Vite + Tailwind v4 + shadcn/ui frontend. Design system: Pastel Neubrutalism, locked in [`console/DESIGN.md`](./console/DESIGN.md).
+
+---
 
-**Self-maintaining**: After each card, the worker auto-writes back any new lessons or module changes — no manual curation. SOP lives in `skills/wiki-update/` and follows a 4-question filter (module changed? decision made? lesson learned? new pattern?). Four NOs = no write.
+## Pipeline mode (`sps tick`)
 
-**Self-retrieving**: Every card prompt receives 5-layer auto-injection (~2K tokens) so the worker starts informed:
+Fully automated card-driven workflow. **One worker, one card at a time, serial.** Each card walks one or more YAML-defined stages (e.g. `develop → review → Done`); failure halts pipeline until you remove the `NEEDS-FIX` label.
 
-- **L1** `hot.md` — recent context (~500 tokens)
-- **L2** `index.md` excerpt — top-30 page TL;DRs (~500 tokens)
-- **L3** pinned pages — explicitly referenced in card frontmatter
-- **L4** skill-tag matches — pages tagged with the card's active skills
-- **L5** BM25F keyword fallback — top-3 by title/desc
+### Create a project
 
-**Compounds over time**: Each completed card adds to the corpus. The longer a project runs, the better workers understand it without reading raw source. Old workers' lessons prime new workers — the wiki *is* the project's institutional memory.
+```bash
+sps project init my-app
+# or use Console /projects/new — has a Wiki toggle (v0.51+)
+```
+
+Asks for: project dir, merge branch, max workers, ACK timeout, optional GitLab remote, optional Matrix room.
+
+Generates:
 
-**Obsidian-compatible**: Stored at `<repo>/wiki/` with `[[wikilink]]` syntax and flat YAML frontmatter. Open the directory as an Obsidian vault for graph view, backlinks, and full-text search out of the box.
+```
+~/.coral/projects/my-app/
+├── conf                              # mode 600 — your active config
+├── conf.example                      # full reference (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
+```
 
-### Agent Mode
-SPS is **agent-agnostic**. Any coding agent that can read a skill and shell out — Claude Code, Codex, OpenClaw, your own — can drive SPS through the bundled `sps-pipeline` skill. The harness adapts to the agent, not the other way around. Wiring up a new agent means dropping a skill file; no SPS code change required. See [§6](#6-supported-agents) for the integration matrix.
+In the target repo (PROJECT_DIR):
 
-## 3. Console
+```
+.claude/CLAUDE.md                     # worker rules (auto-installed)
+.claude/skills/                       # symlinked from ~/.coral/skills/
+.claude/settings.local.json           # Claude Code local config
+wiki/                                 # if WIKI_ENABLED — see doc-28
+ATTRIBUTION.md                        # if WIKI_ENABLED
+```
 
-Launch the local web UI:
+### Run
 
 ```bash
-sps console                      # opens http://127.0.0.1:4311
-sps console --port 5000          # custom port
-sps console --no-open            # don't auto-open the browser
-sps console --kill               # stop a running console
+sps tick my-app                      # foreground tick loop
+sps pipeline start my-app            # alias
+sps pipeline stop my-app             # graceful stop (alias: sps stop my-app)
+sps stop --all                       # stop all running ticks
+sps status                           # all projects
 ```
 
-Single command, no extra services — board, chat, skills, workers, logs, projects all in one place.
+### Pipeline YAML
+
+`~/.coral/projects/<n>/pipelines/project.yaml` — single source of truth for stages.
+
+```yaml
+mode: project
+git: true                            # false = non-code project, no git ops
+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 }
+```
+
+Critical rules:
+1. `mode: project` for state-machine pipelines; `mode: steps` for one-shot custom (use `sps pipeline run <name>`).
+2. Each stage's `on_complete` must point to the **next** stage's target state.
+3. Last stage's `on_complete: "move_card Done"`.
+4. Don't write `agent:` field — it's silently ignored (v0.38+ Claude is the only worker).
+5. `trigger` and `card_state` are auto-derived per stage.
+
+Field reference: see `~/.coral/projects/<n>/pipelines/sample.yaml.example` (auto-generated, comment-rich) or [doc-17](../../docs/design/17-pipeline-configuration-design.md).
+
+---
 
-**Board — card-driven workflow at a glance**
+## Card lifecycle
 
-![Console — Board](docs/screenshots/02-kanban.png)
+```
+Backlog → Todo → Inprogress → [QA / Review] → Done
+   ↑↓                  ↓ fail
+Planning           NEEDS-FIX (halt)
+(manual park, v0.51.9+)
+```
 
-**Chat — multi-turn agent conversations with tool-call streaming**
+**v0.51.10**: caller-aware default state.
+- **`sps card add` (CLI / agent / API default)** → **Backlog**（自动跑）
+- **Console "新卡片" 表单（人在 UI 操作）** → **Planning**（暂存，等用户拖到 Backlog）
 
-![Console — Chat](docs/screenshots/03-chat.png)
+CLI 用户想暂存：`sps card add ... --draft`。Console 用户想立即跑：勾"立即派发执行"。
+卡片严格按 seq 排序；不再有 pipeline_order.json。
 
-**Skills — bundled & per-project skill management**
+Default states (configurable via YAML `pm.card_states`).
 
-![Console — Skills](docs/screenshots/04-skills.png)
+```bash
+sps card add <p> "Title" "Description"
+sps card add <p> "T" "D" --skills python,backend --labels feature
 
-**Workers — capacity, runtime, stage-by-stage logs**
+sps card dashboard <p>               # CLI table
+                                     # console: /board?project=<n>
 
-![Console — Workers](docs/screenshots/05-workers.png)
+sps card mark-started <p> <seq>      # called by Claude Code UserPromptSubmit hook
+sps card mark-complete <p> <seq>     # called by Claude Code Stop hook
 
-## 4. Install
+sps reset <p>                        # reset all non-Done cards
+sps reset <p> --card 5,6,7
+sps reset <p> --all                  # full reset incl. Done + worktrees + branches
+```
+
+### Card label vocabulary
+
+| Label | Meaning | Set by |
+|---|---|---|
+| `AI-PIPELINE` | Required to enter pipeline | User on creation |
+| `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 |
+| `conflict:<domain>` | Serial-with-others-in-same-domain | User |
+
+The active stage writes a per-slot marker file at `~/.coral/projects/<p>/runtime/worker-<slot>-current.json` (v0.50.21+). Stop hook reads it to detect which card the worker just finished.
+
+---
+
+## Memory + Wiki
+
+Two complementary persistence systems, both auto-injected into worker prompts.
+
+| | **Memory** | **Wiki** (v0.51+) |
+|---|---|---|
+| Path | `~/.coral/memory/{user,agents,projects/<p>}/` | `<repo>/wiki/` (per-project, in repo) |
+| Format | Flat markdown + YAML frontmatter | 5 page types with zod-validated frontmatter |
+| Cross-link | None (flat index) | `[[type/Title]]` wikilinks |
+| Auto-inject | `knowledge` section of prompt | `wikiContext` section (5-layer retrieval) |
+| Opt-in | Always on (toggle via `ENABLE_MEMORY=false`) | Per-project (`WIKI_ENABLED=true`) |
+| Best for | Personal prefs, ad-hoc decisions, gotchas | Structured project knowledge: modules, concepts, decisions, lessons |
+
+### Memory CLI
 
 ```bash
-# Install
-npm install -g @coralai/sps-cli
-sps setup                       # one-time interactive wizard
+sps memory list <p>                            # show project memory index
+sps memory list                                # global view (user + agents)
+sps memory context <p> --card <seq>            # preview prompt injection
 
-# Update
-npm update -g @coralai/sps-cli
-sps skill sync --force          # pull updated skill SOPs after upgrade
+sps memory add <p> --type convention --name "API uses camelCase" \
+  --description "REST endpoints use camelCase" --body "..."
 ```
 
-### Build from source
+Types: `convention` (no decay), `decision` (slow), `lesson` (30 days), `reference` (no decay).
+
+### Wiki CLI (when `WIKI_ENABLED=true`)
 
 ```bash
-git clone https://github.com/edwardZhang/sps-cli.git
-cd sps-cli
-npm install
-npm run build                   # tsc + console assets
-npm link                        # symlink `sps` to local build
+sps wiki init <p>                              # scaffold wiki/ (auto on project init if toggled on)
+sps wiki update <p>                            # show source diff
+sps wiki update <p> --finalize                 # flush manifest after worker writes pages
+sps wiki check <p>                             # lint: orphan / dead-link / fm-gap / stale
+sps wiki list <p> --type lesson --tag pipeline
+sps wiki get <p> lessons/Stop-Hook-Race
+sps wiki status <p>                            # source ↔ manifest ↔ pages diff
+sps wiki add <p> ~/notes.md --category transcripts
+sps wiki read <p> "<query>"                    # preview the 5-layer retrieval
 ```
 
-### Prerequisites
+The 5-layer retrieval: hot.md / index summary / pinned / skill-tag / BM25F keyword. Type priority: lesson = 3, decision = 3, concept = 2, module = 1, source = 1. Token budget capped at ~2000.
 
-- **Node.js ≥ 18**
-- **A working Claude Code installation locally.** Run `claude --help` first — if that works for you, SPS will work. SPS does not care **how** you authenticate Claude Code:
-  - Anthropic API key (`ANTHROPIC_API_KEY`)
-  - Claude Pro / Max subscription
-  - Third-party API gateway / proxy
-  - Any other auth method Claude Code supports
+Worker SOP: [`skills/wiki-update/SKILL.md`](./skills/wiki-update/SKILL.md) (300 lines, single source of truth).
 
-  SPS spawns `claude` over the Agent Client Protocol; it inherits whatever credentials you've already configured. No separate SPS-side API key needed.
+---
 
-## 5. Quick Start
+## Skills
 
-### Step 1 — Run the setup wizard (one time)
+User-level skills live in `~/.coral/skills/` (28 bundled, copied from npm package on `sps setup`). Symlinked into `~/.claude/skills/` so Claude Code auto-loads them.
 
 ```bash
-sps setup
+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/
+sps skill sync --force                         # ⭐ overwrite existing user skills (after sps-cli upgrade)
 ```
 
-The wizard:
-- Creates `~/.coral/{projects,memory,sessions,skills}/` directory tree
-- Copies bundled skills into `~/.coral/skills/` and symlinks them into `~/.claude/skills/` so Claude Code picks them up
-- Installs `@agentclientprotocol/claude-agent-acp` globally so `claude` can be driven over ACP
-- Optionally writes `~/.coral/env` (GitLab token, Matrix notification, etc. — all optional)
+Bundled skills (v0.51.3):
+
+- **Dev (23)**: `frontend`, `frontend-developer`, `backend`, `backend-architect`, `typescript`, `golang`, `rust`, `python`, `java`, `kotlin`, `swift`, `mobile`, `database`, `database-optimizer`, `qa-tester`, `security-engineer`, `architecture-decision-records`, `coding-standards`, `debugging-workflow`, `devops`, `devops-automator`, `git-workflow`, `code-reviewer`
+- **Worker profiles (3)**: `dev-worker`, `tax-worker`, `reviewer` (referenced via `--profile`)
+- **SPS-specific (5)**: `sps-pipeline`, `sps-memory`, `wiki-update`
 
-Re-runnable safely: `sps setup --force` keeps existing values as defaults. After upgrading sps-cli later, run **`sps skill sync --force`** to pull updated skill SOPs.
+---
 
-### Step 2 — Smoke-test with the agent (no project needed)
+## Command reference
 
 ```bash
-sps agent "Explain this repo"           # one-shot
-sps agent --chat                        # multi-turn REPL, persistent session
+# Setup & projects
+sps setup [--force]
+sps project init <name>
+sps project doctor <name> [--fix] [--json] [--reset-state] [--skip-remote]
+sps doctor <name> --fix              # alias
+
+# Pipeline
+sps tick <project> [--json]
+sps pipeline start|stop|status|reset|workers|board|card|logs|list|run|use [project] [args]
+sps pipeline run <name> "<prompt>"   # for mode: steps pipelines
+sps pipeline tick <project>          # one-off StageEngine pass
+sps scheduler tick <project>         # dormant since v0.51.9 (kept for tick orchestrator)
+sps qa tick <project>                # QA → Done finalization
+sps monitor tick <project>           # health probe (ACK timeout, stale)
+sps pm scan <project>                # rebuild card index from disk
+
+# Cards
+sps card add <p> "title" ["description"] [--skills a,b] [--labels x,y]
+sps card dashboard <p>
+sps card mark-started <p> [seq] [--stage <name>]
+sps card mark-complete <p> <seq> [--stage <name>]
+
+# Worker
+sps worker ps <project>
+sps worker dashboard <project>
+sps worker kill <project> <seq>
+sps worker launch <project> <seq>
+
+# Status / logs
+sps status [--json]
+sps stop <project> [--all]
+sps reset <project> [--all] [--card N,N,N]
+sps logs [project] [--err] [--lines N] [--no-follow]
+
+# Memory
+sps memory list [project] [--agent <id>]
+sps memory context <project> [--card <seq>] [--agent <id>]
+sps memory add <project> --type <T> --name "title" [--body "content"]
+
+# Wiki (v0.51+)
+sps wiki init <p>
+sps wiki update <p> [--finalize] [--json]
+sps wiki read <p> "<query>" [--skills a,b] [--pinned id1,id2] [--budget N]
+sps wiki check <p> [--json] [--fix]
+sps wiki add <p> <file> [--category <name>] [--no-ingest]
+sps wiki list <p> [--type T] [--tag T] [--json]
+sps wiki get <p> <pageId> [--json]
+sps wiki status <p> [--json]
+
+# Skill
+sps skill list [--project <p>]
+sps skill add <name> [--project <p>]
+sps skill remove <name> [--project <p>]
+sps skill freeze <name> [--project <p>]
+sps skill unfreeze <name> [--project <p>]
+sps skill sync [--force]
+
+# Console
+sps console [--port N] [--host H] [--no-open] [--dev] [--kill]
+
+# Agent
+sps agent "<prompt>" [--profile <p>] [--system "..."] [--context file] [--output file] [--verbose]
+sps agent --chat [--name <session>]
+sps agent status|close|list|add [args]
+sps agent daemon start|stop|status
+
+# Hooks (called by Claude Code, not by users)
+sps hook stop
+sps hook user-prompt-submit
+
+# ACP control (for advanced debugging)
+sps acp <ensure|run|prompt|status|stop|pending|respond> <project> [args]
 ```
 
-If this works, your Claude Code auth is good and SPS is wired correctly.
+Add `--help` after any command to see its specific usage. Add `--json` for structured output where supported.
 
-### Step 3 — Launch the console
+---
 
-```bash
-sps console                             # http://127.0.0.1:4311
+## Project config (conf)
+
+Live at `~/.coral/projects/<name>/conf` (shell `export VAR="value"` syntax, mode 600). Full field reference (with comments) auto-generated at `~/.coral/projects/<name>/conf.example`.
+
+| Field | Default | Notes |
+|---|---|---|
+| `PROJECT_NAME` | (required) | Internal id |
+| `PROJECT_DIR` | (required) | Absolute path to repo |
+| `GITLAB_PROJECT` | — | `user/repo` (optional, for GitLab API) |
+| `GITLAB_PROJECT_ID` | — | Numeric ID (GitLab only; auto-resolved from path on first MR) |
+| `GITLAB_MERGE_BRANCH` | `main` | Worker pushes here |
+| `PM_TOOL` | `markdown` | **Only `markdown` supported as of v0.42**. Cards live in `~/.coral/projects/<n>/cards/<state>/<seq>.md` |
+| `PIPELINE_LABEL` | `AI-PIPELINE` | Required label on cards to enter pipeline |
+| `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; fallback when no `profile:` and no `card.skills` |
+| `ENABLE_MEMORY` | `true` | `false` skips memory write instructions in prompt |
+| **`WIKI_ENABLED`** | unset (off) | **v0.51+**: `true` enables wiki context injection + reminder |
+| `COMPLETION_SIGNAL` | `done` | Word the Stop hook listens for |
+
+Global credentials at `~/.coral/env`: `GITLAB_URL`, `GITLAB_TOKEN`, `GITLAB_SSH_HOST`, `GITLAB_SSH_PORT`, `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_ROOM_ID`. Set via `sps setup` or `vim`.
+
+---
+
+## Project layout
+
+```
+~/.coral/                              # User-global state
+├── env                                # Global credentials (mode 600)
+├── skills/                            # User-level skills (synced from npm)
+├── memory/{user,agents,projects}/     # 3-layer memory store
+├── projects/<name>/                   # Per-project state
+│   ├── conf                           # Project config (mode 600)
+│   ├── conf.example                   # Field reference (auto-generated)
+│   ├── pipelines/{project,*}.yaml     # Pipeline definitions
+│   ├── pipeline_order.json            # Active pipeline pointer
+│   ├── runtime/state.json             # Worker slot + active card state
+│   ├── runtime/worker-<slot>-current.json   # Per-slot card marker (v0.50.21+)
+│   ├── runtime/tick.lock              # Tick lock
+│   ├── runtime/acp-state.json         # ACP session state
+│   ├── cards/<state>/<seq>.md         # Card files (markdown PM backend)
+│   ├── cards/seq.txt                  # Sequence counter
+│   ├── logs/                          # Per-tick logs
+│   └── pm_meta/                       # Card index
+├── sessions/                          # Agent daemon (chat sessions)
+│   ├── daemon.sock daemon.pid
+│   └── chat-sessions/<id>.json        # Persisted chat sessions
+├── console.lock                       # Single-instance guard for console
+└── worktrees/<project>/<seq>/         # Worker worktree per active card
 ```
 
-### Step 4 — Run a pipeline
+In the target repo (PROJECT_DIR):
 
-```bash
-sps project init my-app --repo /path/to/repo    # initialize a project
-sps card add my-app "Add a login button"        # add a task card
-sps tick my-app                                 # advance active cards one stage
+```
+.claude/
+├── CLAUDE.md                          # Worker rules (project-specific + SPS-injected)
+├── settings.local.json                # Claude Code local config
+├── skills/                            # Symlinked from ~/.coral/skills/
+└── hooks/{start,stop}.sh              # Lifecycle hooks (call into sps)
+wiki/                                  # If WIKI_ENABLED — see docs/design/28-wiki-system.md
+ATTRIBUTION.md                         # If WIKI_ENABLED
 ```
 
-**TUI dashboard** — compact multi-project view (`sps status`):
+---
 
-![Card Dashboard](docs/screenshots/06-dashboard.png)
+## Architecture
 
-## 6. Supported Agents
+4-layer service architecture (v0.50+):
 
-SPS-CLI is shell-driven, so any coding agent that can read a skill and execute commands can use it as a task harness. We ship `skills/sps-pipeline/` — install it into the agent's skill directory and the agent immediately learns the full SPS command surface (cards, pipeline ticks, wiki, project setup, daemon lifecycle).
+```
+Delivery (commands/, console/routes/)        Thin parameter parsing + I/O orchestration
+  ↓
+Service (services/)                          ProjectService / ChatService / PipelineService /
+                                             SkillService / WikiService — Result<T> + DomainEvent
+  ↓
+Domain (engines/)                            SchedulerEngine / StageEngine / MonitorEngine /
+                                             CloseoutEngine / EventHandler — pipeline logic
+  ↓
+Infrastructure                               WorkerManager (single worker), ACPWorkerRuntime,
+  (manager/, providers/, daemon/)            sessionDaemon, TaskBackend, RepoBackend
+```
 
-| Agent | Wire-up |
-|---|---|
-| **Claude Code** | ✅ `sps skill sync` symlinks `sps-pipeline` into `~/.claude/skills/`; auto-loaded on description match |
-| **Codex** | ✅ Drop `skills/sps-pipeline/SKILL.md` into the Codex skill directory |
-| **OpenClaw** | ✅ Same — point its skill loader at `skills/sps-pipeline/` |
-| **Harness Agent** | ✅ Same pattern — the skill is agent-agnostic |
-| **Any other coding agent** | ✅ If it reads instructions and shells out, it can drive SPS |
+Engines:
+
+- **SchedulerEngine** — dormant since v0.51.9 (cards go directly to Backlog on add; Planning is a manual park). Class kept as a no-op for the tick orchestrator's stable interface.
+- **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.
 
-The skill is plain markdown — copy it, adapt it, fork it. SPS owns orchestration; the agent owns intent.
+**Single-worker is intentional**: v0.37.2 deleted multi-worker concurrency code. Don't propose "add a parallel mode" — the architecture relies on serial execution for state coherence. For higher throughput, run multiple projects in parallel.
 
-## 7. Acknowledgements
+For deep dives:
+- [doc-27: Service Layer Architecture](../../docs/design/27-service-layer-architecture.md) — current architecture
+- [doc-26: Console Architecture](../../docs/design/26-console-architecture.md) — console internals
+- [doc-28: Wiki System](../../docs/design/28-wiki-system.md) — wiki design
+- [doc-13: Development Guardrails](../../docs/design/13-development-guardrails.md) — hard rules for contributors
+- [doc-17: Pipeline Configuration](../../docs/design/17-pipeline-configuration-design.md) — YAML field semantics
+- [docs/design/](../../docs/design/) — full design tree (most v0.15-v0.32 docs are marked HISTORICAL)
 
-SPS stands on the shoulders of:
+---
+
+## Troubleshooting
+
+```bash
+sps doctor <project> --fix           # ★ first thing to try
+sps logs <project> --err             # stderr / errors only
+sps reset <project> --card <seq>     # nuke a stuck card
+sps reset <project> --all            # full project reset
+
+# 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 (clears stale cwd)
+
+# Wiki issues
+sps wiki check <project>
+sps wiki status <project>
+```
+
+Common issues:
+
+| Symptom | Cause / fix |
+|---|---|
+| 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 `sps logs --err`. Often Claude API key missing or `claude-agent-acp` adapter not installed (`sps setup` reinstalls). |
+| Cards stuck in Planning | Need `AI-PIPELINE` label. `sps card add` applies it automatically; if added externally, add manually. |
+| ACK timeout on every card | Claude cold-start is slow with many skill / memory files. Raise `WORKER_ACK_TIMEOUT_S` (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. |
+| New skill SOP not pulling after upgrade | `sps skill sync --force` (default sync skips existing skills). |
+| Daemon chat using wrong cwd | Daemon captures cwd at startup. `sps agent daemon stop && cd <repo> && sps agent daemon start`. |
 
-- **Andrej Karpathy** — ["LLM Wiki"](https://gist.github.com/karpathy) mental model — the foundation for SPS's knowledge layer
-- **Anthropic Claude Agent SDK** — ACP transport, sub-agent infrastructure
-- **kepano / claude-obsidian** (MIT) — Wiki architecture, manifest, hot cache. Full attribution in [ATTRIBUTION.md](./ATTRIBUTION.md)
-- **hono · chokidar · zod · yaml · vitest · biome** — runtime & toolchain
+---
 
-## 8. License
+## License & attribution
 
-[MIT](./LICENSE)
+MIT, see [`LICENSE`](../../LICENSE).
 
-## 9. Copyright
+The Wiki system (v0.51+) borrows ~70% from [claude-obsidian](https://github.com/kepano/claude-obsidian) (MIT) — three-layer architecture, manifest delta tracking, hot cache, ingest workflow, contradiction callouts, wikilinks. SPS-specific 30%: 5 page types, `sources={card,commit,path}`, 5-layer reader, `sps wiki check` exit gate. Mental model from Karpathy's "LLM Wiki" gist.
 
-Copyright (c) 2026 Coral AI
+Full attribution: [`ATTRIBUTION.md`](./ATTRIBUTION.md).