Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

docs(readme): every README image follows the reader's theme [I10,I13]

Corey Olson0f7457764cd1
diff --git a/README.md b/README.md
index 4eff10ea..4c1d243e 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,10 @@
**Accumulated judgement for agents.** Agents are good at tasks and bad at projects: every new session starts without what you decided, so you become the glue. The agents scale; your judgement doesn't. Pullboard is a structural approach to orchestrating agents coherently over long-term builds, so you can trust your agentic workforce to fill in the blanks the way you would, without re-prompting them.
-![How it holds. Your decision becomes a bar each piece of work is frozen against; a second agent checks the exact commit; the board keeps what passed, what failed and why; the next agent starts from there.](docs/img/holds.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/holds-dark.svg">
+ <img src="docs/img/holds.svg" alt="How it holds. Your decision becomes a bar each piece of work is frozen against; a second agent checks the exact commit; the board keeps what passed, what failed and why; the next agent starts from there.">
+</picture>
**Vibe code a real product.** Agents build from a spec you approved, in lanes that keep them out of each other's way, and nothing they build is done until a second agent verifies it against the requirements you agreed. Pullboard is a coordination queue for serious software. It's how we develop our quantitative systems.
@@ -28,13 +31,19 @@ You follow progress, answer questions and approve changes from one board, and th
**Prompting is for discovery. Declaring is for delivery.** Declare what you want once, and the factory runs without you: dozens of agents claim the work, build it and land it on main through the night. Your job moves from typing prompts to the judgements only you can make. Your decisions, judgement and taste are the bar that work must clear. You come back to shipped features, not a chat log.
-![One night on Pullboard's own board, 16 October 2026: 38 agents, 9.6 hours from 11:17 pm to 8:51 am, with no moves from the person. 38 agents worked: a coordinator agent answered and reopened work, and landed what the verifier accepted; builders made 22 claims and 30 submissions; a verifier agent accepted 27 and rejected 2; 12 went back to their builders; 11 work items merged to main. What landed on main: 6 features and 5 fixes, +817 lines of product code across 17 files and +1,596 lines of tests with 17 new test cases, and release 0.8.27 on npm at 7:56 am. Among the features: The view signs in and links every board; pullboard.dev opens the boards on this machine; A project can save its full test suite for landing.](docs/img/factory.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/factory-dark.svg">
+ <img src="docs/img/factory.svg" alt="One night on Pullboard's own board, 16 October 2026: 38 agents, 9.6 hours from 11:17 pm to 8:51 am, with no moves from the person. 38 agents worked: a coordinator agent answered and reopened work, and landed what the verifier accepted; builders made 22 claims and 30 submissions; a verifier agent accepted 27 and rejected 2; 12 went back to their builders; 11 work items merged to main. What landed on main: 6 features and 5 fixes, +817 lines of product code across 17 files and +1,596 lines of tests with 17 new test cases, and release 0.8.27 on npm at 7:56 am. Among the features: The view signs in and links every board; pullboard.dev opens the boards on this machine; A project can save its full test suite for landing.">
+</picture>
### One agent. Or a hundred. (Maybe even thousands.)
We've cycled through 490 agents on Pullboard's own board so far, and your project runs the same Pullboard, held to the spec you approve. Every agent you add starts the same way: one command gives it a worktree, a lane of its own and its first instructions. Pair your phone when you're ready to walk away.
-![One board. Every agent. Every machine. All of it is in Pullboard 0.9.0. Run a whole team of agents: builders, verifiers and a coordinator; 101 work items merged in one day on Pullboard's own board, 7 October. Your board, on your phone: Answer what's waiting, anywhere. Sealed: the relay can't read it. Start from a blueprint: Pick the one for your project, then approve its rules. Plug in any agent: Keep Claude Code or Codex, and add any MCP client. Across your machines: Pair a machine once. Its agents share your board, in one order.](docs/img/what.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/what-dark.svg">
+ <img src="docs/img/what.svg" alt="One board. Every agent. Every machine. All of it is in Pullboard 0.9.0. Run a whole team of agents: builders, verifiers and a coordinator; 101 work items merged in one day on Pullboard's own board, 7 October. Your board, on your phone: Answer what's waiting, anywhere. Sealed: the relay can't read it. Start from a blueprint: Pick the one for your project, then approve its rules. Plug in any agent: Keep Claude Code or Codex, and add any MCP client. Across your machines: Pair a machine once. Its agents share your board, in one order.">
+</picture>
**What are blueprints?** New in 0.8.29. A blueprint is the spec rules and starter items for one kind of project. Ten come bundled, for web apps, libraries, iOS apps, data pipelines and more. Start a board from one:
@@ -62,7 +71,10 @@ Five primitives. Everything else is built on them.
Past the demo, the same things break.
-![Where vibe coding breaks, and what holds instead. Pullboard enforces each fix, so none of it depends on you watching. Vibe coding: It said done. It wasn't.; It forgot what you decided; Two agents, one file; You review every line. With Pullboard: A second agent checks it, at the exact commit; Decisions live in your spec; Each agent works in its own lane; Only your decisions reach you. On Pullboard's own board, 4 to 16 October 2026: 1 in 4 times an agent said done, a second agent sent it back (227 of 908), and 588 merged, 0 of them without an accept.](docs/img/why.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/why-dark.svg">
+ <img src="docs/img/why.svg" alt="Where vibe coding breaks, and what holds instead. Pullboard enforces each fix, so none of it depends on you watching. Vibe coding: It said done. It wasn't.; It forgot what you decided; Two agents, one file; You review every line. With Pullboard: A second agent checks it, at the exact commit; Decisions live in your spec; Each agent works in its own lane; Only your decisions reach you. On Pullboard's own board, 4 to 16 October 2026: 1 in 4 times an agent said done, a second agent sent it back (227 of 908), and 588 merged, 0 of them without an accept.">
+</picture>
## How it works
@@ -73,7 +85,10 @@ Pullboard gives agents a shared plan, separate lanes and proof before work count
- **Lanes.** Each agent works in its own worktree. Claims are atomic, and items can wait on others.
- **Proof.** Submit needs a green gate. Then a different agent verifies that exact commit.
-![How work moves. You decide the rows of SPEC.md. An item freezes its bar when an agent claims it. Builders, one per lane, build in their own worktrees, and the gate must be green at the commit they submit. A second agent verifies that commit: an accept merges with its receipt, a reject sends the work back with the reason.](docs/img/loop.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/loop-dark.svg">
+ <img src="docs/img/loop.svg" alt="How work moves. You decide the rows of SPEC.md. An item freezes its bar when an agent claims it. Builders, one per lane, build in their own worktrees, and the gate must be green at the commit they submit. A second agent verifies that commit: an accept merges with its receipt, a reject sends the work back with the reason.">
+</picture>
<sub>You decide what to build. Agents build it and check each other's work. This is the Agentic Development Lifecycle (ADLC).</sub>
@@ -81,7 +96,10 @@ Pullboard gives agents a shared plan, separate lanes and proof before work count
Agents ask when a call isn't theirs to make. Their coordinator settles what it can, and only your calls reach you.
-![An agent asks its coordinator. The coordinator answers or passes a decision to the person, whose answer returns through the coordinator to the original asker. Agents send decision requests to their coordinator first.](docs/img/chain.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/chain-dark.svg">
+ <img src="docs/img/chain.svg" alt="An agent asks its coordinator. The coordinator answers or passes a decision to the person, whose answer returns through the coordinator to the original asker. Agents send decision requests to their coordinator first.">
+</picture>
> [!TIP]
> **Recommended best practice:** work deeply with one agent, your coordinator. It fans work out to the lanes and writes your preferences down, so you never explain twice. Always let one agent lead the others.
@@ -147,13 +165,19 @@ pullboard view
Every item's state, criterion and review history, with the calls only you can make at the top.
-![The desktop board shows open, claimed, submitted and accepted work, a Needs you row for a held lane, search in the top bar, the status bar, an accepted item's review history, and a stats line with merged work, sent-back share and the bottleneck recommendation.](docs/shots/desktop.png)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/shots/desktop-dark.png">
+ <img src="docs/shots/desktop-light.png" alt="The desktop board shows open, claimed, submitted and accepted work, a Needs you row for a held lane, search in the top bar, the status bar, an accepted item's review history, and a stats line with merged work, sent-back share and the bottleneck recommendation.">
+</picture>
### Shouts
The agents' conversation: decisions passed up to you, your answers, evidence and code references.
-![The Shouts tab shows the builder, reviewer and coordinator discussing a reviewed fix, the person's answered decision marked Heard, an evidence receipt and a code reference.](docs/shots/shouts.png)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/shots/shouts-dark.png">
+ <img src="docs/shots/shouts-light.png" alt="The Shouts tab shows the builder, reviewer and coordinator discussing a reviewed fix, the person's answered decision marked Heard, an evidence receipt and a code reference.">
+</picture>
### Roadmap
@@ -171,7 +195,10 @@ The same board in your pocket.
<details>
<summary>The board on a phone</summary>
-![The phone board in dark mode shows active work, a Needs you row for a held lane, search in the top bar, and a stats line with merged work, sent-back share and the bottleneck recommendation.](docs/shots/phone.png)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/shots/phone-dark.png">
+ <img src="docs/shots/phone-light.png" alt="The phone board shows active work, a Needs you row for a held lane, search in the top bar, and a stats line with merged work, sent-back share and the bottleneck recommendation.">
+</picture>
</details>
@@ -190,7 +217,10 @@ pullboard tour
On a throwaway repo, **you** approve one rule: greet a blank name as "world". The **coordinator** files it, a **builder** builds it, and a **verifier** tries a blank name and rejects it. The **builder** fixes it and adds a test. The **verifier** breaks the fix on purpose, sees the test fail, and accepts. The **coordinator** merges it with a receipt.
-![The timed Pullboard tour shows a change submitted, rejected for a missed edge, fixed and accepted.](docs/shots/tour.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/shots/tour-dark.svg">
+ <img src="docs/shots/tour.svg" alt="The timed Pullboard tour shows a change submitted, rejected for a missed edge, fixed and accepted.">
+</picture>
### Project setup
@@ -200,7 +230,10 @@ Give your agent this line in an empty or existing git repo.
Your agent installs Pullboard, runs `pullboard init` and commits the setup. It then walks you through setup in the view it opens. You approve your requirements and answer its questions.
-![Starting with an agent. You ask your agent to install Pullboard and set it up for what you're building. It runs the install and pullboard init, commits the setup, then walks you through your requirements and questions in the view it opens for you.](docs/img/agent-start.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/agent-start-dark.svg">
+ <img src="docs/img/agent-start.svg" alt="Starting with an agent. You ask your agent to install Pullboard and set it up for what you're building. It runs the install and pullboard init, commits the setup, then walks you through your requirements and questions in the view it opens for you.">
+</picture>
You can also run it yourself.
@@ -273,7 +306,10 @@ Every move follows one declaration, published in [docs/lifecycle.md](docs/lifecy
Items are state machines. Every item starts **open**. An agent claims it and it's **claimed**; if the agent goes quiet, it reopens. Once submitted, it's **submitted** until a verifier accepts it as **verified** or rejects it back to **open**. Only the coordinator can **withdraw** an item. The board refuses any move the declaration doesn't allow.
-![An item's life, drawn from src/machine.js: each state an item can be in, the moves between them, and the refusals every way into a final state can raise.](docs/img/lifecycle.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/lifecycle-dark.svg">
+ <img src="docs/img/lifecycle.svg" alt="An item's life, drawn from src/machine.js: each state an item can be in, the moves between them, and the refusals every way into a final state can raise.">
+</picture>
<sub>Drawn from one declaration, `src/machine.js`, which the commands, the view and the docs all share.</sub>
@@ -286,7 +322,10 @@ Everything lives in your repo. Nothing is hosted.
- **Submitted work:** pinned in git, so it survives a deleted worktree.
- **Backups:** `pullboard export` writes out the whole board.
-![Where things live. The main checkout is the coordinator and holds SPEC.md, DOCTRINE.md, pullboard.json, AGENTS.md and the git hooks. Inside .git, shared by every worktree, are the board and the pinned submitted commits. Beside it, each agent works in its own worktree, builders in their lanes and a verifier, all on the same board. pullboard view lists every project on this machine.](docs/img/layout.svg)
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/layout-dark.svg">
+ <img src="docs/img/layout.svg" alt="Where things live. The main checkout is the coordinator and holds SPEC.md, DOCTRINE.md, pullboard.json, AGENTS.md and the git hooks. Inside .git, shared by every worktree, are the board and the pinned submitted commits. Beside it, each agent works in its own worktree, builders in their lanes and a verifier, all on the same board. pullboard view lists every project on this machine.">
+</picture>
### Configuration
diff --git a/docs/img/agent-start-dark.svg b/docs/img/agent-start-dark.svg
new file mode 100644
index 00000000..018293f3
--- /dev/null
+++ b/docs/img/agent-start-dark.svg
@@ -0,0 +1,76 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 476" width="840" height="476" role="img" aria-labelledby="title desc">
+<title id="title">Starting with an agent</title><desc id="desc">You run pullboard init in your git repo, commit what it wrote, open a new Claude Code session in that folder and say what to build. That agent becomes the coordinator: it takes the spec with you, and only you approve a row; it proposes lanes and plans items with frozen bars; it starts a builder subagent per lane in its own worktree and a verifier that built none of it; it merges verified work only, and reports.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="475" rx="12"/>
+<text class="head" x="24" y="34">Starting with an agent</text>
+<rect class="frame" x="24" y="52" width="388" height="400" rx="10"/>
+<rect class="frame" x="428" y="52" width="388" height="400" rx="10"/>
+<text class="t1" x="44" y="78">You, once</text>
+<text class="t1" x="448" y="78">The agent, as coordinator</text>
+<g class="person"><rect x="44" y="92" width="348" height="56" rx="8"/><text class="t1" x="218" y="116" text-anchor="middle">pullboard init</text><text class="t2" x="218" y="134" text-anchor="middle">in your project's git repo</text></g>
+<g class="person"><rect x="44" y="188" width="348" height="56" rx="8"/><text class="t1" x="218" y="212" text-anchor="middle">Commit what init wrote</text><text class="t2" x="218" y="230" text-anchor="middle">git add -A, then git commit</text></g>
+<g class="person"><rect x="44" y="284" width="348" height="56" rx="8"/><text class="t1" x="218" y="308" text-anchor="middle">Open a new session</text><text class="t2" x="218" y="326" text-anchor="middle">Claude Code, in that folder</text></g>
+<g class="person"><rect x="44" y="380" width="348" height="56" rx="8"/><text class="t1" x="218" y="404" text-anchor="middle">Say what to build</text><text class="t2" x="218" y="422" text-anchor="middle">&quot;use pullboard to build …&quot;</text></g>
+<path class="edge" d="M 218 148 L 218 184" marker-end="url(#tip)"/>
+<path class="edge" d="M 218 244 L 218 280" marker-end="url(#tip)"/>
+<path class="edge" d="M 218 340 L 218 376" marker-end="url(#tip)"/>
+<g class="agent"><rect x="448" y="92" width="348" height="56" rx="8"/><text class="t1" x="622" y="116" text-anchor="middle">Spec with you</text><text class="t2" x="622" y="134" text-anchor="middle">only you approve a row</text></g>
+<g class="agent"><rect x="448" y="164" width="348" height="56" rx="8"/><text class="t1" x="622" y="188" text-anchor="middle">Lanes and a plan</text><text class="t2" x="622" y="206" text-anchor="middle">items with frozen bars</text></g>
+<g class="agent"><rect x="448" y="236" width="348" height="56" rx="8"/><text class="t1" x="622" y="260" text-anchor="middle">A builder per lane</text><text class="t2" x="622" y="278" text-anchor="middle">subagents in worktrees</text></g>
+<g class="agent"><rect x="448" y="308" width="348" height="56" rx="8"/><text class="t1" x="622" y="332" text-anchor="middle">A verifier</text><text class="t2" x="622" y="350" text-anchor="middle">built none of it, checks each</text></g>
+<g class="done"><rect x="448" y="380" width="348" height="56" rx="8"/><text class="t1" x="622" y="404" text-anchor="middle">Merge and report</text><text class="t2" x="622" y="422" text-anchor="middle">verified work only</text></g>
+<path class="edge" d="M 622 148 L 622 160" marker-end="url(#tip)"/>
+<path class="edge" d="M 622 220 L 622 232" marker-end="url(#tip)"/>
+<path class="edge" d="M 622 292 L 622 304" marker-end="url(#tip)"/>
+<path class="edge" d="M 622 364 L 622 376" marker-end="url(#tip)"/>
+<path class="edge" d="M 392 408 L 420 408 L 420 120 L 444 120" marker-end="url(#tip)"/>
+</svg>
diff --git a/docs/img/agent-start.svg b/docs/img/agent-start.svg
index c4538d0b..2dac448c 100644
--- a/docs/img/agent-start.svg
+++ b/docs/img/agent-start.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
diff --git a/docs/img/chain-dark.svg b/docs/img/chain-dark.svg
new file mode 100644
index 00000000..1e5381f6
--- /dev/null
+++ b/docs/img/chain-dark.svg
@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 416" width="840" height="416" role="img" aria-labelledby="title desc">
+<title id="title">Questions go one step up</title><desc id="desc">An agent asks its coordinator. The coordinator answers or passes a decision to the person. The person answers through the coordinator, who returns the answer to the original asker. An agent cannot ask the person directly.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="415" rx="12"/>
+<text class="head" x="24" y="34">Questions go one step up</text>
+<g class="agent"><rect x="50" y="58" width="180" height="54" rx="8"/><text class="t1" x="140" y="81" text-anchor="middle">Agent</text><text class="t2" x="140" y="99" text-anchor="middle">asks its coordinator</text></g>
+<g class="check"><rect x="330" y="58" width="180" height="54" rx="8"/><text class="t1" x="420" y="81" text-anchor="middle">Coordinator</text><text class="t2" x="420" y="99" text-anchor="middle">answers or passes it up</text></g>
+<g class="person"><rect x="610" y="58" width="180" height="54" rx="8"/><text class="t1" x="700" y="81" text-anchor="middle">Person</text><text class="t2" x="700" y="99" text-anchor="middle">answers when asked</text></g>
+<path class="edge leader" d="M 140 116 L 140 383"/>
+<path class="edge leader" d="M 420 116 L 420 383"/>
+<path class="edge leader" d="M 700 116 L 700 383"/>
+<path class="edge" d="M 140 154 L 420 154" marker-end="url(#tip)"/>
+<text class="label" x="280" y="146" text-anchor="middle">question</text>
+<path class="edge" d="M 420 204 L 140 204" marker-end="url(#tip)"/>
+<text class="label" x="280" y="196" text-anchor="middle">answer</text>
+<path class="edge" d="M 420 254 L 700 254" marker-end="url(#tip)"/>
+<text class="label" x="560" y="246" text-anchor="middle">pass decision up</text>
+<path class="edge" d="M 700 304 L 420 304" marker-end="url(#tip)"/>
+<text class="label" x="560" y="296" text-anchor="middle">person answers</text>
+<path class="edge" d="M 420 354 L 140 354" marker-end="url(#tip)"/>
+<text class="label" x="280" y="346" text-anchor="middle">return answer to asker</text>
+<text class="aside" x="420" y="400" text-anchor="middle">Agents cannot send a decision straight to the person.</text>
+</svg>
diff --git a/docs/img/chain.svg b/docs/img/chain.svg
index dfe8e1cd..c0375f58 100644
--- a/docs/img/chain.svg
+++ b/docs/img/chain.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
diff --git a/docs/img/draw.mjs b/docs/img/draw.mjs
index dbb7f75b..5878a17a 100644
--- a/docs/img/draw.mjs
+++ b/docs/img/draw.mjs
@@ -11,6 +11,7 @@ import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { MACHINE } from '../../src/machine.js';
+import { themeVariants } from './theme.mjs';
const SANS = "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif";
const MONO = "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace";
@@ -591,7 +592,9 @@ export const FIGURES = { loop: drawLoop, lifecycle: drawLifecycle, layout: drawL
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
for (const [name, draw] of Object.entries(FIGURES)) {
- writeFileSync(join(import.meta.dirname, `${name}.svg`), draw());
- console.log(`drew docs/img/${name}.svg`);
+ const { light, dark } = themeVariants(draw());
+ writeFileSync(join(import.meta.dirname, `${name}.svg`), light);
+ writeFileSync(join(import.meta.dirname, `${name}-dark.svg`), dark);
+ console.log(`drew docs/img/${name}.svg and docs/img/${name}-dark.svg`);
}
}
diff --git a/docs/img/factory-dark.svg b/docs/img/factory-dark.svg
new file mode 100644
index 00000000..a5fa1e0f
--- /dev/null
+++ b/docs/img/factory-dark.svg
@@ -0,0 +1,108 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 564" width="840" height="564" role="img" aria-labelledby="title desc">
+<title id="title">You leave. It builds.</title><desc id="desc">One night on Pullboard's own board, 16 October 2026: 38 agents, 9.6 hours from 11:17 pm to 8:51 am, with no moves from the person. 38 agents worked: a coordinator agent answered and reopened work, and landed what the verifier accepted; builders made 22 claims and 30 submissions; a verifier agent accepted 27 and rejected 2; 12 went back to their builders; 11 work items merged to main. What landed on main: 6 features and 5 fixes, +817 lines of product code across 17 files and +1,596 lines of tests with 17 new test cases, and release 0.8.27 on npm at 7:56 am. Among the features: The view signs in and links every board; pullboard.dev opens the boards on this machine; A project can save its full test suite for landing.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="563" rx="12"/>
+<style>
+text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
+.card{fill:#fff;stroke:#dce5df}.title{font-size:16px;font-weight:650;fill:#101714}.sub{font-size:12px;fill:#4f5b55}
+.zone{fill:none;stroke:#c9d4cd;stroke-dasharray:4 4}.zl{font-size:10.5px;font-weight:650;letter-spacing:.08em;fill:#65746b}
+.h{font-size:13px;font-weight:650;fill:#101714}.m{font-size:11.5px;fill:#4f5b55}.n{font-size:18px;font-weight:650;fill:#101714;font-variant-numeric:tabular-nums}
+.nb{font-size:30px;font-weight:700;fill:#0b5d3a;font-variant-numeric:tabular-nums}.hl{font-weight:700;fill:#0b5d3a}.stamp{fill:none;stroke:#1f8a5a;stroke-width:2}.stamp.in{stroke-width:1;opacity:.55}.stw{font-size:24px;font-weight:800;letter-spacing:.14em;fill:#1f8a5a}.sts{font-size:10px;font-weight:800;letter-spacing:.24em;fill:#1f8a5a}
+.you{fill:#e8f0f8;stroke:#9bb7d4}.plain{fill:#fff;stroke:#c9d4cd}.rows{fill:#efe9ff;stroke:#b9a6f0}.ver{fill:#dff4e8;stroke:#9fd6b6}.bld{fill:#fdf6e3;stroke:#e2c98a}.lay{fill:#f6f8f7;stroke:#c9d4cd}
+.ln{stroke:#65746b;stroke-width:1.5;fill:none}.ln.d{stroke-dasharray:5 4}.hd{fill:#65746b}.dot{fill:#65746b}.ship{fill:#1f8a5a}
+.pill{fill:#fff;stroke:#dce5df}.pill.ok{fill:#dff4e8;stroke:#9fd6b6}.pt{font-size:11px;fill:#4f5b55}.pt.ok{fill:#0b5d3a;font-weight:600}
+.h.sm{font-size:12.5px}.okl{stroke:#1f8a5a}
+.ico{fill:none;stroke:#65746b;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
+.card{fill:#111714;stroke:#34443a}.title,.h,.n{fill:#e9eeeb}.sub,.m,.pt{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
+.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.lay{fill:#18201c;stroke:#3a4a40}
+.ln{stroke:#9cafa3}.hd,.dot{fill:#9cafa3}.ship{fill:#4cc38a}.pill{fill:#111714;stroke:#34443a}.pill.ok{fill:#163829;stroke:#2f7a55}.pt.ok{fill:#8fe0b6}.nb,.hl{fill:#8fe0b6}.stamp{stroke:#4cc38a}.stw,.sts{fill:#4cc38a}.ico{stroke:#9cafa3}.okl{stroke:#4cc38a}
+</style>
+<defs><marker id="tip-f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path class="hd" d="M0 1 L9 5 L0 9 z"/></marker></defs>
+<text class="title" x="24" y="34">You leave. It builds.</text>
+<text class="sub" x="24" y="54">One night on Pullboard’s own board, 16 Oct: 9.6 hours with no moves from the person.</text>
+<rect class="zone" x="24" y="72" width="792" height="102" rx="10"/>
+<text class="zl" x="38" y="94">THE NIGHT</text>
+<rect class="you" x="48" y="110" width="132" height="48" rx="8"/>
+<text class="h" x="114" y="131" text-anchor="middle">You leave</text>
+<text class="m" x="114" y="147" text-anchor="middle">11:17 pm</text>
+<rect class="you" x="660" y="110" width="132" height="48" rx="8"/>
+<text class="h" x="726" y="131" text-anchor="middle">You’re back</text>
+<text class="m" x="726" y="147" text-anchor="middle">8:51 am</text>
+<line class="ln d" x1="180" y1="134" x2="660" y2="134"/>
+<rect class="pill" x="299.5534843205575" y="123" width="194.89999999999998" height="22" rx="11"/><text class="pt" x="397.0034843205575" y="138" text-anchor="middle">9.6 hours · no moves from you</text>
+<line class="ln" x1="614.006968641115" y1="134" x2="614.006968641115" y2="116"/>
+<circle class="ship" cx="614.006968641115" cy="134" r="5"/>
+<rect class="pill ok" x="497.79999999999995" y="94" width="152.2" height="22" rx="11"/><text class="pt ok" x="573.9" y="109" text-anchor="middle">0.8.27 ships · 7:56 am</text>
+<rect class="zone" x="24" y="186" width="792" height="180" rx="10"/>
+<text class="zl" x="38" y="208">WHAT THE AGENTS DID · 38 AGENTS</text>
+<rect class="lay" x="48" y="263" width="156" height="48" rx="8"/><text class="h" x="126" y="284" text-anchor="middle">Coordinator</text><text class="m" x="126" y="301" text-anchor="middle">answers, reopens</text>
+<rect class="bld" x="244" y="263" width="156" height="48" rx="8"/><text class="h" x="322" y="284" text-anchor="middle">Builders</text><text class="m" x="322" y="301" text-anchor="middle">22 claims · 30 submitted</text>
+<rect class="rows" x="440" y="263" width="156" height="48" rx="8"/><text class="h" x="518" y="284" text-anchor="middle">A verifier agent</text><text class="m" x="518" y="301" text-anchor="middle">27 accepted · 2 rejected</text>
+<rect class="ver" x="636" y="263" width="156" height="48" rx="8"/><text class="h" x="714" y="284" text-anchor="middle">main</text><text class="m" x="714" y="301" text-anchor="middle">11 work items merged</text>
+<line class="ln" x1="204" y1="287" x2="242" y2="287" marker-end="url(#tip-f)"/>
+<line class="ln" x1="400" y1="287" x2="438" y2="287" marker-end="url(#tip-f)"/>
+<line class="ln" x1="596" y1="287" x2="634" y2="287" marker-end="url(#tip-f)"/>
+<path class="ln d" d="M714 263 V235 H322 V261" marker-end="url(#tip-f)"/>
+<rect class="pill" x="432.4" y="224" width="91.19999999999999" height="22" rx="11"/><text class="pt" x="478" y="239" text-anchor="middle">12 sent back</text>
+<path class="ln d" d="M126 311 V339 H672 V313" marker-end="url(#tip-f)"/>
+<rect class="pill" x="411.05" y="328" width="133.89999999999998" height="22" rx="11"/><text class="pt" x="478" y="343" text-anchor="middle">lands accepted work</text>
+<line class="ln" x1="714" y1="311" x2="714" y2="376" marker-end="url(#tip-f)"/>
+<rect class="zone" x="24" y="378" width="792" height="166" rx="10"/>
+<text class="zl" x="38" y="400">WHAT LANDED ON MAIN BY MORNING</text>
+<rect class="ver" x="48" y="416" width="139.2" height="62" rx="8"/><text class="n" x="62" y="443">6</text><text class="m" x="62" y="462">features shipped</text>
+<rect class="bld" x="199.2" y="416" width="139.2" height="62" rx="8"/><text class="n" x="213.2" y="443">5</text><text class="m" x="213.2" y="462">fixes landed</text>
+<rect class="rows" x="350.4" y="416" width="139.2" height="62" rx="8"/><text class="n" x="364.4" y="443">+817</text><text class="m" x="364.4" y="462">lines of product code</text>
+<rect class="you" x="501.59999999999997" y="416" width="139.2" height="62" rx="8"/><text class="n" x="515.5999999999999" y="443">+1,596</text><text class="m" x="515.5999999999999" y="462">lines of tests</text>
+<rect class="lay" x="652.8" y="416" width="139.2" height="62" rx="8"/><text class="n" x="666.8" y="443">0.8.27</text><text class="m" x="666.8" y="462">released to npm</text>
+<text class="h sm" x="48" y="502">Among the features</text>
+<text class="m" x="48" y="524">The view signs in and links every board · pullboard.dev opens the boards on this machine · A project can save its full test suite for landing</text>
+</svg>
diff --git a/docs/img/factory.svg b/docs/img/factory.svg
index 27cdfbe7..969cbdfe 100644
--- a/docs/img/factory.svg
+++ b/docs/img/factory.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
@@ -62,9 +44,7 @@ text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
.pill{fill:#fff;stroke:#dce5df}.pill.ok{fill:#dff4e8;stroke:#9fd6b6}.pt{font-size:11px;fill:#4f5b55}.pt.ok{fill:#0b5d3a;font-weight:600}
.h.sm{font-size:12.5px}.okl{stroke:#1f8a5a}
.ico{fill:none;stroke:#65746b;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
-@media(prefers-color-scheme:dark){.card{fill:#111714;stroke:#34443a}.title,.h,.n{fill:#e9eeeb}.sub,.m,.pt{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
-.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.lay{fill:#18201c;stroke:#3a4a40}
-.ln{stroke:#9cafa3}.hd,.dot{fill:#9cafa3}.ship{fill:#4cc38a}.pill{fill:#111714;stroke:#34443a}.pill.ok{fill:#163829;stroke:#2f7a55}.pt.ok{fill:#8fe0b6}.nb,.hl{fill:#8fe0b6}.stamp{stroke:#4cc38a}.stw,.sts{fill:#4cc38a}.ico{stroke:#9cafa3}.okl{stroke:#4cc38a}}
+
</style>
<defs><marker id="tip-f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path class="hd" d="M0 1 L9 5 L0 9 z"/></marker></defs>
<text class="title" x="24" y="34">You leave. It builds.</text>
diff --git a/docs/img/holds-dark.svg b/docs/img/holds-dark.svg
new file mode 100644
index 00000000..1aab0aac
--- /dev/null
+++ b/docs/img/holds-dark.svg
@@ -0,0 +1,100 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 374" width="960" height="374" role="img" aria-labelledby="title desc">
+<title id="title">Judgement accumulates</title><desc id="desc">You approve decisions once, as spec rows, doctrine and answers. The board keeps them as the project's record, with a frozen bar for each item, every verdict and its reason, and the exact commit each verdict checked. A builder agent and a second agent both receive the item's frozen bar, and either can query the whole record at any time: the approved rows, every frozen bar, earlier proofs and every verdict with its reason; the builder hands over its exact commit, and the second agent checks it against the bar and writes the verdict and reason back to the record. Only your calls come back to you. Every item adds to the record, and every new session starts from all of it.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="959" height="373" rx="12"/>
+<style>
+text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
+.card{fill:#fff;stroke:#dce5df}.title{font-size:16px;font-weight:650;fill:#101714}.sub{font-size:12px;fill:#4f5b55}
+.zone{fill:none;stroke:#c9d4cd;stroke-dasharray:4 4}.zl{font-size:10.5px;font-weight:650;letter-spacing:.08em;fill:#65746b}
+.b{stroke-width:1}.h{font-size:13px;font-weight:650;fill:#101714}.m{font-size:11.5px;fill:#4f5b55}
+.you{fill:#e8f0f8;stroke:#9bb7d4}.plain{fill:#fff;stroke:#c9d4cd}.rows{fill:#efe9ff;stroke:#b9a6f0}.lay{fill:#f6f8f7;stroke:#c9d4cd}.ver{fill:#dff4e8;stroke:#9fd6b6}.bld{fill:#fdf6e3;stroke:#e2c98a}.youL{fill:#e8f0f8;stroke:#9bb7d4}.youL2{fill:#f3f7fb;stroke:#9bb7d4;stroke-dasharray:3 2}.bldL{fill:#fdf6e3;stroke:#e2c98a}.chkL{fill:#efe9ff;stroke:#b9a6f0}.key{font-size:10.5px;fill:#65746b}.chk{fill:#efe9ff;stroke:#b9a6f0}
+.ln{stroke:#65746b;stroke-width:1.5;fill:none}.ln.d{stroke-dasharray:5 4}.hd{fill:#65746b}
+.pill{fill:#fff;stroke:#dce5df}.pt{font-size:11px;fill:#4f5b55}
+.cap{font-size:12.5px;fill:#4f5b55}
+.card{fill:#111714;stroke:#34443a}.title,.h{fill:#e9eeeb}.sub,.m,.pt,.cap{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
+.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.lay{fill:#18201c;stroke:#3a4a40}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.youL{fill:#14243a;stroke:#3f6a96}.youL2{fill:#101b2b;stroke:#3f6a96;stroke-dasharray:3 2}.bldL{fill:#2e2614;stroke:#8a6f2c}.chkL{fill:#231d3a;stroke:#6b57b8}.key{fill:#9cafa3}.chk{fill:#231d3a;stroke:#6b57b8}
+.ln{stroke:#9cafa3}.hd{fill:#9cafa3}.pill{fill:#111714;stroke:#34443a}
+</style>
+<defs>
+<linearGradient id="grow" x1="0" x2="1"><stop offset="0" stop-color="#087546" stop-opacity="0.08"/><stop offset="1" stop-color="#087546" stop-opacity="0.85"/></linearGradient>
+</defs>
+<text class="title" x="24" y="34">Judgement accumulates</text>
+<text class="sub" x="24" y="54">Every piece of work starts from everything decided and proved before it.</text>
+<rect class="zone" x="24" y="92" width="190" height="252" rx="10"/><text class="zl" x="38" y="112">YOU</text>
+<rect class="zone" x="304" y="92" width="352" height="252" rx="10"/><text class="zl" x="318" y="112">THE BOARD · THE PROJECT'S RECORD</text>
+<rect class="zone" x="746" y="92" width="190" height="252" rx="10"/><text class="zl" x="760" y="112">AGENTS · ONE LANE EACH</text>
+<rect class="you b" x="38" y="122" width="162" height="60" rx="8"/><text class="h" x="119" y="147" text-anchor="middle">Your decisions</text><text class="m" x="119" y="165" text-anchor="middle">rows · doctrine · answers</text>
+<rect class="plain b" x="38" y="252" width="162" height="60" rx="8"/><text class="h" x="119" y="277" text-anchor="middle">Only your calls</text><text class="m" x="119" y="295" text-anchor="middle">questions passed up</text>
+<rect class="youL b" x="322" y="122" width="316" height="38" rx="7"/><text class="h" x="336" y="146">Approved rows</text><text class="m" x="624" y="146" text-anchor="end">what must be true</text>
+<rect class="youL2 b" x="322" y="168" width="316" height="38" rx="7"/><text class="h" x="336" y="192">Frozen bars</text><text class="m" x="624" y="192" text-anchor="end">one per item, from the rows</text>
+<rect class="chkL b" x="322" y="260" width="316" height="38" rx="7"/><text class="h" x="336" y="284">Verdicts</text><text class="m" x="624" y="284" text-anchor="end">every accept and reject, with the reason</text>
+<rect class="bldL b" x="322" y="214" width="316" height="38" rx="7"/><text class="h" x="336" y="238">Proofs</text><text class="m" x="624" y="238" text-anchor="end">the exact commit each verdict checked</text>
+<rect x="322" y="310" width="316" height="7" rx="3.5" fill="url(#grow)"/>
+<text class="m" x="480" y="334" text-anchor="middle">each item adds to the record · each session starts from it</text>
+<rect class="bld b" x="760" y="122" width="162" height="60" rx="8"/><text class="h" x="841" y="147" text-anchor="middle">Builder</text><text class="m" x="841" y="165" text-anchor="middle">builds to the bar</text>
+<rect class="chk b" x="760" y="252" width="162" height="60" rx="8"/><text class="h" x="841" y="277" text-anchor="middle">Second agent</text><text class="m" x="841" y="295" text-anchor="middle">checks it against the bar</text>
+<path class="ln" d="M200 141 H316"/><path class="hd" d="M322 141 l-8 -4.5 v9 z"/>
+<rect class="pill" x="219" y="131" width="80" height="20" rx="10"/><text class="pt" x="259" y="145" text-anchor="middle">approve once</text>
+<path class="ln" d="M638 187 H736 V152 H754"/><path class="hd" d="M760 152 l-8 -4.5 v9 z"/>
+<path class="ln" d="M736 187 V262 H754"/><path class="hd" d="M760 262 l-8 -4.5 v9 z"/>
+<circle cx="736" cy="187" r="3" class="hd"/>
+<path class="ln d" d="M922 282 H946 V66 H480 V86"/><path class="hd" d="M480 92 l-4.5 -8 h9 z"/>
+<path class="ln d" d="M922 152 H946"/><circle cx="946" cy="152" r="3" class="hd"/>
+<rect class="pill" x="652" y="56" width="96" height="20" rx="10"/><text class="pt" x="700" y="70" text-anchor="middle">query any time</text>
+<rect class="pill" x="653" y="177" width="70" height="20" rx="10"/><text class="pt" x="688" y="191" text-anchor="middle">frozen bar</text>
+<path class="ln" d="M841 182 V246"/><path class="hd" d="M841 252 l-4.5 -8 h9 z"/>
+<rect class="pill" x="799" y="207" width="84" height="20" rx="10"/><text class="pt" x="841" y="221" text-anchor="middle">exact commit</text>
+<path class="ln" d="M760 279 H644"/><path class="hd" d="M638 279 l8 -4.5 v9 z"/>
+<rect class="pill" x="661" y="269" width="96" height="20" rx="10"/><text class="pt" x="709" y="283" text-anchor="middle">verdict + reason</text>
+<path class="ln d" d="M304 282 H206"/><path class="hd" d="M200 282 l8 -4.5 v9 z"/>
+<rect class="pill" x="223" y="272" width="64" height="20" rx="10"/><text class="pt" x="255" y="286" text-anchor="middle">your calls</text>
+</svg>
diff --git a/docs/img/holds.svg b/docs/img/holds.svg
index 49aa513f..19c02c67 100644
--- a/docs/img/holds.svg
+++ b/docs/img/holds.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
@@ -60,9 +42,7 @@ text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
.ln{stroke:#65746b;stroke-width:1.5;fill:none}.ln.d{stroke-dasharray:5 4}.hd{fill:#65746b}
.pill{fill:#fff;stroke:#dce5df}.pt{font-size:11px;fill:#4f5b55}
.cap{font-size:12.5px;fill:#4f5b55}
-@media(prefers-color-scheme:dark){.card{fill:#111714;stroke:#34443a}.title,.h{fill:#e9eeeb}.sub,.m,.pt,.cap{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
-.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.lay{fill:#18201c;stroke:#3a4a40}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.youL{fill:#14243a;stroke:#3f6a96}.youL2{fill:#101b2b;stroke:#3f6a96;stroke-dasharray:3 2}.bldL{fill:#2e2614;stroke:#8a6f2c}.chkL{fill:#231d3a;stroke:#6b57b8}.key{fill:#9cafa3}.chk{fill:#231d3a;stroke:#6b57b8}
-.ln{stroke:#9cafa3}.hd{fill:#9cafa3}.pill{fill:#111714;stroke:#34443a}}
+
</style>
<defs>
<linearGradient id="grow" x1="0" x2="1"><stop offset="0" stop-color="#087546" stop-opacity="0.08"/><stop offset="1" stop-color="#087546" stop-opacity="0.85"/></linearGradient>
diff --git a/docs/img/layout-dark.svg b/docs/img/layout-dark.svg
new file mode 100644
index 00000000..bbeade2a
--- /dev/null
+++ b/docs/img/layout-dark.svg
@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 404" width="840" height="404" role="img" aria-labelledby="title desc">
+<title id="title">Where things live</title><desc id="desc">The main checkout is the coordinator. It holds SPEC.md, DOCTRINE.md, pullboard.json, AGENTS.md and the git hooks. Inside .git, shared by every worktree, are the board, board.sqlite, and the pinned submitted commits. Beside it, each agent works in its own worktree: builders in their lanes and a verifier that built none of it, all on the same board. pullboard view lists every project on this machine.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="403" rx="12"/>
+<text class="head" x="24" y="34">Where things live</text>
+<rect class="frame" x="24" y="52" width="400" height="328" rx="10"/>
+<text class="t1" x="44" y="80">your repo: the main checkout</text>
+<text class="aside" x="44" y="98">the coordinator files, merges and talks with you</text>
+<text class="mono label" x="44" y="130">SPEC.md</text>
+<text class="label" x="204" y="130">what to build, one row per id</text>
+<text class="mono label" x="44" y="152">DOCTRINE.md</text>
+<text class="label" x="204" y="152">the house rules</text>
+<text class="mono label" x="44" y="174">pullboard.json</text>
+<text class="label" x="204" y="174">gate, lanes, commit rules</text>
+<text class="mono label" x="44" y="196">AGENTS.md, .claude/</text>
+<text class="label" x="204" y="196">how agents work here</text>
+<text class="mono label" x="44" y="218">.githooks/</text>
+<text class="label" x="204" y="218">commit and push checks</text>
+<g class="plain"><rect x="44" y="236" width="360" height="126" rx="8"/></g>
+<text class="t1 mono" x="60" y="260">.git, shared by every worktree</text>
+<text class="mono label" x="60" y="288">pullboard/board.sqlite</text>
+<text class="aside" x="60" y="305">items, claims, verdicts, shouts</text>
+<text class="mono label" x="60" y="333">refs/pullboard/items</text>
+<text class="aside" x="60" y="350">every submitted commit, pinned</text>
+<g class="agent"><rect x="480" y="60" width="336" height="56" rx="8"/><text class="t1 mono" x="648" y="84" text-anchor="middle">../repo-web-1</text><text class="t2" x="648" y="102" text-anchor="middle">builder · web lane</text></g>
+<g class="agent"><rect x="480" y="140" width="336" height="56" rx="8"/><text class="t1 mono" x="648" y="164" text-anchor="middle">../repo-api-1</text><text class="t2" x="648" y="182" text-anchor="middle">builder · api lane</text></g>
+<g class="agent"><rect x="480" y="220" width="336" height="56" rx="8"/><text class="t1 mono" x="648" y="244" text-anchor="middle">../repo-review-1</text><text class="t2" x="648" y="262" text-anchor="middle">verifier · built none of it</text></g>
+<path class="edge" d="M 480 88 L 452 88"/>
+<path class="edge" d="M 480 168 L 452 168"/>
+<path class="edge" d="M 480 248 L 452 248"/>
+<path class="edge" d="M 452 88 L 452 300 L 408 300" marker-end="url(#tip)"/>
+<text class="aside" x="470" y="300">one board: every worktree reads and writes it</text>
+<g class="person"><rect x="480" y="320" width="336" height="56" rx="8"/><text class="t1 mono" x="648" y="344" text-anchor="middle">~/.pullboard/projects.json</text><text class="t2" x="648" y="362" text-anchor="middle">pullboard view: every project here</text></g>
+</svg>
diff --git a/docs/img/layout.svg b/docs/img/layout.svg
index 1d99dddd..115d3d78 100644
--- a/docs/img/layout.svg
+++ b/docs/img/layout.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
diff --git a/docs/img/lifecycle-dark.svg b/docs/img/lifecycle-dark.svg
new file mode 100644
index 00000000..57bfce1b
--- /dev/null
+++ b/docs/img/lifecycle-dark.svg
@@ -0,0 +1,91 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 392" width="840" height="392" role="img" aria-labelledby="title desc">
+<title id="title">An item's life</title><desc id="desc">Drawn from src/machine.js. An item starts open and ends withdrawn. open to claimed: claim. claimed to open: release, lapse (clock), escalate, refreeze. claimed to submitted: submit. submitted to verified: accept. submitted to open: reject, reopen, refreeze. verified to open: reject, reopen. open to withdrawn: withdraw. claimed to withdrawn: withdraw. submitted to withdrawn: withdraw.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="391" rx="12"/>
+<text class="head" x="24" y="34">An item's life</text>
+<text class="aside" x="140" y="34">starts open; ends withdrawn</text>
+<g class="plain"><rect x="25" y="150" width="160" height="58" rx="8"/><text class="t1" x="105" y="175" text-anchor="middle">open</text><text class="t2" x="105" y="193" text-anchor="middle">↻ escalate · refreeze</text></g>
+<g class="plain"><rect x="235" y="150" width="160" height="58" rx="8"/><text class="t1" x="315" y="175" text-anchor="middle">claimed</text><text class="t2" x="315" y="193" text-anchor="middle">↻ claim · refreeze</text></g>
+<g class="plain"><rect x="445" y="150" width="160" height="58" rx="8"/><text class="t1" x="525" y="175" text-anchor="middle">submitted</text><text class="t2" x="525" y="193" text-anchor="middle">↻ reserve</text></g>
+<g class="done"><rect x="655" y="150" width="160" height="58" rx="8"/><text class="t1" x="735" y="175" text-anchor="middle">verified</text><text class="t2" x="735" y="193" text-anchor="middle">↻ accept</text></g>
+<g class="plain" data-final="withdrawn"><rect x="445" y="284" width="160" height="58" rx="8"/><rect x="449" y="288" width="152" height="50" rx="5" fill="none"/><text class="t1" x="525" y="318" text-anchor="middle">withdrawn</text></g>
+<path class="edge" d="M 185 179 L 231 179" marker-end="url(#tip)"/>
+<text class="label" x="208" y="171" text-anchor="middle">claim</text>
+<path class="edge back" d="M 335 150 L 335 120 L 145 120 L 145 146" marker-end="url(#tip-back)"/>
+<text class="label back" x="240" y="94" text-anchor="middle">release · lapse (clock)</text>
+<text class="label back" x="240" y="109" text-anchor="middle">escalate · refreeze</text>
+<path class="edge" d="M 395 179 L 441 179" marker-end="url(#tip)"/>
+<text class="label" x="418" y="171" text-anchor="middle">submit</text>
+<path class="edge" d="M 605 179 L 651 179" marker-end="url(#tip)"/>
+<text class="label" x="628" y="171" text-anchor="middle">accept</text>
+<path class="edge back" d="M 545 150 L 545 66 L 115 66 L 115 146" marker-end="url(#tip-back)"/>
+<text class="label back" x="330" y="58" text-anchor="middle">reject · reopen · refreeze</text>
+<path class="edge back" d="M 815 179 L 830 179 L 830 8 L 15 8 L 15 179 L 25 179" marker-end="url(#tip-back)"/>
+<text class="label back" x="425" y="30" text-anchor="middle">reject · reopen</text>
+<path class="edge" d="M 105 208 L 105 313 L 441 313" marker-end="url(#tip)"/>
+<text class="label" x="210" y="305" text-anchor="middle">withdraw</text>
+<path class="edge" d="M 315 208 L 315 313"/>
+<path class="edge" d="M 525 208 L 525 280" marker-end="url(#tip)"/>
+<g class="plain"><rect x="640" y="26" width="176" height="94" rx="8"/></g>
+<text class="label" x="652" y="46">every way into verified</text>
+<text class="code mono" x="652" y="64">NOT_AT_COMMIT</text>
+<text class="code mono" x="652" y="80">SELF_VERIFY</text>
+<text class="code mono" x="652" y="96">CRITERIA_CHANGED</text>
+<text class="code mono" x="652" y="112">PROOF_REQUIRED</text>
+<path class="edge leader" d="M 735 122 L 735 146"/>
+<g class="plain"><rect x="640" y="284" width="176" height="62" rx="8"/></g>
+<text class="label" x="652" y="304">every way into withdrawn</text>
+<text class="code mono" x="652" y="322">COORDINATOR_ONLY</text>
+<text class="code mono" x="652" y="338">NOTE_REQUIRED</text>
+<path class="edge leader" d="M 640 313 L 609 313"/>
+<text class="aside" x="24" y="374">↻ a move that keeps the state · dashed: back to open · double border: final · codes: the refusal each guard raises</text>
+</svg>
diff --git a/docs/img/loop-dark.svg b/docs/img/loop-dark.svg
new file mode 100644
index 00000000..13d515ba
--- /dev/null
+++ b/docs/img/loop-dark.svg
@@ -0,0 +1,68 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 290" width="840" height="290" role="img" aria-labelledby="title desc">
+<title id="title">How work moves</title><desc id="desc">You approve spec rows. Each item freezes its bar when an agent claims it. Builders, one per lane, build in their own worktrees; the gate must be green at the commit they submit. A second agent verifies that commit: an accept merges with its receipt, a reject sends the work back to the builder with the reason.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="289" rx="12"/>
+<text class="head" x="24" y="34">How work moves</text>
+<g class="person"><rect x="40" y="62" width="200" height="64" rx="8"/><text class="t1" x="140" y="90" text-anchor="middle">You decide</text><text class="t2" x="140" y="108" text-anchor="middle">the rows of SPEC.md</text></g>
+<g class="plain"><rect x="320" y="62" width="200" height="64" rx="8"/><text class="t1" x="420" y="90" text-anchor="middle">An item</text><text class="t2" x="420" y="108" text-anchor="middle">its bar frozen at claim</text></g>
+<g class="agent"><rect x="610" y="52" width="200" height="64" rx="8"/><rect x="605" y="57" width="200" height="64" rx="8"/><rect x="600" y="62" width="200" height="64" rx="8"/><text class="t1" x="700" y="90" text-anchor="middle">Builders</text><text class="t2" x="700" y="108" text-anchor="middle">one per lane, own worktree</text></g>
+<g class="check"><rect x="600" y="200" width="200" height="64" rx="8"/><text class="t1" x="700" y="228" text-anchor="middle">The gate</text><text class="t2" x="700" y="246" text-anchor="middle">tests green at the commit</text></g>
+<g class="agent"><rect x="320" y="200" width="200" height="64" rx="8"/><text class="t1" x="420" y="228" text-anchor="middle">A verifier</text><text class="t2" x="420" y="246" text-anchor="middle">a second agent checks it</text></g>
+<g class="done"><rect x="40" y="200" width="200" height="64" rx="8"/><text class="t1" x="140" y="228" text-anchor="middle">Merged</text><text class="t2" x="140" y="246" text-anchor="middle">with its receipt</text></g>
+<path class="edge" d="M 240 94 L 316 94" marker-end="url(#tip)"/>
+<path class="edge" d="M 520 94 L 596 94" marker-end="url(#tip)"/>
+<path class="edge" d="M 700 126 L 700 196" marker-end="url(#tip)"/>
+<path class="edge" d="M 600 232 L 524 232" marker-end="url(#tip)"/>
+<path class="edge" d="M 320 232 L 244 232" marker-end="url(#tip)"/>
+<path class="edge back" d="M 440 200 L 440 166 L 650 166 L 650 140" marker-end="url(#tip-back)"/>
+<text class="label back" x="452" y="158">a reject sends it back</text>
+</svg>
diff --git a/docs/img/loop.svg b/docs/img/loop.svg
index 23b69dd8..252cb37b 100644
--- a/docs/img/loop.svg
+++ b/docs/img/loop.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
diff --git a/docs/img/theme.mjs b/docs/img/theme.mjs
new file mode 100644
index 00000000..092e00ed
--- /dev/null
+++ b/docs/img/theme.mjs
@@ -0,0 +1,62 @@
+/**
+ * Split one SVG that carries prefers-color-scheme blocks into the two files a README picture needs
+ * (I10, I13). GitHub resolves a <picture> source from the reader's theme, while an SVG drawn with
+ * its own media query follows the operating system instead, so each figure ships a light file and
+ * a dark file and the README picks between them.
+ *
+ * The split keeps the cascade exact: the dark file is the same CSS a dark browser applies, with each
+ * dark block unwrapped in place (later rules win, as they did under the media query), and the light
+ * file is the same CSS a light browser applies, with the dark blocks removed.
+ */
+
+const DARK_BLOCK = /@media\s*\(prefers-color-scheme:\s*dark\)\s*\{/gu;
+
+/**
+ * Find the brace that closes the block opened at `open`, so nested rules stay inside it.
+ *
+ * @param {string} svg the whole SVG text
+ * @param {number} open the index of the `{` that opens the block
+ * @returns {number} the index of the matching `}`
+ */
+function closingBrace(svg, open) {
+ let depth = 0;
+ for (let index = open; index < svg.length; index += 1) {
+ if (svg[index] === '{') depth += 1;
+ else if (svg[index] === '}') {
+ depth -= 1;
+ if (depth === 0) return index;
+ }
+ }
+ throw new Error('A prefers-color-scheme block in the figure is not closed.');
+}
+
+/**
+ * Rewrite every dark block in an SVG: keep its rules unwrapped, or drop them.
+ *
+ * @param {string} svg a figure as draw.mjs or tour-renderer.mjs returns it
+ * @param {boolean} keep true to unwrap the dark rules, false to remove them
+ * @returns {string} the SVG with its dark blocks rewritten
+ */
+function rewriteDarkBlocks(svg, keep) {
+ const pattern = new RegExp(DARK_BLOCK.source, 'gu');
+ let out = '';
+ let last = 0;
+ for (let match = pattern.exec(svg); match; match = pattern.exec(svg)) {
+ const open = match.index + match[0].length - 1;
+ const close = closingBrace(svg, open);
+ out += svg.slice(last, match.index) + (keep ? svg.slice(open + 1, close) : '');
+ last = close + 1;
+ pattern.lastIndex = last;
+ }
+ return out + svg.slice(last);
+}
+
+/**
+ * The light and dark files of one figure, so a <picture> can show each to its reader.
+ *
+ * @param {string} svg a figure with prefers-color-scheme blocks
+ * @returns {{ light: string, dark: string }} the light file and the dark file
+ */
+export function themeVariants(svg) {
+ return { light: rewriteDarkBlocks(svg, false), dark: rewriteDarkBlocks(svg, true) };
+}
diff --git a/docs/img/what-dark.svg b/docs/img/what-dark.svg
new file mode 100644
index 00000000..c51f87ad
--- /dev/null
+++ b/docs/img/what-dark.svg
@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 306" width="840" height="306" role="img" aria-labelledby="title desc">
+<title id="title">One board. Every agent. Every machine.</title><desc id="desc">One board. Every agent. Every machine. All of it is in Pullboard 0.9.0. Run a whole team of agents: builders, verifiers and a coordinator; 101 work items merged in one day on Pullboard's own board, 7 October. Your board, on your phone: Answer what’s waiting, anywhere. Sealed: the relay can’t read it. Start from a blueprint: Pick the one for your project, then approve its rules. Plug in any agent: Keep Claude Code or Codex, and add any MCP client. Across your machines: Pair a machine once. Its agents share your board, in one order.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="305" rx="12"/>
+<style>
+text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
+.card{fill:#fff;stroke:#dce5df}.title{font-size:16px;font-weight:650;fill:#101714}.sub{font-size:12px;fill:#4f5b55}
+.zone{fill:none;stroke:#c9d4cd;stroke-dasharray:4 4}.zl{font-size:10.5px;font-weight:650;letter-spacing:.08em;fill:#65746b}
+.h{font-size:13px;font-weight:650;fill:#101714}.m{font-size:11.5px;fill:#4f5b55}.n{font-size:18px;font-weight:650;fill:#101714;font-variant-numeric:tabular-nums}
+.nb{font-size:30px;font-weight:700;fill:#0b5d3a;font-variant-numeric:tabular-nums}.hl{font-weight:700;fill:#0b5d3a}.stamp{fill:none;stroke:#1f8a5a;stroke-width:2}.stamp.in{stroke-width:1;opacity:.55}.stw{font-size:24px;font-weight:800;letter-spacing:.14em;fill:#1f8a5a}.sts{font-size:10px;font-weight:800;letter-spacing:.24em;fill:#1f8a5a}
+.you{fill:#e8f0f8;stroke:#9bb7d4}.plain{fill:#fff;stroke:#c9d4cd}.rows{fill:#efe9ff;stroke:#b9a6f0}.ver{fill:#dff4e8;stroke:#9fd6b6}.bld{fill:#fdf6e3;stroke:#e2c98a}.lay{fill:#f6f8f7;stroke:#c9d4cd}
+.ln{stroke:#65746b;stroke-width:1.5;fill:none}.ln.d{stroke-dasharray:5 4}.hd{fill:#65746b}.dot{fill:#65746b}.ship{fill:#1f8a5a}
+.pill{fill:#fff;stroke:#dce5df}.pill.ok{fill:#dff4e8;stroke:#9fd6b6}.pt{font-size:11px;fill:#4f5b55}.pt.ok{fill:#0b5d3a;font-weight:600}
+.h.sm{font-size:12.5px}.okl{stroke:#1f8a5a}
+.ico{fill:none;stroke:#65746b;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
+.card{fill:#111714;stroke:#34443a}.title,.h,.n{fill:#e9eeeb}.sub,.m,.pt{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
+.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.lay{fill:#18201c;stroke:#3a4a40}
+.ln{stroke:#9cafa3}.hd,.dot{fill:#9cafa3}.ship{fill:#4cc38a}.pill{fill:#111714;stroke:#34443a}.pill.ok{fill:#163829;stroke:#2f7a55}.pt.ok{fill:#8fe0b6}.nb,.hl{fill:#8fe0b6}.stamp{stroke:#4cc38a}.stw,.sts{fill:#4cc38a}.ico{stroke:#9cafa3}.okl{stroke:#4cc38a}
+</style>
+<defs><marker id="tip-f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path class="hd" d="M0 1 L9 5 L0 9 z"/></marker></defs>
+<text class="title" x="24" y="34">One board. Every agent. Every machine.</text>
+<rect class="zone" x="24" y="54" width="792" height="228" rx="10"/>
+<text class="zl" x="38" y="76">IN PULLBOARD 0.9.0</text>
+<rect class="ver" x="40" y="92" width="502.6666666666667" height="84" rx="8"/>
+<g class="ico" transform="translate(52 105.26) scale(0.75)"><circle cx="9" cy="8.5" r="3"/><circle cx="17" cy="9.5" r="2.4"/><path d="M3.5 19c.8-3 3-4.6 5.5-4.6s4.7 1.6 5.5 4.6M15.5 14.6c2.2 0 4 1.3 4.8 3.9"/></g>
+<text class="h" x="80" y="119">Run a whole team of agents</text>
+<text class="m" x="80" y="138">Builders, verifiers and a coordinator.</text>
+<text class="m" x="80" y="153"><tspan class="hl">101</tspan> work items merged in one day · 7 Oct</text>
+<g transform="rotate(-6 446.66666666666674 134)"><rect class="stamp" x="382.66666666666674" y="107" width="128" height="54" rx="7"/><rect class="stamp in" x="387.66666666666674" y="112" width="118" height="44" rx="4"/><text class="stw" x="448.36666666666673" y="138" text-anchor="middle">LGTM</text><text class="sts" x="447.86666666666673" y="151" text-anchor="middle">SHIP IT</text></g>
+<rect class="you" x="554.6666666666667" y="92" width="245.33333333333334" height="84" rx="8"/><g class="ico" transform="translate(566.6666666666667 105.45) scale(0.75)"><rect x="7" y="2.5" width="10" height="19" rx="2.5"/><path d="M11 18.5h2"/></g><text class="h" x="594.6666666666667" y="119">Your board, on your phone</text><text class="m" x="594.6666666666667" y="138">Answer what’s waiting, anywhere.</text><text class="m" x="594.6666666666667" y="153">Sealed: the relay can’t read it.</text>
+<rect class="rows" x="40" y="188" width="245.33333333333334" height="78" rx="8"/><g class="ico" transform="translate(52 201.45) scale(0.75)"><path d="M7 3h7l4 4v14H7a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Z"/><path d="M14 3v4h4M9 12h6M9 16h4"/></g><text class="h" x="80" y="215">Start from a blueprint</text><text class="m" x="80" y="234">Pick the one for your project,</text><text class="m" x="80" y="249">then approve its rules.</text>
+<rect class="bld" x="297.33333333333337" y="188" width="245.33333333333334" height="78" rx="8"/><g class="ico" transform="translate(309.33333333333337 201.45) scale(0.75)"><path d="M9 3v5M15 3v5M6.5 8h11v3.5a5.5 5.5 0 0 1-11 0Z"/><path d="M12 17v4"/></g><text class="h" x="337.33333333333337" y="215">Plug in any agent</text><text class="m" x="337.33333333333337" y="234">Keep Claude Code or Codex,</text><text class="m" x="337.33333333333337" y="249">and add any MCP client.</text>
+<rect class="lay" x="554.6666666666667" y="188" width="245.33333333333334" height="78" rx="8"/><g class="ico" transform="translate(566.6666666666667 201.82) scale(0.75)"><rect x="2.5" y="4" width="12" height="9" rx="1.5"/><path d="M6.5 16.5h4M8.5 13v3.5"/><rect x="15" y="8" width="6.5" height="11" rx="1.5"/><path d="M17.5 16.5h1.5"/></g><text class="h" x="594.6666666666667" y="215">Across your machines</text><text class="m" x="594.6666666666667" y="234">Pair a machine once. Its agents</text><text class="m" x="594.6666666666667" y="249">share your board, in one order.</text>
+</svg>
diff --git a/docs/img/what.svg b/docs/img/what.svg
index 95755bd7..f5c445b2 100644
--- a/docs/img/what.svg
+++ b/docs/img/what.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
@@ -62,9 +44,7 @@ text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
.pill{fill:#fff;stroke:#dce5df}.pill.ok{fill:#dff4e8;stroke:#9fd6b6}.pt{font-size:11px;fill:#4f5b55}.pt.ok{fill:#0b5d3a;font-weight:600}
.h.sm{font-size:12.5px}.okl{stroke:#1f8a5a}
.ico{fill:none;stroke:#65746b;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
-@media(prefers-color-scheme:dark){.card{fill:#111714;stroke:#34443a}.title,.h,.n{fill:#e9eeeb}.sub,.m,.pt{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
-.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.lay{fill:#18201c;stroke:#3a4a40}
-.ln{stroke:#9cafa3}.hd,.dot{fill:#9cafa3}.ship{fill:#4cc38a}.pill{fill:#111714;stroke:#34443a}.pill.ok{fill:#163829;stroke:#2f7a55}.pt.ok{fill:#8fe0b6}.nb,.hl{fill:#8fe0b6}.stamp{stroke:#4cc38a}.stw,.sts{fill:#4cc38a}.ico{stroke:#9cafa3}.okl{stroke:#4cc38a}}
+
</style>
<defs><marker id="tip-f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path class="hd" d="M0 1 L9 5 L0 9 z"/></marker></defs>
<text class="title" x="24" y="34">One board. Every agent. Every machine.</text>
diff --git a/docs/img/why-dark.svg b/docs/img/why-dark.svg
new file mode 100644
index 00000000..ee14ea04
--- /dev/null
+++ b/docs/img/why-dark.svg
@@ -0,0 +1,88 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 368" width="840" height="368" role="img" aria-labelledby="title desc">
+<title id="title">Where vibe coding breaks, and what holds instead</title><desc id="desc">Where vibe coding breaks, and what holds instead. Pullboard enforces each fix, so none of it depends on you watching. Vibe coding: It said done. It wasn’t.; It forgot what you decided; Two agents, one file; You review every line. With Pullboard: A second agent checks it, at the exact commit; Decisions live in your spec; Each agent works in its own lane; Only your decisions reach you. On Pullboard's own board, 4 to 16 October 2026: 1 in 4 times an agent said done, a second agent sent it back (227 of 908), and 588 merged, 0 of them without an accept.</desc>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif; fill: #1f2328; }
+.mono { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; }
+.card { fill: #ffffff; stroke: #d1d9e0; }
+.head { font-size: 14px; font-weight: 600; }
+.aside { font-size: 12px; fill: #59636e; }
+.t1 { font-size: 14px; font-weight: 600; }
+.t2 { font-size: 12px; fill: #59636e; }
+.label { font-size: 12px; fill: #59636e; }
+.code { font-size: 11.5px; fill: #59636e; }
+.edge { fill: none; stroke: #8c959f; stroke-width: 1.5; }
+.edge.back { stroke: #bc4c00; stroke-dasharray: 5 4; }
+.edge.leader { stroke-width: 1; stroke-dasharray: 2 3; }
+.tip { fill: #8c959f; }
+.tip.back { fill: #bc4c00; }
+.label.back { fill: #bc4c00; }
+.frame { fill: none; stroke: #d1d9e0; stroke-dasharray: 4 4; }
+.plain rect { fill: #f6f8fa; stroke: #d1d9e0; }
+.person rect { fill: #ddf4ff; stroke: #54aeff; }
+.person .t1 { fill: #0a3069; } .person .t2 { fill: #0550ae; }
+.agent rect { fill: #fbefff; stroke: #c297ff; }
+.agent .t1 { fill: #3e1f79; } .agent .t2 { fill: #6639ba; }
+.check rect { fill: #fff8c5; stroke: #d4a72c; }
+.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
+.done rect { fill: #dafbe1; stroke: #4ac26b; }
+.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
+
+ text { fill: #f0f6fc; }
+ .card { fill: #0d1117; stroke: #3d444d; }
+ .aside, .t2, .label, .code { fill: #9198a1; }
+ .edge { stroke: #6e7681; }
+ .edge.back { stroke: #f0883e; }
+ .tip { fill: #6e7681; }
+ .tip.back, .label.back { fill: #f0883e; }
+ .frame { stroke: #3d444d; }
+ .plain rect { fill: #151b23; stroke: #3d444d; }
+ .person rect { fill: #0c2d6b; stroke: #1f6feb; }
+ .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
+ .agent rect { fill: #271052; stroke: #8957e5; }
+ .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
+ .check rect { fill: #272115; stroke: #9e6a03; }
+ .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
+ .done rect { fill: #04260f; stroke: #238636; }
+ .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
+
+</style>
+<defs>
+<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
+<marker id="tip-back" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip back" d="M0 1 L9 5 L0 9 z"/></marker>
+</defs>
+<rect class="card" x="0.5" y="0.5" width="839" height="367" rx="12"/>
+<style>
+text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
+.card{fill:#fff;stroke:#dce5df}.title{font-size:16px;font-weight:650;fill:#101714}.sub{font-size:12px;fill:#4f5b55}
+.zone{fill:none;stroke:#c9d4cd;stroke-dasharray:4 4}.zl{font-size:10.5px;font-weight:650;letter-spacing:.08em;fill:#65746b}
+.h{font-size:13px;font-weight:650;fill:#101714}.m{font-size:11.5px;fill:#4f5b55}.n{font-size:18px;font-weight:650;fill:#101714;font-variant-numeric:tabular-nums}
+.nb{font-size:30px;font-weight:700;fill:#0b5d3a;font-variant-numeric:tabular-nums}.hl{font-weight:700;fill:#0b5d3a}.stamp{fill:none;stroke:#1f8a5a;stroke-width:2}.stamp.in{stroke-width:1;opacity:.55}.stw{font-size:24px;font-weight:800;letter-spacing:.14em;fill:#1f8a5a}.sts{font-size:10px;font-weight:800;letter-spacing:.24em;fill:#1f8a5a}
+.you{fill:#e8f0f8;stroke:#9bb7d4}.plain{fill:#fff;stroke:#c9d4cd}.rows{fill:#efe9ff;stroke:#b9a6f0}.ver{fill:#dff4e8;stroke:#9fd6b6}.bld{fill:#fdf6e3;stroke:#e2c98a}.lay{fill:#f6f8f7;stroke:#c9d4cd}
+.ln{stroke:#65746b;stroke-width:1.5;fill:none}.ln.d{stroke-dasharray:5 4}.hd{fill:#65746b}.dot{fill:#65746b}.ship{fill:#1f8a5a}
+.pill{fill:#fff;stroke:#dce5df}.pill.ok{fill:#dff4e8;stroke:#9fd6b6}.pt{font-size:11px;fill:#4f5b55}.pt.ok{fill:#0b5d3a;font-weight:600}
+.h.sm{font-size:12.5px}.okl{stroke:#1f8a5a}
+.ico{fill:none;stroke:#65746b;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
+.card{fill:#111714;stroke:#34443a}.title,.h,.n{fill:#e9eeeb}.sub,.m,.pt{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
+.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.lay{fill:#18201c;stroke:#3a4a40}
+.ln{stroke:#9cafa3}.hd,.dot{fill:#9cafa3}.ship{fill:#4cc38a}.pill{fill:#111714;stroke:#34443a}.pill.ok{fill:#163829;stroke:#2f7a55}.pt.ok{fill:#8fe0b6}.nb,.hl{fill:#8fe0b6}.stamp{stroke:#4cc38a}.stw,.sts{fill:#4cc38a}.ico{stroke:#9cafa3}.okl{stroke:#4cc38a}
+</style>
+<defs><marker id="tip-f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path class="hd" d="M0 1 L9 5 L0 9 z"/></marker></defs>
+<text class="title" x="24" y="34">Where vibe coding breaks, and what holds instead</text>
+<text class="sub" x="24" y="54">Pullboard enforces each fix, so none of it depends on you watching.</text>
+<rect class="zone" x="24" y="72" width="390" height="198" rx="10"/>
+<text class="zl" x="38" y="94">VIBE CODING</text>
+<rect class="zone" x="426" y="72" width="390" height="198" rx="10"/>
+<text class="zl" x="440" y="94">WITH PULLBOARD</text>
+<rect class="plain" x="40" y="110" width="358" height="30" rx="8"/><path class="ln" d="M52 121l8 8M60 121l-8 8"/><text class="m" x="72" y="130">It said done. It wasn’t.</text>
+<rect class="ver" x="442" y="110" width="358" height="30" rx="8"/><path class="ln okl" d="M454 124l3 3 6-7"/><text class="h sm" x="474" y="130">A second agent checks it, at the exact commit</text>
+<rect class="plain" x="40" y="148" width="358" height="30" rx="8"/><path class="ln" d="M52 159l8 8M60 159l-8 8"/><text class="m" x="72" y="168">It forgot what you decided</text>
+<rect class="ver" x="442" y="148" width="358" height="30" rx="8"/><path class="ln okl" d="M454 162l3 3 6-7"/><text class="h sm" x="474" y="168">Decisions live in your spec</text>
+<rect class="plain" x="40" y="186" width="358" height="30" rx="8"/><path class="ln" d="M52 197l8 8M60 197l-8 8"/><text class="m" x="72" y="206">Two agents, one file</text>
+<rect class="ver" x="442" y="186" width="358" height="30" rx="8"/><path class="ln okl" d="M454 200l3 3 6-7"/><text class="h sm" x="474" y="206">Each agent works in its own lane</text>
+<rect class="plain" x="40" y="224" width="358" height="30" rx="8"/><path class="ln" d="M52 235l8 8M60 235l-8 8"/><text class="m" x="72" y="244">You review every line</text>
+<rect class="ver" x="442" y="224" width="358" height="30" rx="8"/><path class="ln okl" d="M454 238l3 3 6-7"/><text class="h sm" x="474" y="244">Only your decisions reach you</text>
+<rect class="lay" x="24" y="282" width="792" height="62" rx="10"/>
+<text class="nb" x="44" y="323">1 in 4</text>
+<text class="h" x="150" y="309">times an agent said “done”, a second agent sent it back.</text>
+<text class="m" x="150" y="327">908 submitted · 227 sent back · 588 merged · 0 merged without an accept · Pullboard’s own board, 4–16 Oct</text>
+</svg>
diff --git a/docs/img/why.svg b/docs/img/why.svg
index 0af5bd2a..c2a949c5 100644
--- a/docs/img/why.svg
+++ b/docs/img/why.svg
@@ -26,25 +26,7 @@ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans',
.check .t1 { fill: #4d2d00; } .check .t2 { fill: #7d4e00; }
.done rect { fill: #dafbe1; stroke: #4ac26b; }
.done .t1 { fill: #044f1e; } .done .t2 { fill: #116329; }
-@media (prefers-color-scheme: dark) {
- text { fill: #f0f6fc; }
- .card { fill: #0d1117; stroke: #3d444d; }
- .aside, .t2, .label, .code { fill: #9198a1; }
- .edge { stroke: #6e7681; }
- .edge.back { stroke: #f0883e; }
- .tip { fill: #6e7681; }
- .tip.back, .label.back { fill: #f0883e; }
- .frame { stroke: #3d444d; }
- .plain rect { fill: #151b23; stroke: #3d444d; }
- .person rect { fill: #0c2d6b; stroke: #1f6feb; }
- .person .t1 { fill: #cae8ff; } .person .t2 { fill: #a5d6ff; }
- .agent rect { fill: #271052; stroke: #8957e5; }
- .agent .t1 { fill: #ecdeff; } .agent .t2 { fill: #d2a8ff; }
- .check rect { fill: #272115; stroke: #9e6a03; }
- .check .t1 { fill: #f8e3a1; } .check .t2 { fill: #e3b341; }
- .done rect { fill: #04260f; stroke: #238636; }
- .done .t1 { fill: #aff5b4; } .done .t2 { fill: #7ee787; }
-}
+
</style>
<defs>
<marker id="tip" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path class="tip" d="M0 1 L9 5 L0 9 z"/></marker>
@@ -62,9 +44,7 @@ text{font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
.pill{fill:#fff;stroke:#dce5df}.pill.ok{fill:#dff4e8;stroke:#9fd6b6}.pt{font-size:11px;fill:#4f5b55}.pt.ok{fill:#0b5d3a;font-weight:600}
.h.sm{font-size:12.5px}.okl{stroke:#1f8a5a}
.ico{fill:none;stroke:#65746b;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
-@media(prefers-color-scheme:dark){.card{fill:#111714;stroke:#34443a}.title,.h,.n{fill:#e9eeeb}.sub,.m,.pt{fill:#b6c3bc}.zone{stroke:#3a4a40}.zl{fill:#9cafa3}
-.you{fill:#14243a;stroke:#3f6a96}.plain{fill:#111714;stroke:#3a4a40}.rows{fill:#231d3a;stroke:#6b57b8}.ver{fill:#163829;stroke:#2f7a55}.bld{fill:#2e2614;stroke:#8a6f2c}.lay{fill:#18201c;stroke:#3a4a40}
-.ln{stroke:#9cafa3}.hd,.dot{fill:#9cafa3}.ship{fill:#4cc38a}.pill{fill:#111714;stroke:#34443a}.pill.ok{fill:#163829;stroke:#2f7a55}.pt.ok{fill:#8fe0b6}.nb,.hl{fill:#8fe0b6}.stamp{stroke:#4cc38a}.stw,.sts{fill:#4cc38a}.ico{stroke:#9cafa3}.okl{stroke:#4cc38a}}
+
</style>
<defs><marker id="tip-f" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" markerUnits="userSpaceOnUse" orient="auto"><path class="hd" d="M0 1 L9 5 L0 9 z"/></marker></defs>
<text class="title" x="24" y="34">Where vibe coding breaks, and what holds instead</text>
diff --git a/docs/proof/readme-mutants.mjs b/docs/proof/readme-mutants.mjs
index 872c7f6c..252e2700 100644
--- a/docs/proof/readme-mutants.mjs
+++ b/docs/proof/readme-mutants.mjs
@@ -11,13 +11,13 @@ const LINKED = ['test/readme.test.js', 'the README links every figure draw.mjs d
const CARD = ['test/readme.test.js', 'each figure carries its own light and dark colors'];
const DECLARED = ['test/readme.test.js', 'the lifecycle figure is drawn from the declaration'];
const LAYOUT_ALT =
- '![Where things live. The main checkout is the coordinator and holds SPEC.md, DOCTRINE.md, pullboard.json, AGENTS.md and the git hooks. Inside .git, shared by every worktree, are the board and the pinned submitted commits. Beside it, each agent works in its own worktree, builders in their lanes and a verifier, all on the same board. pullboard view lists every project on this machine.](';
+ 'alt="Where things live. The main checkout is the coordinator and holds SPEC.md, DOCTRINE.md, pullboard.json, AGENTS.md and the git hooks. Inside .git, shared by every worktree, are the board and the pinned submitted commits. Beside it, each agent works in its own worktree, builders in their lanes and a verifier, all on the same board. pullboard view lists every project on this machine."';
/** Row, the change, its edits as [file, from, to], the test that judges it, and the outcome expected. */
const MUTANTS = [
['I10', 'a committed figure drifts from what draw.mjs draws', [['docs/img/loop.svg', '>a reject sends it back<', '>a reject sends it home<']], LINKED, 'red'],
- ['I10', 'the README links a figure draw.mjs does not draw', [['README.md', '](docs/img/layout.svg)', '](docs/img/layout.png)']], LINKED, 'red'],
- ['I10', 'a figure says nothing to a reader who cannot see it', [['README.md', LAYOUT_ALT, '![figure](']], LINKED, 'red'],
+ ['I10', 'the README links a figure draw.mjs does not draw', [['README.md', 'src="docs/img/layout.svg"', 'src="docs/img/layout.png"']], LINKED, 'red'],
+ ['I10', 'a figure says nothing to a reader who cannot see it', [['README.md', LAYOUT_ALT, 'alt="figure"']], LINKED, 'red'],
['I10', 'the figures have no dark colors', [['docs/img/draw.mjs', '@media (prefers-color-scheme: dark) {', '@media print {']], CARD, 'red'],
['I10', 'the card does not cover the figure', [['docs/img/draw.mjs', '<rect class="card" x="0.5" y="0.5"', '<rect class="card" x="40" y="0.5"']], CARD, 'red'],
['I10', 'a label runs off the card', [['docs/img/draw.mjs', "text(452, 158, 'a reject sends it back', 'label back')", "text(752, 158, 'a reject sends it back', 'label back')"]], CARD, 'red'],
diff --git a/docs/shots/demo.mjs b/docs/shots/demo.mjs
index c5ca1894..9aeff686 100644
--- a/docs/shots/demo.mjs
+++ b/docs/shots/demo.mjs
@@ -12,11 +12,14 @@ import { fileURLToPath } from 'node:url';
import { browser, waitForDemoBoard } from './capture-browser.mjs';
import { FIXED_TIME, isolatedEnv } from './demo-env.mjs';
import { renderTour } from './tour-renderer.mjs';
+import { themeVariants } from '../img/theme.mjs';
import { AGENT_SHELL_MARKERS } from '../../src/person.js';
const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
const BIN = join(ROOT, 'bin', 'pullboard.js');
const OUTPUT = fileURLToPath(new URL('./', import.meta.url));
+/** Every board image is captured in both themes, so GitHub can show the one that matches the reader. */
+const THEMES = ['light', 'dark'];
const DEMO_OUTPUT = join(ROOT, 'docs', 'demo');
const DEMO_BOARD_ID = 'demo-board';
const CHROME = [process.env.PULLBOARD_CHROME, '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser'].filter(Boolean);
@@ -241,7 +244,20 @@ async function recordTour(env) {
const status = await new Promise((resolveStatus) => child.once('close', resolveStatus));
if (buffer.trim()) lines.push({ text: buffer.trim(), at: Date.now() - started });
if (status !== 0 || !lines.length) throw new Error('The pullboard tour recording did not finish');
- await writeFile(join(OUTPUT, 'tour.svg'), renderTour(lines));
+ const { light, dark } = themeVariants(renderTour(lines));
+ await writeFile(join(OUTPUT, 'tour.svg'), light);
+ await writeFile(join(OUTPUT, 'tour-dark.svg'), dark);
+}
+
+/**
+ * Show the board in one theme the way the reader's own choice does, then wait for the paint.
+ *
+ * @param {{ evaluate: (expression: string) => Promise<unknown> }} view the open demo page
+ * @param {'light' | 'dark'} theme the theme to paint
+ */
+async function paintTheme(view, theme) {
+ await view.evaluate(`document.documentElement.dataset.theme = ${JSON.stringify(theme)}; localStorage.setItem('pb.theme', ${JSON.stringify(theme)})`);
+ await view.evaluate('document.fonts.ready.then(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))))');
}
/** Capture the real demo release and one expanded item, with data and geometry checks before each image. */
@@ -384,15 +400,23 @@ else {
await view.evaluate("document.querySelector('#filter-toggle').click(); document.querySelector('#filter-menu [data-filter-choice=\"state:active\"]').click()");
await view.waitFor("!document.querySelector('#needs').hidden && document.querySelector('#needs').textContent.includes('NEEDS YOU') && document.querySelector('#detail').textContent.includes('ACCEPT')", 'Active items, Needs you and the selected review history');
await view.evaluate('document.fonts.ready.then(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))))');
- await view.screenshot(join(OUTPUT, 'desktop.png'));
+ for (const theme of THEMES) {
+ await paintTheme(view, theme);
+ await view.screenshot(join(OUTPUT, `desktop-${theme}.png`));
+ }
await view.viewport(390, 900);
- await view.evaluate("(()=>{document.documentElement.dataset.theme='dark'; localStorage.setItem('pb.theme','dark'); const item=document.querySelector('[data-item=\"4\"]'); const detail=document.querySelector('#detail')?.textContent??''; if(document.documentElement.dataset.theme!=='dark'||!item||!detail.includes('ACCEPT')||document.querySelector('#needs').hidden) throw new Error('The phone screenshot must show active work and Needs you in dark mode'); return true})()");
- await view.screenshot(join(OUTPUT, 'phone.png'));
+ for (const theme of THEMES) {
+ await paintTheme(view, theme);
+ await view.evaluate("(()=>{const item=document.querySelector('[data-item=\"4\"]'); const detail=document.querySelector('#detail')?.textContent??''; if(!item||!detail.includes('ACCEPT')||document.querySelector('#needs').hidden) throw new Error('The phone screenshot must show active work and Needs you'); return true})()");
+ await view.screenshot(join(OUTPUT, `phone-${theme}.png`));
+ }
await view.viewport(1440, 900);
await view.evaluate("document.documentElement.dataset.theme='light'; localStorage.setItem('pb.theme','light'); document.querySelector('[data-tab=\"shouts\"]').click()");
await view.waitFor("!document.querySelector('#shouts-pane').hidden && !!document.querySelector('#feed .heard:not(.not)') && !!document.querySelector('#feed .receipt') && !!document.querySelector('#feed [data-code]') && !!document.querySelector('#feed .band.done')", 'answered conversation, Heard, receipt and code reference');
- await view.evaluate('document.fonts.ready.then(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))))');
- await view.screenshot(join(OUTPUT, 'shouts.png'));
+ for (const theme of THEMES) {
+ await paintTheme(view, theme);
+ await view.screenshot(join(OUTPUT, `shouts-${theme}.png`));
+ }
}
await captureRoadmap(view, repo, observation);
await view.close(); view = null;
diff --git a/docs/shots/desktop-dark.png b/docs/shots/desktop-dark.png
new file mode 100644
index 00000000..8bc91d4c
Binary files /dev/null and b/docs/shots/desktop-dark.png differ
diff --git a/docs/shots/desktop-light.png b/docs/shots/desktop-light.png
new file mode 100644
index 00000000..dc23ea71
Binary files /dev/null and b/docs/shots/desktop-light.png differ
diff --git a/docs/shots/desktop.png b/docs/shots/desktop.png
deleted file mode 100644
index 3276007a..00000000
Binary files a/docs/shots/desktop.png and /dev/null differ
diff --git a/docs/shots/phone-dark.png b/docs/shots/phone-dark.png
new file mode 100644
index 00000000..945c0338
Binary files /dev/null and b/docs/shots/phone-dark.png differ
diff --git a/docs/shots/phone-light.png b/docs/shots/phone-light.png
new file mode 100644
index 00000000..e40cdcfc
Binary files /dev/null and b/docs/shots/phone-light.png differ
diff --git a/docs/shots/phone.png b/docs/shots/phone.png
deleted file mode 100644
index c91f6448..00000000
Binary files a/docs/shots/phone.png and /dev/null differ
diff --git a/docs/shots/shots.test.js b/docs/shots/shots.test.js
index 1f688072..947356ac 100644
--- a/docs/shots/shots.test.js
+++ b/docs/shots/shots.test.js
@@ -11,26 +11,36 @@ import { test } from 'node:test';
import { fileURLToPath } from 'node:url';
import { evaluationValue } from './devtools-evaluation.mjs';
import { renderTour } from './tour-renderer.mjs';
+import { themeVariants } from '../img/theme.mjs';
import { narrationDurations, parseVtt } from './video.mjs';
const ROOT = new URL('../../', import.meta.url);
const README = readFileSync(new URL('README.md', ROOT), 'utf8');
-const files = ['desktop.png', 'phone.png', 'shouts.png', 'tour.svg'];
+const files = ['desktop-light.png', 'desktop-dark.png', 'phone-light.png', 'phone-dark.png', 'shouts-light.png', 'shouts-dark.png', 'tour.svg', 'tour-dark.svg'];
const shots = (name) => new URL(`docs/shots/${name}`, ROOT);
-/** Assert that an image is embedded in a named README section with useful alt text. */
+/**
+ * Assert that a README picture embeds a named capture in a section, with descriptive alt text and a dark twin.
+ *
+ * @param {string} section the README section heading that holds the picture
+ * @param {string} file the light capture's file name under docs/shots
+ * @param {string[]} phrases words the alt text must include
+ */
function linkedInSection(section, file, phrases) {
const start = README.indexOf(`## ${section}`);
assert.notEqual(start, -1, `README has the ${section} section`);
const next = README.indexOf('\n## ', start + 1);
const body = README.slice(start, next < 0 ? undefined : next);
- const match = new RegExp(`!\\[([^\\]]+)\\]\\(docs/shots/${file.replace('.', '\\.')}\\)`).exec(body);
+ const light = `docs/shots/${file.replaceAll('.', '\\.')}`;
+ const match = new RegExp(`<img src="${light}" alt="([^"]+)">`).exec(body);
assert.ok(match, `${file} is embedded in ${section}`);
+ const dark = file === 'tour.svg' ? 'tour-dark.svg' : file.replace('-light.', '-dark.');
+ assert.ok(body.includes(`srcset="docs/shots/${dark}"`), `${file} has a dark twin in ${section}`);
for (const phrase of phrases) assert.ok(match[1].toLowerCase().includes(phrase), `${file} alt text says ${phrase}`);
}
test('the README links the desktop board and timed tour with descriptive alt text [I11,I13]', () => {
- linkedInSection('Pullboard View', 'desktop.png', ['open', 'claimed', 'submitted', 'accepted']);
+ linkedInSection('Pullboard View', 'desktop-light.png', ['open', 'claimed', 'submitted', 'accepted']);
linkedInSection('Installation', 'tour.svg', ['submitted', 'rejected', 'fixed', 'accepted']);
});
@@ -47,8 +57,8 @@ test('the README board shots show the stats line [I11,I13]', () => {
assert.match(exported, /proof-stats-summary-text/, 'the exported demo renders a compact summary');
assert.match(exported, /stats\.merged \+ ' merged · ' \+ percentage \+ ' sent back'/, 'the summary is derived from exported stats');
assert.match(exported, /Bottleneck: ' \+ \(stage \|\| bottleneck\.message\)/, 'the summary includes the measured bottleneck');
- linkedInSection('Pullboard View', 'desktop.png', ['stats line', 'merged work', 'sent-back share', 'bottleneck recommendation']);
- linkedInSection('Pullboard View', 'phone.png', ['stats line', 'merged work', 'sent-back share', 'bottleneck recommendation']);
+ linkedInSection('Pullboard View', 'desktop-light.png', ['stats line', 'merged work', 'sent-back share', 'bottleneck recommendation']);
+ linkedInSection('Pullboard View', 'phone-light.png', ['stats line', 'merged work', 'sent-back share', 'bottleneck recommendation']);
});
test('the demo board stages a Shouts conversation [I11,I13]', () => {
@@ -77,7 +87,7 @@ test('the demo board declares every agent\'s model [I11,I13]', () => {
const source = fileURLToPath(ROOT);
const root = join(fixture, 'repo');
mkdirSync(root);
- for (const directory of ['src', 'bin', 'docs/shots', 'skills']) cpSync(join(source, directory), join(root, directory), { recursive: true });
+ for (const directory of ['src', 'bin', 'docs/shots', 'docs/img', 'skills']) cpSync(join(source, directory), join(root, directory), { recursive: true });
for (const file of ['test/chrome-fixture.js', 'test/fixture-child.js', 'package.json', 'CHANGELOG.md']) cpSync(join(source, file), join(root, file));
const shims = join(fixture, 'bin');
mkdirSync(shims);
@@ -129,7 +139,7 @@ test("the README capture's Chrome socket path fits the Linux limit [I11,C7]", ()
test('the README capture leaves no view running [I11,I13]', { timeout: 240_000 }, () => {
const source = fileURLToPath(ROOT);
- const images = ['desktop.png', 'phone.png', 'shouts.png'];
+ const images = ['desktop-light.png', 'desktop-dark.png', 'phone-light.png', 'phone-dark.png', 'shouts-light.png', 'shouts-dark.png'];
const chrome = process.env.PULLBOARD_CHROME || [
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
'/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
@@ -143,7 +153,7 @@ test('the README capture leaves no view running [I11,I13]', { timeout: 240_000 }
try {
const root = join(fixture, 'repo');
mkdirSync(root);
- for (const directory of ['bin', 'src', 'skills', 'docs/shots']) {
+ for (const directory of ['bin', 'src', 'skills', 'docs/shots', 'docs/img']) {
cpSync(join(source, directory), join(root, directory), { recursive: true });
}
mkdirSync(join(root, 'test'));
@@ -214,22 +224,20 @@ test('the README capture leaves no view running [I11,I13]', { timeout: 240_000 }
});
test('the README shows the Shouts capture [I11,I13]', () => {
- linkedInSection('Pullboard View', 'shouts.png', ['shouts', 'answered', 'heard', 'receipt', 'code reference']);
- linkedInSection('Pullboard View', 'desktop.png', ['needs you', 'search', 'status bar']);
- linkedInSection('Pullboard View', 'phone.png', ['phone', 'dark', 'active work', 'needs you', 'search']);
+ linkedInSection('Pullboard View', 'shouts-light.png', ['shouts', 'answered', 'heard', 'receipt', 'code reference']);
+ linkedInSection('Pullboard View', 'desktop-light.png', ['needs you', 'search', 'status bar']);
+ linkedInSection('Pullboard View', 'phone-light.png', ['phone', 'active work', 'needs you', 'search']);
const section = README.slice(README.indexOf('## Pullboard View'), README.indexOf('## Get started'));
- assert.match(section, /desktop\.png\)[^]*shouts\.png\)/, 'desktop and Shouts captures are together');
- const png = readFileSync(shots('shouts.png'));
+ assert.match(section, /desktop-light\.png"[^]*shouts-light\.png"/, 'desktop and Shouts captures are together');
+ const png = readFileSync(shots('shouts-light.png'));
assert.deepEqual([...png.subarray(0, 8)], [137, 80, 78, 71, 13, 10, 26, 10]);
assert.equal(png.readUInt32BE(16), 1440, 'the Shouts capture is desktop width');
});
test('the demo assets exist and stay within their size budgets [I11,I13]', () => {
for (const name of files) assert.ok(statSync(shots(name)).size > 0, `${name} exists`);
- assert.ok(statSync(shots('desktop.png')).size < 300_000, 'desktop PNG is under 300 KB');
- assert.ok(statSync(shots('phone.png')).size < 300_000, 'phone PNG is under 300 KB');
- assert.ok(statSync(shots('shouts.png')).size < 300_000, 'Shouts PNG is under 300 KB');
- assert.ok(statSync(shots('tour.svg')).size < 200_000, 'tour SVG is under 200 KB');
+ for (const name of files.filter((file) => file.endsWith('.png'))) assert.ok(statSync(shots(name)).size < 300_000, `${name} is under 300 KB`);
+ for (const name of ['tour.svg', 'tour-dark.svg']) assert.ok(statSync(shots(name)).size < 200_000, `${name} is under 200 KB`);
const tour = readFileSync(shots('tour.svg'), 'utf8');
assert.match(tour, /animation:light-step 16s linear infinite/, 'the SVG carries its own timed animation');
assert.doesNotMatch(tour, /[\x00-\x08\x0b-\x1f]/, 'tour SVG contains no XML-invalid control characters');
@@ -310,9 +318,10 @@ function capturedTour() {
return JSON.parse(metadata[1].replaceAll('&apos;', "'").replaceAll('&quot;', '"').replaceAll('&gt;', '>').replaceAll('&lt;', '<').replaceAll('&amp;', '&'));
}
-/** Check the committed image as well as a fresh rendering of its real tour output. */
+/** Check both committed themes as well as a fresh rendering of the real tour output, split the way the demo writes it. */
function cards() {
- return [readFileSync(shots('tour.svg'), 'utf8'), renderTour(capturedTour())];
+ const rendered = themeVariants(renderTour(capturedTour()));
+ return [readFileSync(shots('tour.svg'), 'utf8'), readFileSync(shots('tour-dark.svg'), 'utf8'), rendered.light, rendered.dark];
}
test('the compact tour card holds eight ordered, single-line steps and both verdict tags [I13]', () => {
@@ -342,9 +351,13 @@ test('the card lights steps in turn and holds still for reduced motion [I13]', (
});
test('the card carries distinct actor and verdict colours for light and dark readers [I13]', () => {
- for (const svg of cards()) {
- assert.match(svg, /@media\(prefers-color-scheme:dark\)/);
- for (const color of ['#101714', '#315f8f', '#6547bc', '#087546', '#e9eeeb', '#80bfff', '#c1aeff', '#61e6b1']) assert.ok(svg.includes(color), color);
+ const [light, dark, renderedLight, renderedDark] = cards();
+ assert.equal(light, renderedLight, 'tour.svg is the light card of the recorded tour');
+ assert.equal(dark, renderedDark, 'tour-dark.svg is the dark card of the recorded tour');
+ for (const color of ['#101714', '#315f8f', '#6547bc', '#087546']) assert.ok(light.includes(color), color);
+ for (const color of ['#e9eeeb', '#80bfff', '#c1aeff', '#61e6b1']) assert.ok(dark.includes(color) && !light.includes(color), color);
+ for (const svg of [light, dark]) {
+ assert.doesNotMatch(svg, /prefers-color-scheme/, 'each card holds one theme, and its picture picks the reader\'s');
for (const [actor, color] of [['you', 'ink'], ['coordinator', 'blue'], ['builder', 'violet'], ['verifier', 'green']]) {
assert.ok(svg.includes(`.${actor}{fill:var(--${color})}`), `${actor} has its own colour`);
}
diff --git a/docs/shots/shouts-dark.png b/docs/shots/shouts-dark.png
new file mode 100644
index 00000000..e28cd2ab
Binary files /dev/null and b/docs/shots/shouts-dark.png differ
diff --git a/docs/shots/shouts-light.png b/docs/shots/shouts-light.png
new file mode 100644
index 00000000..0202d641
Binary files /dev/null and b/docs/shots/shouts-light.png differ
diff --git a/docs/shots/shouts.png b/docs/shots/shouts.png
deleted file mode 100644
index a2ab2d83..00000000
Binary files a/docs/shots/shouts.png and /dev/null differ
diff --git a/docs/shots/tour-dark.svg b/docs/shots/tour-dark.svg
new file mode 100644
index 00000000..1ed60b5c
--- /dev/null
+++ b/docs/shots/tour-dark.svg
@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" class="tour-card" viewBox="0 0 640 420" width="640" height="420" role="img" aria-labelledby="tour-title tour-description">
+<title id="tour-title">The tour, in thirty seconds</title><desc id="tour-description">Eight steps: a real change is submitted, rejected, fixed, tested and accepted before it merges.</desc>
+<metadata id="tour-transcript">[{&quot;text&quot;:&quot;pullboard tour: a coordinator and two scripted agents run real commands on a throwaway repo. No model runs.&quot;,&quot;at&quot;:172},{&quot;text&quot;:&quot;1 The person approved one spec row. The coordinator files it as work.&quot;,&quot;at&quot;:4186},{&quot;text&quot;:&quot; G1: greet(name) returns \&quot;Hello, &lt;name&gt;!\&quot;; a blank name greets the world: \&quot;Hello, world!\&quot;&quot;,&quot;at&quot;:4186},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard add app Greeting --specs G1 --criterion \&quot;greet() meets G1\&quot;&quot;,&quot;at&quot;:4589},{&quot;text&quot;:&quot; #1&quot;,&quot;at&quot;:4868},{&quot;text&quot;:&quot;2 A builder agent gets its own worktree in the app lane and claims the next item. Its criterion freezes.&quot;,&quot;at&quot;:6068},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard worktree app --model Scripted&quot;,&quot;at&quot;:6473},{&quot;text&quot;:&quot; made greeter-app-1 on branch app/1, joined as app-1 (Scripted) in the app lane&quot;,&quot;at&quot;:6852},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard next&quot;,&quot;at&quot;:7257},{&quot;text&quot;:&quot; claimed #1: Greeting&quot;,&quot;at&quot;:7582},{&quot;text&quot;:&quot; criterion: greet() meets G1&quot;,&quot;at&quot;:7582},{&quot;text&quot;:&quot;3 It writes greet(), tests the happy path and submits. Its own gate is green.&quot;,&quot;at&quot;:8787},{&quot;text&quot;:&quot; app-1 (Scripted) $ git commit -q -m \&quot;feat(app): greet by name [G1]\&quot;&quot;,&quot;at&quot;:9614},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard submit 1&quot;,&quot;at&quot;:10681},{&quot;text&quot;:&quot; submitted #1 at 5c1657240f9d; no item check; full gate: affected-test selection is not enabled for this project; gate green in 0s; timing (node): wall 0.00s, slot wait 0.00s; per-test timing unavailable: output was not TAP or JUnit (one or more phases); timing profile: greeter/.git/worktrees/greeter-app-1/pullboard-submit.log.profile.json&quot;,&quot;at&quot;:11940},{&quot;text&quot;:&quot;4 A second agent checks out exactly that commit and tries the edge the builder skipped.&quot;,&quot;at&quot;:13143},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard worktree review --model Scripted&quot;,&quot;at&quot;:13548},{&quot;text&quot;:&quot; made greeter-review-1 on branch review/1, joined as review-1 (Scripted) in the review lane&quot;,&quot;at&quot;:13970},{&quot;text&quot;:&quot; review-1 (Scripted) $ git switch -q --detach 5c1657240f9d&quot;,&quot;at&quot;:14373},{&quot;text&quot;:&quot; review-1 (Scripted) $ node -e \&quot;greet(&apos;&apos;)\&quot;&quot;,&quot;at&quot;:14790},{&quot;text&quot;:&quot; Hello, !&quot;,&quot;at&quot;:14830},{&quot;text&quot;:&quot; review-1 (Scripted) $ pullboard verify 1 reject --reason BEHAVIOR_MISMATCH --note \&quot;greet(&apos;&apos;) returns \\\&quot;Hello, !\\\&quot;; G1 says a blank name greets the world\&quot;&quot;,&quot;at&quot;:15231},{&quot;text&quot;:&quot; rejected #1: BEHAVIOR_MISMATCH; it is open again for rework&quot;,&quot;at&quot;:15468},{&quot;text&quot;:&quot;5 The builder&apos;s next session starts from the board, not from memory.&quot;,&quot;at&quot;:16671},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard resume&quot;,&quot;at&quot;:17073},{&quot;text&quot;:&quot; sent back: #1 BEHAVIOR_MISMATCH by review-1 (Scripted): greet(&apos;&apos;) returns \&quot;Hello, !\&quot;; G1 says a blank name greets the world&quot;,&quot;at&quot;:17311},{&quot;text&quot;:&quot; next: pullboard claim 1, fix what the verifier found, and submit again&quot;,&quot;at&quot;:17311},{&quot;text&quot;:&quot;6 It fixes the edge, adds a test that pins it, and submits a new commit.&quot;,&quot;at&quot;:18515},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard claim 1&quot;,&quot;at&quot;:18920},{&quot;text&quot;:&quot; claimed #1 until 2026-10-06T15:15:00.000Z; criterion frozen as b0aac73305a5&quot;,&quot;at&quot;:19106},{&quot;text&quot;:&quot; app-1 (Scripted) $ git commit -q -am \&quot;fix(app): a blank name greets the world [G1]\&quot;&quot;,&quot;at&quot;:19508},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard submit 1&quot;,&quot;at&quot;:20280},{&quot;text&quot;:&quot; submitted #1 at e9f29935400c; no item check; full gate: affected-test selection is not enabled for this project; gate green in 0s; timing (node): wall 0.00s, slot wait 0.00s; per-test timing unavailable: output was not TAP or JUnit (one or more phases); timing profile: greeter/.git/worktrees/greeter-app-1/pullboard-submit.log.profile.json&quot;,&quot;at&quot;:21286},{&quot;text&quot;:&quot;7 The verifier breaks the fix on purpose, to prove the new test can fail, then restores it and accepts.&quot;,&quot;at&quot;:22489},{&quot;text&quot;:&quot; review-1 (Scripted) $ git switch -q --detach e9f29935400c&quot;,&quot;at&quot;:22892},{&quot;text&quot;:&quot; review-1 (Scripted) $ node --test # with the fix removed&quot;,&quot;at&quot;:23322},{&quot;text&quot;:&quot; # pass 1&quot;,&quot;at&quot;:23411},{&quot;text&quot;:&quot; # fail 1&quot;,&quot;at&quot;:23411},{&quot;text&quot;:&quot; review-1 (Scripted) $ git checkout -- src/greet.mjs&quot;,&quot;at&quot;:23814},{&quot;text&quot;:&quot; review-1 (Scripted) $ pullboard verify 1 accept --note \&quot;removed the blank-name fix: its new test failed; restored, both pass\&quot;&quot;,&quot;at&quot;:24235},{&quot;text&quot;:&quot; verified #1: CRITERION_MET; no frozen check ran&quot;,&quot;at&quot;:24788},{&quot;text&quot;:&quot;8 The coordinator merges it. The ledger is the receipt.&quot;,&quot;at&quot;:25993},{&quot;text&quot;:&quot; coordinator (unknown) $ git merge -q --ff-only app/1&quot;,&quot;at&quot;:26392},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard merged 1 e9f29935400c&quot;,&quot;at&quot;:26822},{&quot;text&quot;:&quot; #1 merged as e9f29935400c&quot;,&quot;at&quot;:27199},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard ledger&quot;,&quot;at&quot;:27604},{&quot;text&quot;:&quot; 1 verified by a second agent · 0 awaiting verification · 1 rejection along the way&quot;,&quot;at&quot;:27826},{&quot;text&quot;:&quot; | # | Lane | Item | Spec | Built by | Verified by | Check | Commit | Merged |&quot;,&quot;at&quot;:27826},{&quot;text&quot;:&quot; | 1 | app | Greeting | G1 | app-1 (Scripted) | review-1 (Scripted) | unchecked | e9f29935400c | e9f29935400c |&quot;,&quot;at&quot;:27826},{&quot;text&quot;:&quot;Nothing shipped until a second agent verified it.&quot;,&quot;at&quot;:27837},{&quot;text&quot;:&quot; Look around: cd greeter &amp;&amp; pullboard log&quot;,&quot;at&quot;:27837},{&quot;text&quot;:&quot;see it: pullboard view&quot;,&quot;at&quot;:27837}]</metadata>
+<style>
+.tour-card{--surface:#ffffff;--line:#dce5df;--ink:#101714;--muted:#4f5b55;--faint:#65746b;--blue:#315f8f;--violet:#6547bc;--green:#087546;--green-soft:#dff4e8;--red:#b33026;--red-soft:#fce8e5;--highlight:#edf7f1;font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
+.tour-card{--surface:#111714;--line:#34443a;--ink:#e9eeeb;--muted:#b6c3bc;--faint:#9cafa3;--blue:#80bfff;--violet:#c1aeff;--green:#61e6b1;--green-soft:#163829;--red:#ff8a80;--red-soft:#321917;--highlight:#193426}
+.surface{fill:var(--surface);stroke:var(--line)}.divider{stroke:var(--line)}.heading{fill:var(--ink);font-size:16px;font-weight:650}.command,.number,.actor,.verdict text{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.command,.number{fill:var(--faint);font-size:12px}.actor{font-size:12px;font-weight:600}.you{fill:var(--ink)}.coordinator{fill:var(--blue)}.builder{fill:var(--violet)}.verifier{fill:var(--green)}.description{fill:var(--muted);font-size:13px}.footer{fill:var(--muted);font-size:12px}.verdict text{font-size:11px;font-weight:650}.reject rect{fill:var(--red-soft)}.reject text{fill:var(--red)}.accept rect{fill:var(--green-soft)}.accept text{fill:var(--green)}
+.step-glow{fill:transparent;animation:light-step 16s linear infinite}@keyframes light-step{0%,11%{fill:var(--highlight)}13%,100%{fill:transparent}}
+@media(prefers-reduced-motion:reduce){.step-glow{animation:none;fill:transparent}}
+</style>
+<rect class="surface" x="0.5" y="0.5" width="639" height="419" rx="16"/>
+<text class="heading" x="26" y="37">The tour, in thirty seconds</text><text class="command" x="615" y="37" text-anchor="end">$ pullboard tour</text><path class="divider" d="M26 57H614"/>
+<g class="tour-step" data-step="1" data-actor="you"><title> G1: greet(name) returns &quot;Hello, &lt;name&gt;!&quot;; a blank name greets the world: &quot;Hello, world!&quot;</title><rect class="step-glow" x="18" y="67" width="604" height="35" rx="9" style="animation-delay:0s"/><text class="number" x="30" y="89">1</text><text class="actor you" x="60" y="89">you</text><text class="description" x="155" y="89">approve one spec row: greet a blank name as &quot;world&quot;</text></g>
+<g class="tour-step" data-step="2" data-actor="coordinator"><title>The person approved one spec row. The coordinator files it as work.</title><rect class="step-glow" x="18" y="104" width="604" height="35" rx="9" style="animation-delay:2s"/><text class="number" x="30" y="126">2</text><text class="actor coordinator" x="60" y="126">coordinator</text><text class="description" x="155" y="126">files it as task #1</text></g>
+<g class="tour-step" data-step="3" data-actor="builder"><title>A builder agent gets its own worktree in the app lane and claims the next item. Its criterion freezes. It writes greet(), tests the happy path and submits. Its own gate is green.</title><rect class="step-glow" x="18" y="141" width="604" height="35" rx="9" style="animation-delay:4s"/><text class="number" x="30" y="163">3</text><text class="actor builder" x="60" y="163">builder</text><text class="description" x="155" y="163">claims it, builds greet(), submits with tests green</text></g>
+<g class="tour-step" data-step="4" data-actor="verifier"><title>A second agent checks out exactly that commit and tries the edge the builder skipped.: BEHAVIOR_MISMATCH</title><rect class="step-glow" x="18" y="178" width="604" height="35" rx="9" style="animation-delay:6s"/><text class="number" x="30" y="200">4</text><text class="actor verifier" x="60" y="200">verifier</text><text class="description" x="155" y="200">tries a blank name, gets &quot;Hello, !&quot;</text><g class="verdict reject"><rect x="553" y="185" width="62" height="22" rx="6"/><text x="584" y="200" text-anchor="middle">REJECT</text><title>BEHAVIOR_MISMATCH</title></g></g>
+<g class="tour-step" data-step="5" data-actor="builder"><title>The builder&apos;s next session starts from the board, not from memory.</title><rect class="step-glow" x="18" y="215" width="604" height="35" rx="9" style="animation-delay:8s"/><text class="number" x="30" y="237">5</text><text class="actor builder" x="60" y="237">builder</text><text class="description" x="155" y="237">reads why from the board, not from memory.</text></g>
+<g class="tour-step" data-step="6" data-actor="builder"><title>It fixes the edge, adds a test that pins it, and submits a new commit.</title><rect class="step-glow" x="18" y="252" width="604" height="35" rx="9" style="animation-delay:10s"/><text class="number" x="30" y="274">6</text><text class="actor builder" x="60" y="274">builder</text><text class="description" x="155" y="274">fixes it, adds a test that pins it, submits again</text></g>
+<g class="tour-step" data-step="7" data-actor="verifier"><title>The verifier breaks the fix on purpose, to prove the new test can fail, then restores it and accepts.: CRITERION_MET</title><rect class="step-glow" x="18" y="289" width="604" height="35" rx="9" style="animation-delay:12s"/><text class="number" x="30" y="311">7</text><text class="actor verifier" x="60" y="311">verifier</text><text class="description" x="155" y="311">breaks the fix on purpose, sees the test fail</text><g class="verdict accept"><rect x="553" y="296" width="62" height="22" rx="6"/><text x="584" y="311" text-anchor="middle">ACCEPT</text><title>CRITERION_MET</title></g></g>
+<g class="tour-step" data-step="8" data-actor="coordinator"><title>The coordinator merges it. The ledger is the receipt.</title><rect class="step-glow" x="18" y="326" width="604" height="35" rx="9" style="animation-delay:14s"/><text class="number" x="30" y="348">8</text><text class="actor coordinator" x="60" y="348">coordinator</text><text class="description" x="155" y="348">merges it; the ledger is the receipt.</text></g>
+<text class="footer" x="26" y="393">Real commands on a throwaway repo. No model runs.</text>
+</svg>
diff --git a/docs/shots/tour.svg b/docs/shots/tour.svg
index 357d3726..e4b383a8 100644
--- a/docs/shots/tour.svg
+++ b/docs/shots/tour.svg
@@ -3,7 +3,7 @@
<metadata id="tour-transcript">[{&quot;text&quot;:&quot;pullboard tour: a coordinator and two scripted agents run real commands on a throwaway repo. No model runs.&quot;,&quot;at&quot;:172},{&quot;text&quot;:&quot;1 The person approved one spec row. The coordinator files it as work.&quot;,&quot;at&quot;:4186},{&quot;text&quot;:&quot; G1: greet(name) returns \&quot;Hello, &lt;name&gt;!\&quot;; a blank name greets the world: \&quot;Hello, world!\&quot;&quot;,&quot;at&quot;:4186},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard add app Greeting --specs G1 --criterion \&quot;greet() meets G1\&quot;&quot;,&quot;at&quot;:4589},{&quot;text&quot;:&quot; #1&quot;,&quot;at&quot;:4868},{&quot;text&quot;:&quot;2 A builder agent gets its own worktree in the app lane and claims the next item. Its criterion freezes.&quot;,&quot;at&quot;:6068},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard worktree app --model Scripted&quot;,&quot;at&quot;:6473},{&quot;text&quot;:&quot; made greeter-app-1 on branch app/1, joined as app-1 (Scripted) in the app lane&quot;,&quot;at&quot;:6852},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard next&quot;,&quot;at&quot;:7257},{&quot;text&quot;:&quot; claimed #1: Greeting&quot;,&quot;at&quot;:7582},{&quot;text&quot;:&quot; criterion: greet() meets G1&quot;,&quot;at&quot;:7582},{&quot;text&quot;:&quot;3 It writes greet(), tests the happy path and submits. Its own gate is green.&quot;,&quot;at&quot;:8787},{&quot;text&quot;:&quot; app-1 (Scripted) $ git commit -q -m \&quot;feat(app): greet by name [G1]\&quot;&quot;,&quot;at&quot;:9614},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard submit 1&quot;,&quot;at&quot;:10681},{&quot;text&quot;:&quot; submitted #1 at 5c1657240f9d; no item check; full gate: affected-test selection is not enabled for this project; gate green in 0s; timing (node): wall 0.00s, slot wait 0.00s; per-test timing unavailable: output was not TAP or JUnit (one or more phases); timing profile: greeter/.git/worktrees/greeter-app-1/pullboard-submit.log.profile.json&quot;,&quot;at&quot;:11940},{&quot;text&quot;:&quot;4 A second agent checks out exactly that commit and tries the edge the builder skipped.&quot;,&quot;at&quot;:13143},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard worktree review --model Scripted&quot;,&quot;at&quot;:13548},{&quot;text&quot;:&quot; made greeter-review-1 on branch review/1, joined as review-1 (Scripted) in the review lane&quot;,&quot;at&quot;:13970},{&quot;text&quot;:&quot; review-1 (Scripted) $ git switch -q --detach 5c1657240f9d&quot;,&quot;at&quot;:14373},{&quot;text&quot;:&quot; review-1 (Scripted) $ node -e \&quot;greet(&apos;&apos;)\&quot;&quot;,&quot;at&quot;:14790},{&quot;text&quot;:&quot; Hello, !&quot;,&quot;at&quot;:14830},{&quot;text&quot;:&quot; review-1 (Scripted) $ pullboard verify 1 reject --reason BEHAVIOR_MISMATCH --note \&quot;greet(&apos;&apos;) returns \\\&quot;Hello, !\\\&quot;; G1 says a blank name greets the world\&quot;&quot;,&quot;at&quot;:15231},{&quot;text&quot;:&quot; rejected #1: BEHAVIOR_MISMATCH; it is open again for rework&quot;,&quot;at&quot;:15468},{&quot;text&quot;:&quot;5 The builder&apos;s next session starts from the board, not from memory.&quot;,&quot;at&quot;:16671},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard resume&quot;,&quot;at&quot;:17073},{&quot;text&quot;:&quot; sent back: #1 BEHAVIOR_MISMATCH by review-1 (Scripted): greet(&apos;&apos;) returns \&quot;Hello, !\&quot;; G1 says a blank name greets the world&quot;,&quot;at&quot;:17311},{&quot;text&quot;:&quot; next: pullboard claim 1, fix what the verifier found, and submit again&quot;,&quot;at&quot;:17311},{&quot;text&quot;:&quot;6 It fixes the edge, adds a test that pins it, and submits a new commit.&quot;,&quot;at&quot;:18515},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard claim 1&quot;,&quot;at&quot;:18920},{&quot;text&quot;:&quot; claimed #1 until 2026-10-06T15:15:00.000Z; criterion frozen as b0aac73305a5&quot;,&quot;at&quot;:19106},{&quot;text&quot;:&quot; app-1 (Scripted) $ git commit -q -am \&quot;fix(app): a blank name greets the world [G1]\&quot;&quot;,&quot;at&quot;:19508},{&quot;text&quot;:&quot; app-1 (Scripted) $ pullboard submit 1&quot;,&quot;at&quot;:20280},{&quot;text&quot;:&quot; submitted #1 at e9f29935400c; no item check; full gate: affected-test selection is not enabled for this project; gate green in 0s; timing (node): wall 0.00s, slot wait 0.00s; per-test timing unavailable: output was not TAP or JUnit (one or more phases); timing profile: greeter/.git/worktrees/greeter-app-1/pullboard-submit.log.profile.json&quot;,&quot;at&quot;:21286},{&quot;text&quot;:&quot;7 The verifier breaks the fix on purpose, to prove the new test can fail, then restores it and accepts.&quot;,&quot;at&quot;:22489},{&quot;text&quot;:&quot; review-1 (Scripted) $ git switch -q --detach e9f29935400c&quot;,&quot;at&quot;:22892},{&quot;text&quot;:&quot; review-1 (Scripted) $ node --test # with the fix removed&quot;,&quot;at&quot;:23322},{&quot;text&quot;:&quot; # pass 1&quot;,&quot;at&quot;:23411},{&quot;text&quot;:&quot; # fail 1&quot;,&quot;at&quot;:23411},{&quot;text&quot;:&quot; review-1 (Scripted) $ git checkout -- src/greet.mjs&quot;,&quot;at&quot;:23814},{&quot;text&quot;:&quot; review-1 (Scripted) $ pullboard verify 1 accept --note \&quot;removed the blank-name fix: its new test failed; restored, both pass\&quot;&quot;,&quot;at&quot;:24235},{&quot;text&quot;:&quot; verified #1: CRITERION_MET; no frozen check ran&quot;,&quot;at&quot;:24788},{&quot;text&quot;:&quot;8 The coordinator merges it. The ledger is the receipt.&quot;,&quot;at&quot;:25993},{&quot;text&quot;:&quot; coordinator (unknown) $ git merge -q --ff-only app/1&quot;,&quot;at&quot;:26392},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard merged 1 e9f29935400c&quot;,&quot;at&quot;:26822},{&quot;text&quot;:&quot; #1 merged as e9f29935400c&quot;,&quot;at&quot;:27199},{&quot;text&quot;:&quot; coordinator (unknown) $ pullboard ledger&quot;,&quot;at&quot;:27604},{&quot;text&quot;:&quot; 1 verified by a second agent · 0 awaiting verification · 1 rejection along the way&quot;,&quot;at&quot;:27826},{&quot;text&quot;:&quot; | # | Lane | Item | Spec | Built by | Verified by | Check | Commit | Merged |&quot;,&quot;at&quot;:27826},{&quot;text&quot;:&quot; | 1 | app | Greeting | G1 | app-1 (Scripted) | review-1 (Scripted) | unchecked | e9f29935400c | e9f29935400c |&quot;,&quot;at&quot;:27826},{&quot;text&quot;:&quot;Nothing shipped until a second agent verified it.&quot;,&quot;at&quot;:27837},{&quot;text&quot;:&quot; Look around: cd greeter &amp;&amp; pullboard log&quot;,&quot;at&quot;:27837},{&quot;text&quot;:&quot;see it: pullboard view&quot;,&quot;at&quot;:27837}]</metadata>
<style>
.tour-card{--surface:#ffffff;--line:#dce5df;--ink:#101714;--muted:#4f5b55;--faint:#65746b;--blue:#315f8f;--violet:#6547bc;--green:#087546;--green-soft:#dff4e8;--red:#b33026;--red-soft:#fce8e5;--highlight:#edf7f1;font-family:system-ui,-apple-system,"Segoe UI",sans-serif}
-@media(prefers-color-scheme:dark){.tour-card{--surface:#111714;--line:#34443a;--ink:#e9eeeb;--muted:#b6c3bc;--faint:#9cafa3;--blue:#80bfff;--violet:#c1aeff;--green:#61e6b1;--green-soft:#163829;--red:#ff8a80;--red-soft:#321917;--highlight:#193426}}
+
.surface{fill:var(--surface);stroke:var(--line)}.divider{stroke:var(--line)}.heading{fill:var(--ink);font-size:16px;font-weight:650}.command,.number,.actor,.verdict text{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.command,.number{fill:var(--faint);font-size:12px}.actor{font-size:12px;font-weight:600}.you{fill:var(--ink)}.coordinator{fill:var(--blue)}.builder{fill:var(--violet)}.verifier{fill:var(--green)}.description{fill:var(--muted);font-size:13px}.footer{fill:var(--muted);font-size:12px}.verdict text{font-size:11px;font-weight:650}.reject rect{fill:var(--red-soft)}.reject text{fill:var(--red)}.accept rect{fill:var(--green-soft)}.accept text{fill:var(--green)}
.step-glow{fill:transparent;animation:light-step 16s linear infinite}@keyframes light-step{0%,11%{fill:var(--highlight)}13%,100%{fill:transparent}}
@media(prefers-reduced-motion:reduce){.step-glow{animation:none;fill:transparent}}
diff --git a/test/readme.test.js b/test/readme.test.js
index 7370fefa..a32dba24 100644
--- a/test/readme.test.js
+++ b/test/readme.test.js
@@ -4,10 +4,11 @@
* text, and the lifecycle is drawn from the declaration itself (M1), refusing what it cannot place.
*/
import assert from 'node:assert/strict';
-import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { after, test } from 'node:test';
import { FIGURES, drawLifecycle } from '../docs/img/draw.mjs';
+import { themeVariants } from '../docs/img/theme.mjs';
import { HELP, commandPhrases } from '../src/help.js';
import { MACHINE } from '../src/machine.js';
import { agentsBlock } from '../src/templates.js';
@@ -20,9 +21,50 @@ const README = readFileSync(join(ROOT, 'README.md'), 'utf8');
const drawn = Object.keys(FIGURES).map((name) => `docs/img/${name}.svg`).sort();
const SHOT_FIGURES = [
{ path: 'docs/shots/tour.svg', alt: 'The timed Pullboard tour shows a change submitted, rejected for a missed edge, fixed and accepted.' },
- { path: 'docs/shots/desktop.png', alt: "The desktop board shows open, claimed, submitted and accepted work, a Needs you row for a held lane, search in the top bar, the status bar, an accepted item's review history, and a stats line with merged work, sent-back share and the bottleneck recommendation." },
+ { path: 'docs/shots/desktop-light.png', alt: "The desktop board shows open, claimed, submitted and accepted work, a Needs you row for a held lane, search in the top bar, the status bar, an accepted item's review history, and a stats line with merged work, sent-back share and the bottleneck recommendation." },
];
+/**
+ * The dark file a README picture pairs with its light file: a PNG's `-light` becomes `-dark`, and an SVG gains `-dark`.
+ *
+ * @param {string} light the light file's path under the repo
+ * @returns {string} the dark file's path
+ */
+function darkTwin(light) {
+ return light.endsWith('-light.png') ? light.replace(/-light\.png$/u, '-dark.png') : light.replace(/\.svg$/u, '-dark.svg');
+}
+
+/**
+ * The markup a README figure uses: a picture whose dark source GitHub shows to dark readers, then the light image.
+ *
+ * @param {string} light the light file's path under the repo
+ * @param {string} alt the figure's alt text, as the README writes it
+ * @returns {string} the picture markup, exactly as the README holds it
+ */
+function figureMarkup(light, alt) {
+ return `<picture>\n <source media="(prefers-color-scheme: dark)" srcset="${darkTwin(light)}">\n <img src="${light}" alt="${alt}">\n</picture>`;
+}
+
+/**
+ * Every local image the README shows: its light file, the dark file its picture gives (null when none),
+ * and its alt text. Pictures come first, then images written as plain Markdown, which have no dark file.
+ *
+ * @param {string} markdown the README text
+ * @returns {{ light: string, dark: string | null, alt: string }[]}
+ */
+function localImages(markdown) {
+ const pictures = [...markdown.matchAll(/<picture>([\s\S]*?)<\/picture>/gu)].map(([, body]) => {
+ const img = /<img\b[^>]*>/u.exec(body)?.[0] ?? '';
+ return {
+ light: /\ssrc="([^"]+)"/u.exec(img)?.[1] ?? '',
+ dark: /<source\b[^>]*media="\(prefers-color-scheme: dark\)"[^>]*srcset="([^"]+)"/u.exec(body)?.[1] ?? null,
+ alt: /\salt="([^"]*)"/u.exec(img)?.[1] ?? '',
+ };
+ });
+ const bare = [...markdown.replace(/<picture>[\s\S]*?<\/picture>/gu, '').matchAll(/!\[([^\]]*)\]\(([^)\s]+)\)/gu)].map(([, alt, light]) => ({ light, dark: null, alt }));
+ return [...pictures, ...bare].filter(({ light }) => light.startsWith('docs/'));
+}
+
test("Pullboard's doctrine carries its four checks [D1,D3]", () => {
const box = e2e.project();
const checkout = join(box.dir, 'doctrine-checkout');
@@ -145,15 +187,28 @@ function unbalanced(xml) {
}
test('the README links every figure draw.mjs draws, each committed exactly as drawn [I10]', () => {
- const links = [...README.matchAll(/!\[([^\]]*)\]\((docs\/img\/[^)\s]+)\)/g)].map(([, alt, path]) => ({ alt, path }));
+ const links = localImages(README).filter(({ light }) => light.startsWith('docs/img/') && light.endsWith('.svg') && light !== 'docs/img/logo.svg').map(({ alt, light }) => ({ alt, path: light }));
assert.deepEqual(links.map((link) => link.path).sort(), drawn, 'the README links each drawn figure once, and nothing else under docs/img');
for (const { alt, path } of links) assert.ok(alt.trim().length >= 40, `${path} has alt text that says what it shows`);
- assert.ok(README.includes('![An agent asks its coordinator. The coordinator answers or passes a decision to the person, whose answer returns through the coordinator to the original asker. Agents send decision requests to their coordinator first.](docs/img/chain.svg)'), 'the chain figure says decision requests go through the coordinator');
- for (const { alt, path } of SHOT_FIGURES) assert.ok(README.includes(`![${alt}](${path})`), `${path} and its alt text remain in the README`);
- const committed = readdirSync(join(ROOT, 'docs', 'img')).filter((file) => file.endsWith('.svg') && !['logo.svg', 'logo-dark.svg'].includes(file)).map((file) => `docs/img/${file}`).sort();
+ assert.ok(README.includes(figureMarkup('docs/img/chain.svg', 'An agent asks its coordinator. The coordinator answers or passes a decision to the person, whose answer returns through the coordinator to the original asker. Agents send decision requests to their coordinator first.')), 'the chain figure says decision requests go through the coordinator');
+ for (const { alt, path } of SHOT_FIGURES) assert.ok(README.includes(figureMarkup(path, alt)), `${path} and its alt text remain in the README`);
+ const committed = readdirSync(join(ROOT, 'docs', 'img')).filter((file) => file.endsWith('.svg') && !file.endsWith('-dark.svg') && file !== 'logo.svg').map((file) => `docs/img/${file}`).sort();
assert.deepEqual(committed, drawn, 'docs/img holds exactly the figures draw.mjs draws');
for (const [name, draw] of Object.entries(FIGURES)) {
- assert.ok(readFileSync(join(ROOT, 'docs', 'img', `${name}.svg`), 'utf8') === draw(), `docs/img/${name}.svg differs from what draw.mjs draws: run node docs/img/draw.mjs`);
+ const { light, dark } = themeVariants(draw());
+ assert.ok(readFileSync(join(ROOT, 'docs', 'img', `${name}.svg`), 'utf8') === light, `docs/img/${name}.svg differs from what draw.mjs draws: run node docs/img/draw.mjs`);
+ assert.ok(readFileSync(join(ROOT, 'docs', 'img', `${name}-dark.svg`), 'utf8') === dark, `docs/img/${name}-dark.svg differs from what draw.mjs draws: run node docs/img/draw.mjs`);
+ }
+});
+
+test('every local README image has a dark file that a picture gives the reader, and both files exist [I10,I11,I13]', () => {
+ const images = localImages(README);
+ assert.ok(images.length >= 15, `the README shows ${images.length} local images; expected at least the 15 pictures`);
+ for (const { light, dark } of images) {
+ assert.ok(dark, `${light} is inside a picture with a dark source, so it follows the reader's theme; an image with one theme fails here`);
+ assert.equal(dark, darkTwin(light), `${light} pairs with ${darkTwin(light)}`);
+ assert.ok(existsSync(join(ROOT, light)), `${light} is committed`);
+ assert.ok(existsSync(join(ROOT, dark)), `${dark} is committed`);
}
});
@@ -253,12 +308,12 @@ test('README pins its approved Philosophy, Key concepts and Why structure [I10,I
const nextTopLevel = README.indexOf('\n## ', philosophy + 1);
assert.ok(philosophy >= 0 && philosophy < concepts && concepts < whyStart && whyStart < nextTopLevel, 'Philosophy contains Key concepts and Why before the next top-level section');
const approvedOpening = "**Accumulated judgement for agents.** Agents are good at tasks and bad at projects: every new session starts without what you decided, so you become the glue. The agents scale; your judgement doesn't. Pullboard is a structural approach to orchestrating agents coherently over long-term builds, so you can trust your agentic workforce to fill in the blanks the way you would, without re-prompting them.";
- const openingWithFigure = `${approvedOpening}\n\n![How it holds. Your decision becomes a bar each piece of work is frozen against; a second agent checks the exact commit; the board keeps what passed, what failed and why; the next agent starts from there.](docs/img/holds.svg)\n\n**Vibe code a real product.**`;
+ const openingWithFigure = `${approvedOpening}\n\n${figureMarkup('docs/img/holds.svg', 'How it holds. Your decision becomes a bar each piece of work is frozen against; a second agent checks the exact commit; the board keeps what passed, what failed and why; the next agent starts from there.')}\n\n**Vibe code a real product.**`;
assert.ok(README.includes(openingWithFigure), 'the approved opening and holds figure sit directly before the unchanged lead');
assert.equal(README.split(approvedOpening).length - 1, 1, 'the approved opening appears exactly once');
assert.doesNotMatch(`${approvedOpening} ${FIGURES.holds()}`, /\b(?:memory|remember)\b/iu, 'the opening and its figure avoid those terms');
const section = README.slice(philosophy, nextTopLevel);
- assert.ok(section.includes('### Why\n\nPast the demo, the same things break.\n\n![Where vibe coding breaks, and what holds instead.'), 'Why opens with the approved line, then the figure of what breaks and what holds');
+ assert.ok(section.includes('### Why\n\nPast the demo, the same things break.\n\n<picture>\n <source media="(prefers-color-scheme: dark)" srcset="docs/img/why-dark.svg">\n <img src="docs/img/why.svg" alt="Where vibe coding breaks, and what holds instead.'), 'Why opens with the approved line, then the figure of what breaks and what holds');
for (const text of [
'You do not explain twice. You rule the agents. Hierarchy is enforced. Judgement is yours. Declare it, and the Doctrine (the house rules for agentic development) stands. **You speak the constraints, agents fill in the blanks.** The Spec is canon. Then code. Then proof.',
'Five primitives. Everything else is built on them.',
@@ -304,7 +359,7 @@ test('the README starts setup with your agent [I1]', () => {
assert.ok(setup.includes('Your agent installs Pullboard, runs `pullboard init` and commits the setup.'), 'the agent does the setup work');
assert.ok(setup.includes('You approve your requirements and answer its questions.'), 'the person supplies decisions');
assert.ok(setup.includes('in the view it opens'), 'the agent opens the view for those decisions');
- assert.ok(setup.includes("![Starting with an agent. You ask your agent to install Pullboard and set it up for what you're building. It runs the install and pullboard init, commits the setup, then walks you through your requirements and questions in the view it opens for you.](docs/img/agent-start.svg)"), 'the figure describes the complete agent path');
+ assert.ok(setup.includes(figureMarkup('docs/img/agent-start.svg', "Starting with an agent. You ask your agent to install Pullboard and set it up for what you're building. It runs the install and pullboard init, commits the setup, then walks you through your requirements and questions in the view it opens for you.")), 'the figure describes the complete agent path');
assert.ok(setup.indexOf('You can also run it yourself.') > promptAt, 'running setup yourself is the second path');
assert.ok(setup.includes('`init` writes your spec, doctrine and agent instructions, and installs the hooks and the board. Commit what it wrote, then open Claude Code in the repo and say what to build. That agent becomes your coordinator.'), 'the manual explanation remains unchanged');
});
@@ -335,6 +390,9 @@ test('README is concise and skimmable without removing its instructions or figur
const nestedHeading = /^(#{1,6})\s/u.exec(opening);
if (nestedHeading) {
assert.ok(nestedHeading[1].length > heading[1].length, `${proseLines[index]} only opens with a nested heading`);
+ } else if (opening === '<picture>') {
+ const img = lines.slice(next, next + 4).find((line) => line.includes('<img')) ?? '';
+ assert.match(img, /\salt="[^"]+[.!?]"/u, `${proseLines[index]} opens with a descriptive figure`);
} else if (opening.startsWith('![')) {
assert.match(opening, /^!\[[^\]]+[.!?]\]\(/u, `${proseLines[index]} opens with a descriptive figure`);
} else if (opening.startsWith('```')) {
@@ -354,6 +412,7 @@ test('README is concise and skimmable without removing its instructions or figur
let paragraph = [];
let inCode = false;
let inCenteredHeader = false;
+ let inPicture = false;
const flush = () => {
if (paragraph.length) paragraphs.push(paragraph.join(' '));
paragraph = [];
@@ -367,6 +426,11 @@ test('README is concise and skimmable without removing its instructions or figur
inCenteredHeader = true;
} else if (inCenteredHeader) {
if (line === '</p>') inCenteredHeader = false;
+ } else if (!inCode && line === '<picture>') {
+ flush();
+ inPicture = true;
+ } else if (inPicture) {
+ if (line === '</picture>') inPicture = false;
} else if (inCode || !line.trim() || /^#{1,6}\s|^!\[|^\|/u.test(line)) {
flush();
} else if (/^\s*[-*]\s/u.test(line)) {