Docs: rewrite board.md and split out a Dispatch page (T297)

[smarzban]

Task A of the docs cleanup (T297). board.md is rewritten under the agreed headings. The Agents section moves to a new dispatch.md, rewritten rather than pasted. The new page sits in the sidebar after Board.

Words

File	Before	After
site/src/content/docs/docs/board.md	11,583	3,631
site/src/content/docs/docs/dispatch.md (new)	0	2,428

Both pages pass a length check: no paragraph over 60 words, no sentence over 25.

Other files

• site/astro.config.mjs: sidebar Dispatch after Board.
• site/src/lib/agent-docs.mjs: dispatch added to SIDEBAR_SLUGS, so llms-full.txt includes the page.
• site/test/agent-surface.test.mjs: Dispatch added to SIDEBAR_TITLES. Task E may also edit this file; my hunk is one line.
• tests/docs_parity.rs: palette test only. It learns a new condition, A task list has focus. "Always" rows must now also be offered over an open task page, so the old table (group/sort/fold under Always) fails this test. Task C edits the keys functions in this file; the hunks are separate.

Moved facts

Fact	From	To
Assign, dispatch, names, base, marked-set start, relaunch, decision cards, cleanup, merge, Windows	board.md "Agents"	dispatch.md, one agreed heading each
Status-verb key table, card keys, multi-select keys, fold keys, picker keys	board.md	Linked to keys.md (#board, #cards, #esc-and-quit)
Reply and feedback box keys	board.md	Linked to task-page.md #blocked
Board defaults, merge method, agent profiles, fetch window	board.md (repeated)	Linked to storage.md #configuration
Notices detail	board.md	Linked to storage.md #starter-tasks
ON DECK order, section order, multi-select (were under "Reply to a running agent")	board.md	Sections and status, Multi-select
Status-row string catalogues (cleanup outcomes, merge checks, undo table, reply outcomes)	board.md	Dropped; one example kept where a reader needs to recognise it

Real task and PR numbers (T169/T203/T204, #190/#193/#194), repo paths, store field names (past_reviews), gh flags and history are gone. Examples use T12/T202/T205 and PR #42. One name for each thing: Projects view, and workspace for what cleanup closes. The quoted cleanup card says "agent pane", so the page explains that once.

Corrected claims

Old claim (board.md)	Code	Now
r on another row says not blocked	src/ui/board/apply.rs:1388	not blocked or in review
Palette: group by / sort by / fold listed under Always	src/ui/board/commands.rs:135, model.rs:6021	New row: A task list has focus (not the Projects view, not an open task page)
ssr finds set status: review	commands.rs:224 subsequence match; ssr first matches set status: ready	rev, which matches only review
Headers that open nothing on double-click omit unassigned (Mouse)	apply.rs:2665-2697	unassigned listed
Quitting never mentions ctrl+c	src/ui/input.rs:2436, :2553, :2663	ctrl+c quits from the board, a task page, and Help
Marked-set start: further dispatches and quitting wait	src/app.rs:4527-4564 (refused with a bulk dispatch is still running …)	Refused until every launch lands
Marked-set card title only described when nothing launches	src/ui/board/draw.rs:357-375	Dispatch N tasks? (N = launches), Start N tasks? when nothing launches
core.longpaths off: dispatch says so once	src/dispatch.rs:3647-3651 (per dispatch)	Each dispatch says so
Windows batch file: nothing starts	src/agents.rs:409-462 (refused in the pane after the workspace opens)	The workspace opens; the pane refuses and the agent does not start
Sort exclusions not stated (only group's)	model.rs:4266-4272	Neither group nor sort offers what the view fixes
[board] defaults apply to every view	model.rs:6816-6829	Desk and project boards only; thread and @name views start at none/recent
Project-board filter clears when switching projects	model.rs:3641-3644	Clears when you leave that board; the desk filter lasts the session
NEEDS YOU = blocked/review on you	src/ui/queue.rs:1131-1158	Also tasks blocked on a task that is done or deleted
After picker refuses a task running after itself	model.rs:5317-5318 (the task is left out of the list)	"lists the other tasks"
Setting a status moves a task to the top of its new section	src/ui/queue.rs:1206-1207, :1273 (ready sorts oldest pick first; open keeps capture order)	Only NEEDS YOU, IN MOTION and the done drawer put the latest change on top; a task set ready joins the end of ready; the inbox keeps capture order
Search on the Projects tab matches names/paths	model.rs:4180-4191	Only on Overview; a thread or @name view searches tasks

Suspected bugs (code not changed)

1. A launch that fails after the worktree exists leaves the worktree and Herdr workspace behind, with no dispatch record to clean them up (src/dispatch.rs:3641, run_in_pane error returns without removing them).
2. Windows: a profile whose command resolves only to a .cmd/.bat records the dispatch and sets started before the pane refuses. The task shows ◉ with no agent (src/agents.rs:409-462).
3. A task blocked on a task number that is now done sits in NEEDS YOU but keeps the □ (elsewhere) glyph (src/ui/render.rs:1337-1339).
4. Without marks, ctrl+b/ctrl+r refuse a done task. In a marked set, done tasks go into the block or review card with the rest (apply.rs:2862, :2895).

Inbound links for other tasks

These pages link old board.md anchors that no longer exist. They belong to other tasks, so I didn't touch them:

File	Old anchor	New target
capture.md	/docs/board/#base-branch	/docs/dispatch/#base-branch
cli.md	#block-with-a-reason, #reply-to-a-running-agent	/docs/board/#block-review-reply
cli.md	#dispatch	/docs/dispatch/#dispatch
cli.md (×2), storage.md	#dispatch-on-windows-preview	/docs/dispatch/#windows-preview
keys.md	#agents	/docs/dispatch/
keys.md, task-page.md	#complete-and-clean-up	/docs/dispatch/#complete-and-clean-up
keys.md, task-page.md	#wide-stage-slider	/docs/board/#wide-layout
storage.md	#archive	/docs/board/#done-drawer-and-archive
storage.md	#merge-the-pull-request	/docs/dispatch/#merge-the-pull-request
task-page.md	#base-branch, #dispatch (×2), #relaunch	the same heading on /docs/dispatch/
task-page.md	#reply-to-a-running-agent, #review-with-what-was-done	/docs/board/#block-review-reply
task-page.md	#status	/docs/board/#sections-and-status

#after, #group-and-sort, #save-failures and #delete-and-undo still resolve. The AGENTS.md product-reference row should name dispatch.md (task F). The llms.txt docs list needs the Dispatch page (task E).

These links in board.md and dispatch.md point only at agreed headings on other pages, e.g. keys #cards and #esc-and-quit, storage #configuration and #starter-tasks. Those anchors appear once task C and task D land.

Checks

• cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test: green, 2150 passed.
• cargo test --test integration -- docs_parity:: cli_discovery::: 5 passed. Restoring the old Always row makes the palette test fail ("group by…" is documented as always available but vanishes over a task page).
• cd site && npm ci && npm test && npm run build: 52 passed, build clean.
• src/ not touched, so no Windows clippy. npm run test:parity not run (task G owns the port). No live Herdr smoke: docs only.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
herdr-tsk	Ready	Preview	Oct 19, 2026 11:57pm UTC