@coralai/sps-cli 0.51.11 → 0.52.0

package/README.md

@@ -1,547 +1,218 @@
-# SPS CLI — AI Agent Harness & Development Pipeline
+# SPS CLI
 
-[![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)
 
-**v0.51.3**
+## 1. Introduction
 
-SPS (Smart Pipeline System) drives a Claude Code worker through task cards — code, commit, push, QA, merge, all automated. Three modes:
+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.
 
-| 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). |
-
-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).
-
----
-
-## Table of contents
+### 24/7 unattended software development
 
-- [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)
-
----
-
-## Install & setup
-
-```bash
-npm install -g @coralai/sps-cli      # latest 0.51.x
-sps setup                            # interactive wizard (must run once)
-```
+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.
 
-`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.
+### Beyond software — extensible to any domain via skills
 
-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).
+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:
 
-**Prerequisites**: Node ≥ 18; an Anthropic API key (or Claude Pro / Max subscription); `claude` CLI in PATH.
+- **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
 
----
+One CLI, one console, one filesystem-driven workflow. No vendor lock-in.
 
-## Harness mode (`sps agent`)
+![CLI](docs/screenshots/01-cli-banner.png)
 
-Direct one-shot or multi-turn chat with Claude. No project, no PM, no Git.
+## 2. Core Concepts
 
-```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?"
-```
+### 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.
 
-**`--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.)
+### 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.
 
-**Built-in agent**: `claude` only (Codex / Gemini support removed in v0.38). Workers communicate via ACP JSON-RPC over stdio with `claude-agent-acp`.
+### 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.
 
-**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.
+### 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`.
 
-**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.
+| 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 |
 
----
+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.
 
-## Console mode (`sps console`)
+### Knowledge Base — LLM Wiki
 
-Local web UI bundled into the binary. Single-instance guard via `~/.coral/console.lock`.
+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.
 
-```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)
-```
+**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.
 
-Pages:
+**The wiki**: Workers continuously distill code, design docs, and completed cards into atomic, cross-linked pages:
 
-| Path | Purpose |
+| Page type | What it captures |
 |---|---|
-| `/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).
-
----
+| `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) |
 
-## Pipeline mode (`sps tick`)
+**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.
 
-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.
+**Self-retrieving**: Every card prompt receives 5-layer auto-injection (~2K tokens) so the worker starts informed:
 
-### Create a project
+- **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
 
-```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:
+**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.
 
-```
-~/.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
-```
+**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.
 
-In the target repo (PROJECT_DIR):
+### 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.
 
-```
-.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
-```
+## 3. Console
 
-### Run
+Launch the local web UI:
 
 ```bash
-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
+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
 ```
 
-### 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).
-
----
+Single command, no extra services — kanban, chat, skills, workers, logs, projects all in one place.
 
-## Card lifecycle
+**Kanban — card-driven workflow at a glance**
 
-```
-Backlog → Todo → Inprogress → [QA / Review] → Done
-   ↑↓                  ↓ fail
-Planning           NEEDS-FIX (halt)
-(manual park, v0.51.9+)
-```
+![Console — Kanban](docs/screenshots/02-kanban.png)
 
-**v0.51.10**: caller-aware default state.
-- **`sps card add` (CLI / agent / API default)** → **Backlog**（自动跑）
-- **Console "新卡片" 表单（人在 UI 操作）** → **Planning**（暂存，等用户拖到 Backlog）
+**Chat — multi-turn agent conversations with tool-call streaming**
 
-CLI 用户想暂存：`sps card add ... --draft`。Console 用户想立即跑：勾"立即派发执行"。
-卡片严格按 seq 排序；不再有 pipeline_order.json。
+![Console — Chat](docs/screenshots/03-chat.png)
 
-Default states (configurable via YAML `pm.card_states`).
+**Skills — bundled & per-project skill management**
 
-```bash
-sps card add <p> "Title" "Description"
-sps card add <p> "T" "D" --skills python,backend --labels feature
+![Console — Skills](docs/screenshots/04-skills.png)
 
-sps card dashboard <p>               # CLI table
-                                     # console: /board?project=<n>
+**Workers — capacity, runtime, stage-by-stage logs**
 
-sps card mark-started <p> <seq>      # called by Claude Code UserPromptSubmit hook
-sps card mark-complete <p> <seq>     # called by Claude Code Stop hook
+![Console — Workers](docs/screenshots/05-workers.png)
 
-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
+## 4. Install
 
 ```bash
-sps memory list <p>                            # show project memory index
-sps memory list                                # global view (user + agents)
-sps memory context <p> --card <seq>            # preview prompt injection
+# Install
+npm install -g @coralai/sps-cli
+sps setup                       # one-time interactive wizard
 
-sps memory add <p> --type convention --name "API uses camelCase" \
-  --description "REST endpoints use camelCase" --body "..."
+# Update
+npm update -g @coralai/sps-cli
+sps skill sync --force          # pull updated skill SOPs after upgrade
 ```
 
-Types: `convention` (no decay), `decision` (slow), `lesson` (30 days), `reference` (no decay).
-
-### Wiki CLI (when `WIKI_ENABLED=true`)
+### Build from source
 
 ```bash
-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
+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
 ```
 
-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.
+### Prerequisites
 
-Worker SOP: [`skills/wiki-update/SKILL.md`](./skills/wiki-update/SKILL.md) (300 lines, single source of truth).
+- **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
 
----
+  SPS spawns `claude` over the Agent Client Protocol; it inherits whatever credentials you've already configured. No separate SPS-side API key needed.
 
-## Skills
+## 5. Quick Start
 
-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.
+### Step 1 — Run the setup wizard (one time)
 
 ```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/
-sps skill sync --force                         # ⭐ overwrite existing user skills (after sps-cli upgrade)
+sps setup
 ```
 
-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`
+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)
 
----
+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.
 
-## Command reference
+### Step 2 — Smoke-test with the agent (no project needed)
 
 ```bash
-# 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]
+sps agent "Explain this repo"           # one-shot
+sps agent --chat                        # multi-turn REPL, persistent session
 ```
 
-Add `--help` after any command to see its specific usage. Add `--json` for structured output where supported.
+If this works, your Claude Code auth is good and SPS is wired correctly.
 
----
-
-## 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
+### Step 3 — Launch the console
 
+```bash
+sps console                             # http://127.0.0.1:4311
 ```
-~/.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
-```
-
-In the target repo (PROJECT_DIR):
-
-```
-.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
-```
-
----
-
-## Architecture
 
-4-layer service architecture (v0.50+):
+### Step 4 — Run a pipeline
 
-```
-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
+```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
 ```
 
-Engines:
+**TUI dashboard** — compact multi-project view (`sps status`):
 
-- **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.
+![Card Dashboard](docs/screenshots/06-dashboard.png)
 
-**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.
+## 6. Supported Agents
 
-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-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).
 
----
+| 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 |
 
-## Troubleshooting
+The skill is plain markdown — copy it, adapt it, fork it. SPS owns orchestration; the agent owns intent.
 
-```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:
+## 7. Acknowledgements
 
-| 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`. |
+SPS stands on the shoulders of:
 
----
+- **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
 
-## License & attribution
+## 8. License
 
-MIT, see [`LICENSE`](../../LICENSE).
+[MIT](./LICENSE)
 
-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.
+## 9. Copyright
 
-Full attribution: [`ATTRIBUTION.md`](./ATTRIBUTION.md).
+Copyright (c) 2026 Coral AI