docs(dashboard): add Ralph Workplan reference page

Covers installation, usage, workplan file format, task status lifecycle,
custodian naming conventions, COULOMBCORE usage, and manual cancellation.
Registered in Reference nav + reference.md index.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dashboard/observablehq.config.js

@@ -56,6 +56,7 @@ export default {
         { name: "Live Data",                path: "/docs/live-data" },
         { name: "Overview",                 path: "/docs/overview" },
         { name: "Progress Log",             path: "/docs/progress-log" },
+        { name: "Ralph Workplan",           path: "/docs/ralph-workplan" },
         { name: "Reference & Context Help", path: "/docs/reference" },
         { name: "Repo Integration",         path: "/docs/repo-integration" },
         { name: "Repos",                    path: "/docs/repos" },

dashboard/src/docs/ralph-workplan.md

@@ -0,0 +1,208 @@
+---
+title: Ralph Workplan — Reference
+---
+
+# Ralph Workplan — Reference
+
+`/ralph-workplan` is a Claude Code skill that starts a self-managing
+[Ralph Loop](https://github.com/anthropics/claude-code) tied to a specific
+workplan file. The loop retires automatically when all tasks in the workplan
+are done — no external services required.
+
+---
+
+## Why use it instead of `/ralph-loop`
+
+`/ralph-loop` with a static prompt has no awareness of completion state. It
+loops until `--max-iterations` is reached, even if the work is already done.
+
+`/ralph-workplan`:
+- **Refuses to start** if the workplan `status` is already `done`
+- **Self-retires** — re-reads the workplan file every iteration; outputs
+  `<promise>HEUREKA</promise>` the moment all tasks are `done`
+- Always sets `--completion-promise HEUREKA` and a bounded iteration count
+
+---
+
+## Installation
+
+The skill lives in its own repository: `coulomb/ralph-workplan` on Gitea.
+
+```bash
+git clone http://92.205.130.254:32166/coulomb/ralph-workplan.git ~/ralph-workplan
+cd ~/ralph-workplan && ./install.sh
+# restart Claude Code
+```
+
+**Prerequisite:** the `ralph-loop` plugin must be installed first.
+Install it from within Claude Code: `/install ralph-loop` (or via the plugin
+marketplace).
+
+To update to the latest version:
+```bash
+cd ~/ralph-workplan && git pull && ./install.sh
+```
+
+To uninstall:
+```bash
+cd ~/ralph-workplan && ./install.sh --uninstall
+```
+
+---
+
+## Usage
+
+```
+/ralph-workplan <workplan-file> [--max-iterations N]
+```
+
+| Argument | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `<workplan-file>` | yes | — | Path to the workplan `.md` file |
+| `--max-iterations N` | no | `20` | Maximum loop iterations before stopping |
+
+**Examples:**
+
+```
+/ralph-workplan workplans/MRKD-WP-0001-core-pipeline.md
+/ralph-workplan workplans/MRKD-WP-0001-core-pipeline.md --max-iterations 15
+```
+
+---
+
+## What happens when you invoke it
+
+1. **Validates** the workplan file exists
+2. **Reads** the frontmatter — extracts `id`, `title`, `status`
+3. **Guards** — if `status: done`, stops immediately with a message
+4. **Shows** current task summary (done / in progress / todo counts)
+5. **Writes** `.claude/ralph-loop.local.md` — the ralph state file containing
+   a workplan-aware prompt
+6. **The loop begins** — on every iteration Claude:
+   - Re-reads the workplan file
+   - If all tasks are `done` and frontmatter `status: done` → outputs
+     `<promise>HEUREKA</promise>` and the loop stops
+   - Otherwise → continues implementation, marking tasks done as it goes
+
+---
+
+## Workplan file format
+
+```markdown
+---
+id: WP-0001
+title: "Build a thing"
+status: active
+---
+
+Optional description.
+
+## Task: Do the first thing
+
+​```task
+id: T-01
+status: todo
+priority: high
+​```
+
+## Task: Do the second thing
+
+​```task
+id: T-02
+status: todo
+priority: medium
+​```
+```
+
+**Frontmatter fields:**
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `id` | string | Unique workplan identifier |
+| `title` | string | Human-readable name |
+| `status` | `active` \| `done` \| `paused` | Workplan lifecycle state |
+
+**Task block fields:**
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `id` | string | Unique task identifier |
+| `status` | `todo` \| `in_progress` \| `done` | Task state |
+| `priority` | `high` \| `medium` \| `low` | Execution order hint |
+
+---
+
+## How Claude updates task status
+
+As Claude completes tasks it edits the workplan file directly:
+
+```
+status: todo  →  status: in_progress   (when starting)
+status: in_progress  →  status: done   (when verified complete)
+```
+
+When every task is `done`, Claude also updates the frontmatter:
+
+```
+status: active  →  status: done
+```
+
+The loop detects this on the next iteration and stops.
+
+---
+
+## Naming convention for custodian-family projects
+
+Projects tracked in the State Hub use the prefix `<DOMAIN>-WP-NNNN`:
+
+| Domain | Prefix | Example file |
+|--------|--------|-------------|
+| markitect / marki-docx | `MRKD-WP` | `workplans/MRKD-WP-0001-core-pipeline.md` |
+| ops-bridge | `BRIDGE-WP` | `workplans/BRIDGE-WP-0004-catalog.md` |
+| railiance | `RAIL-WP` | `workplans/RAIL-WP-0001-infra.md` |
+| custodian | `CUST-WP` | `workplans/CUST-WP-0011-goals.md` |
+
+The skill works with any filename — the prefix is a convention, not a requirement.
+
+---
+
+## Using ralph-workplan on COULOMBCORE
+
+The skill is already installed on COULOMBCORE. No additional setup needed.
+
+Open a Claude Code session in the target repository on COULOMBCORE and invoke
+the skill exactly as you would locally:
+
+```
+/ralph-workplan workplans/MRKD-WP-0001-my-feature.md
+```
+
+The skill is **fully self-contained** — it reads and writes only the workplan
+file. It does not call the State Hub API or require network access.
+
+If the project also integrates with the State Hub (via the MCP tunnel), the
+agent can additionally report progress and mark workstream tasks done through
+the MCP tools during the loop — but this is optional and independent of the
+ralph-workplan lifecycle.
+
+---
+
+## Stopping a running loop
+
+The loop stops automatically when the completion promise is detected. To stop
+it manually:
+
+```
+/cancel-ralph
+```
+
+This removes `.claude/ralph-loop.local.md`, which the stop hook checks on every
+exit attempt. The current iteration completes before the loop stops.
+
+---
+
+## Source
+
+Repository: `coulomb/ralph-workplan` on Gitea
+Install path: `~/.claude/plugins/ralph-workplan/`
+Full spec: `~/ralph-workplan/workplan-spec.md` (after cloning)

dashboard/src/reference.md

@@ -45,4 +45,5 @@ convention used in the Custodian State Hub.
 
 | Topic | What it covers |
 |-------|---------------|
+| [Ralph Workplan](/docs/ralph-workplan) | `/ralph-workplan` skill — installation, usage, workplan format, COULOMBCORE setup |
 | [Reference & Context Help](/docs/reference) | How reference pages work; the ? context-help button |