@gavin-hu/my-pi-agent 0.19.0 → 0.20.0

package/docs/extensions/board.md

@@ -1,25 +1,31 @@
 # board — one shared feature board per repository
 
-Every Pi session on a repository reads and writes the same cards, and a repository
-has **one** page: the session that starts it serves it under the seat `team-lead`, and
-every other session opens that page read-only instead of a second one. A card is one
-**feature**: its outcome, who holds it, where the work happens, the plan it is
-executing, how urgent it is, what it waits for, and the notes that explain how it got
-there.
+Every Pi session on a repository works the same cards through the tools, and a repository
+has **one** page that shows them: the session that starts it serves it under the seat
+`team-lead`, and every other session opens that same page instead of a second one. The
+page is a **view** — it cannot change a card — so what a browser shows and what the
+terminal holds cannot disagree. A card is one **feature**: its outcome, who holds it,
+where the work happens, the plan it is executing, how urgent it is, what it waits for,
+and the notes that explain how it got there.
 
 The steps of the work are deliberately *not* on the board. They live in the
 owner's plan and in `todo`; the board answers who is doing what, and what needs a
 decision.
 
-<img src="../../assets/screens/board.png" alt="The board page: a toolbar with the seat the page writes as, a live badge, Board and Team tabs, done-of-total progress, a filter and a New card button; four lane trays, each with a dot, a count and a fold control; and cards carrying an owner chip, path hints, a reason line and their actions" width="100%">
+<img src="../../assets/screens/board.png" alt="The board page: a toolbar with the seat the page is served as, a live badge, Board and Team tabs, done-of-total progress, a filter, the keys button and a theme toggle; four lane trays, each with a dot, a count and a fold control; and cards carrying an owner chip, path hints and a reason line, with no button on any of them" width="100%">
 
-*`/board`: the four lanes, with a new card one keystroke from its dialog and the round one tab away.*
+*`/board`: the four lanes, with the round one tab away and every card opened by its title.*
+
+<img src="../../assets/screens/card-dialog.png" alt="The card dialog on one doing card: the id and title with the lane as a dot and a word, a head/value ladder reading owner, updated, in lane, last edited, plan and paths, each value on one line, then a Notes section whose sentences are attributed under them" width="100%">
+
+*The card dialog: the record of one card — a ladder of facts, then its notes at body size
+(`screenshot:board --dialog card`).*
 
 ## Capabilities
 
 | Capability | How | What you get |
 |---|---|---|
-| A shared feature list for one repository | `board` action `list` | Every card in lane order — `todo`, `doing`, `blocked`, `done` — or one card, or one lane |
+| A shared feature list for one repository | `board` action `list` | Every open card in lane order — `todo`, `doing`, `blocked` — or one card, or one lane; the `done` cards are left out with a count of how many, and `status: "done"` reads them |
 | The lead's rollup | `board` action `list` with `round: true` | Every owner with its live cards and, beside the count, what it has finished — an owner whose last card is done stays listed — then unassigned, unplanned, blocked, idle, and done |
 | Publish a feature | `board` action `add` | A `todo` card with path hints and a first note |
 | Take a feature | `board` action `claim` | The card is `doing` and owned by this session |
@@ -29,16 +35,19 @@ decision.
 | Record the plan | `board` action `plan` | The plan file the card is executing, so "unplanned" work is visible |
 | Fix what a card says | `board` action `edit` | A new title, path hints, priority, or the cards it waits for — by its holder, or by anyone while nobody holds it |
 | Say how urgent it is | `board` action `add` or `edit` with `priority` | `high` sorts first inside its lane, and the card says so |
-| Record what a card waits for | `board` action `edit` with `dependsOn` | An unfinished dependency refuses a claim and a move to `doing` or `done`, and the reason line names it |
-| Hand a card to a teammate | `Assign to` in the card dialog | The owner is recorded and the card's history says no handoff was sent — `team`'s `assign` is the one that messages a peer |
+| Record what a card waits for | `board` action `edit` with `dependsOn` | An unfinished dependency refuses a claim and a move to `doing` or `done`, and the reason line names it; the card it waits on answers the other half — `list` on it names the cards waiting on it, and its dialog row `waited on by` says the same |
+| Hand a card to a teammate | `team` action `assign` | The owner is recorded **and** a handoff is sent to that session's inbox. The page cannot do this: a browser has no way to message a peer, so a page assignment that recorded an owner and told nobody is gone with the write path |
 | Take a card back from the tool | `board` action `reclaim` | The owner clears and the card returns to To do, without the page and without `team` |
-| Find a card without reading every lane | `board` action `list` with `query` | The cards whose title, path hint, or holder matches — the same rule the page's filter uses |
+| Find a card without reading every lane | `board` action `list` with `query` | The cards whose title, holder, path hint, plan, or note text matches — the same rule the page's filter uses, from one body (`MATCHES_QUERY_JS`) |
 | See the work you hold | `board` action `list` with `mine` | The cards this session holds, by the same rule a claim is checked against |
-| Delete a card | `board` action `drop` | The card and its notes are gone; a `todo` or `done` card is anyone's to drop, one in flight only its holder's, and one that a card waits on cannot leave at all |
+| Set a finished card aside | `board` action `archive` | A `done` card's file moves into an `archive/` pile beside the board with its notes, plan, owner, and landed commit still readable, and the board stops reading it: the card named by `card`, or every finished card when none is named. It is a decision a person makes, never a threshold in the background, and nothing un-archives |
+| Delete a card | `board` action `drop` | The card and its notes are gone, and its id is spent: a record of the title, the lane, who ended it, and when stays in `ended/`, so a note or a handoff that names that id cannot come to mean a different feature. A `todo` or `done` card is anyone's to drop, an archived one included, one in flight only its holder's, and one that a card waits on cannot leave at all |
 | One page per repository | `/board` | Serves a loopback page as `team-lead` with a **Board** and a **Team** tab, following the store live; a page already served is opened instead |
-| Watch somebody else's page | `/board` on a session that is not serving | The same page, **read-only**: no **+ New card**, no `Claim`, `Move`, `Edit`, `Drop` or note field, because the note a viewer reads carries a credential that may only read. The viewer joins the team under its own label, so a handoff can still reach it |
+| Watch somebody else's page | `/board` on a session that is not serving | The same page, because there is one: every page is a read view, so a second session gets exactly what the first one sees instead of a writable rival. It joins the team under its own label, so a handoff can still reach it |
+| Read a board at its real size | the `Done` fold, an empty lane's rail | `Done` starts folded at six cards or more, its count in the head, and a reader's toggle decides from then on. A lane holding no cards narrows to its head, word, and count, so the lanes carrying work keep the width |
+| Open a card | the card's title, or `Enter` on a focused one | The title is the only door, because it is the only one needed: it opens the dialog holding the card whole — its lane, its owner, its paths, what it waits for, its plan, and every note |
 | See the lead's round at a glance | `/board team`, or `/team` with no browser | A queue of cards that need a decision, each with the reason and its way out, then who is on the team and what they hold |
-| Join the team | `/board`, or any card you work | Opening the page joins this session to the team — as `team-lead` when it serves the page, under its own name when it watches one — and the first card write joins it too, so nothing has to be armed by hand. `/board status` says which team a `/board` in this session put you on |
+| Join the team | `/board`, or any card you work | Opening the page joins this session to the team — as `team-lead` when it serves the page, under its own name when it opens one somebody else serves — and the first card a tool writes joins it too, so nothing has to be armed by hand. `/board status` says which team a `/board` in this session put you on |
 | See who is around | `/board team` | The Teammates list: every session this repository's bus has recorded, plus every owner a card names, each stating `live`, `quiet`, `no record`, or `—` when no bus is loaded |
 
 ## Quickstart
@@ -60,11 +69,11 @@ lead: board list round: true
 
 | Command | Who | Effect |
 |---|---|---|
-| `/board` | lead | Serves the page as `team-lead`, or opens the one another session already serves |
+| `/board` | lead | Serves the page as `team-lead`, or opens the one another session already serves — and opens it again when it is already up, so a closed tab is one command away. The line it prints names the address |
 | `/board team` | lead | The same, opened on the Team tab |
-| `/board status` | both | One line: the seat, the port, how many tabs are watching, the store, and the team the last `/board` joined — or the page being watched |
-| `/board stop` | lead | Stops the page this session serves; on a watching session it says who serves it |
-| `/team` | both | The round in the terminal: the rollup, then who is live and who has gone quiet |
+| `/board status` | both | One line: the seat, the port, how many tabs are watching, the store, and the team the last `/board` joined — or the page being watched, and whether the note behind it still answers |
+| `/board stop` | lead | Stops the page this session serves; a watched page that has stopped answering is dropped instead, and a watched page that is alive is its owner's to stop |
+| `/team` | both | The round in the terminal: the rollup, the work a dead owner left behind, then who is live, who has gone quiet, and who is gone |
 
 **Who serves the page.** The first `/board` in a repository serves it; after that the
 page is found by the note it leaves beside the cards (`page.json`, in the board's own
@@ -72,7 +81,11 @@ directory), so a second session opens the same page rather than a rival one. Tha
 while a page answers; if nobody is serving, the next `/board` serves — the seat's name
 does not change, so a card a browser claimed is still the seat's. A note a session left
 behind when it died is not a dead end either: `/board` says which page it named — with its
-URL — takes the note over, and serves.
+URL — takes the note over, and serves. A clean exit is not that case: `/board stop` and a
+session shut down normally both take their note with them, so the note that survives is
+one a crash left. `/board status` probes the note it is watching, and names one that
+answers nobody; `/board stop` then drops it (a token-safe clear, so a page that came back
+keeps its own note) instead of waiting for the next `/board` to trip over it.
 
 **Joining.** One thing, done for you: `/board` puts this session on the team — as
 `team-lead` when it serves the page, under its own name when it watches one — and so does
@@ -82,8 +95,10 @@ session that has neither opened the board nor touched a card is not on it. `/boa
 status` reports the join `/board` made itself: a session that joined by writing a card
 is on the team, and its status line does not say so.
 
-The page is still a seat: it writes as `team-lead` with an id of its own, so a card it
-claimed comes back with `reclaim` rather than a `release` from the terminal.
+The page still serves as a seat: `/board status` names `team-lead`, the toolbar chip says
+so, and a card a browser claimed **before** the page stopped writing still names
+`board:team-lead` as its owner — `reclaim` is how a lead takes that back from the
+terminal.
 
 ## Tool
 
@@ -92,42 +107,65 @@ claimed comes back with `reclaim` rather than a `release` from the terminal.
 
 | Action | Parameters | Result |
 |---|---|---|
-| `list` | `status?`, `mine?`, `card?`, `query?`, `round?` | the cards in lane order, one card, or what a query or `mine` matches; `round: true` adds the rollup, which always covers the whole board |
+| `list` | `status?`, `mine?`, `card?`, `query?`, `round?`, `archived?` | the cards in lane order, one card, or what a query or `mine` matches — a query reads a card's title, holder, path hints, plan, and the text of its notes; a listing that names no lane leaves out the `done` cards and says how many, since a finished card is history rather than work; `round: true` adds the rollup, which always covers the whole board; `archived: true` reads the archive instead of the board, with `query` and `mine` narrowing it and `status`/`round` refused |
 | `add` | `title`, `paths?`, `priority?`, `note?` | the new `todo` card |
 | `claim` | `card` | the card, now `doing` and owned by this session |
-| `release` | `card` | the card, back in `todo` |
+| `release` | `card` | the card, back in `todo`, keeping any block it recorded |
 | `reclaim` | `card` | the card, back in `todo`, whoever held it |
-| `move` | `card`, `status` | the card in its new lane |
+| `move` | `card`, `status`, `blockedBy?` | the card in its new lane; `blockedBy` (one line, ≤200 characters) is what a block waits on, and a move to `done` records the commit `HEAD` resolved to, when the directory is a repository |
 | `note` | `card`, `text` | the card with the note appended |
 | `plan` | `card`, `path` | the card with its plan recorded |
 | `edit` | `card`, `title?`, `paths?`, `priority?`, `dependsOn?` | the card with what it says corrected; an omitted field is left alone, and `dependsOn: []` removes every link |
-| `drop` | `card` | the id that was dropped |
+| `archive` | `card?` | the ids set aside — one finished card, or every finished card when no card is named; a card still in flight is refused |
+| `drop` | `card` | the id that was dropped, whose number is now spent |
 
 `card` takes `4` or `#4`. A refused call is an error result that still carries the
 card, so the next attempt starts from the truth.
 
+The parameters are one flat object, so a field is published to every action at once.
+An action reads only the fields in its row above, and a call carrying one that its
+action does not read is **refused**, naming the action that takes it — not ignored.
+`add` with `dependsOn` used to create the card and drop the link, so a caller could
+not tell a recorded link from an ignored one:
+
+```
+add does not act on dependsOn: `edit` takes it.
+```
+
+To link a new card, add it and then edit it. `ACTION_FIELDS` in `types.ts` is the
+table that answers this, and a test holds every published parameter to an action that
+acts on it.
+
 ## Routes
 
-Every route but three needs a token, and which one a request carries decides what it may
-do: the lead's satisfies every route and is in the URL its browser was opened at; the one
-the note carries satisfies the reads and gets a 403 on every write. The three that do not
-are the page's own furniture — `/favicon.ico`, `/theme.js`, and `/app.js` are the same
-bytes to every reader and can neither read nor change a card, so refusing them to a
-fetch that has no token would only break the page. A write is made as the page's
-seat — `team-lead` — not as the session that opened it.
+Every route but two needs the token, and there is exactly one: 128 random bits minted
+when the page starts, compared in constant time, in the URL the browser was opened at.
+The two that do not are the page's own furniture — `/theme.js` and `/app.js` are the same
+bytes to every reader and can neither read nor change a card, so refusing them to a fetch
+that has no token would only break the page. Everything below a
+token is a **read**: the method list is `GET` and `HEAD`, so a `POST` or a `DELETE` is
+refused by the envelope — `405`, `Allow: GET, HEAD` — before the token is even read.
+
+The tab's icon is not a route: the document head links the mark as an SVG data URI, so
+a browser fetches the icon out of the page it already has, and `/favicon.ico` is one more
+path the board does not serve.
 
 ```
-GET    /favicon.ico          204 and no body — no token
 GET    /theme.js             the theme script — no token
 GET    /app.js               the client script — no token
-GET    /                     the document (?view=board|team)
+GET    /                     the document (?view=board|team), whose tab reads
+                             board · <store key> · <N> open
+GET    /index.html           the same document, for a link that names it
+GET    /api/ping             whether the page answers, and nothing else: a session
+                             deciding whether to attach reads this, not the snapshot
 GET    /api/board            the snapshot
 GET    /events               the live frame stream
-POST   /api/cards            add a card
-POST   /api/cards/:id/…      claim, release, reclaim, assign, move, note, plan, edit
-DELETE /api/cards/:id        drop a card
 ```
 
+`/api/ping` exists so a probe cannot be queued behind the page's own work: the snapshot
+is a store read and a roster read on the same event loop, and a page that is busy
+answering its browser would otherwise be declared dead and taken over.
+
 ## Layout
 
 One page, two tabs, one lifecycle. The kit shell keeps the toolbar and the footer
@@ -135,29 +173,30 @@ pinned and makes the main pane the only scroll box; the page adds no second one.
 
 | Band | What it holds |
 |---|---|
-| Toolbar | the mark, the seat the page writes as, as a chip, a live badge (`connecting…`, `live` or `live · 3m`, `reconnecting…`), then one group: the Board\|Team switch, done-of-total progress, a filter, **+ New card**, the keys button, and the theme toggle |
-| New card dialog | the modal the toolbar's button (or `n`) opens: **Title** on its own line, the loudest field on the page, with a `n/120` count once you type; **Paths** under it, space-separated hints; **Priority** as a three-word list; the hint line; and one closer, `Cancel`, beside **Add card**. The title is focused on open, the dialog stays open after an add so a lead can publish several cards, and a draft survives `Esc`, the backdrop, and `Cancel` is the only thing that discards it. The same dialog is the card dialog's **Edit**: prefilled, headed `Edit card #4`, with **Save** in place of Add — and leaving that mode throws its text away, because that text was the card's, not a draft |
-| Lanes | trays, not a bare list: four columns above 1180px, two at 1180px or narrower, one lane plus the lane switch at 860px or narrower — where it opens on the first lane that holds a card. Each head sticks while the pane scrolls, carries its count as a pill, and folds its cards away |
-| Cards | the id and a two-line title (the page's loudest text), an owner chip and an age, a muted priority chip when it is not `normal`, path chips, one reason line in one voice — what a card waits for, a blocked card's last note (or `blocked, with nothing recorded`), `no plan recorded`, `planned`, `✓ done by <owner>`, and the last note of a card that is none of those — clamped, with the whole sentence as its tooltip, and at most three actions — `Claim` or `Move` bordered, then `Note` and `Open`. A card that waits offers no `Claim`, because the claim would be refused: the reason line is what it says instead, and `Move` is drawn on any card still in flight, as the way into its dialog rather than a permission. A viewer's page draws `Open` alone, and no **+ New card**: the document says `data-writes="0"` and every affordance reads it. A hovered card lifts a pixel; a finished one recedes, title and owner chip muted |
-| Team | two panels and a strip. **Needs a decision** is one row per card — a card that is both idle and unplanned arrives once, keeping its strongest reason — laid out as two lines: the id, title, owner chip and `Reclaim` (or `Claim` when nobody holds it) on the first, the reason on the second with the whole sentence as its tooltip, and its kind as a left edge (`--danger` blocked, `--warn` idle, `--dim` unplanned or waiting, the same `--dim` dashed for nobody's). An unassigned card that waits on unfinished work is a row of its own kind, ranked just under a blocker, and offers no action: the claim the rules would refuse is not on the row at all. Above 1180px the queue stops at one screen's height and scrolls inside its panel, so the roster and the Done strip stay on the same page as its top. **Teammates** is one row per person — a state dot, the label, a `you` chip, a `not listening` chip on a live peer whose inbox watch is off, a mail badge, then `live · 3 held · 1 done · oldest 21m` (a quiet session reads `quiet for 2h`, because a word without an age is no reason to reclaim) — sorted you, live, quiet, no record, and an owner whose label nothing answers to keeps its row. Done is one quiet strip whose ids open their cards. Both panels honour the toolbar's filter, and their headings read `shown/total` the way a lane head does. Below 1180px the queue comes first and the roster follows |
-| Card dialog | the lane as a dot and a word beside the title, a meta line, the owner and its priority, the paths, what it waits for, the plan as monospace text, the notes as a timeline (who and when above the sentence, a rule between them), a note field, and `Move to` every lane but the card's own — a waiting card may be parked in `blocked`, and the rules turn down the two that put it back in flight — then `Assign to` for an unowned card, `Release`, `Edit`, `Drop`, `Close` |
+| Toolbar | the mark, the seat the page is served as, as a chip, a live badge (`connecting…`, `live` or `live · 3m`, `reconnecting…`), then one group: the Board\|Team switch, done-of-total progress, a filter, the keys button, and the theme toggle |
+| Lanes | trays, not a bare list: one column per lane, sized by the work it holds — a lane with two cards is wider than one with a single card, and a lane showing nothing, because it holds no cards or because it is folded, narrows to a rail of dot, word, and count — so the lanes carrying work keep the width. Three or four across above 1180px, two at 1180px or narrower, one lane plus the lane switch at 860px or narrower — where it opens on the first lane that holds a card. Each head sticks while the pane scrolls, carries its count as a pill, and folds its cards away: `Done` starts folded at six cards or more, since finished work is history, and a reader's toggle decides from then on |
+| Cards | the id and a two-line title (the page's loudest text and its only door), an owner chip and an age, a muted priority chip when it is not `normal`, path chips, and one reason line in one voice — what a card waits for, a blocked card's recorded reason or else its last note (or `blocked, with nothing recorded`), `no plan recorded`, `planned`, `✓ done by <owner>` with the commit it landed as, and the last note of a card that is none of those — up to two lines at the Team tab's size, with the whole sentence as its tooltip, because the reason is the reason to act on the card. A card draws **no button**: claiming, moving, editing, and annotating are the tools' work, and a face that offered them would be offering a refusal. A hovered card lifts a pixel; a finished one recedes, title and owner chip muted |
+| Team | two panels and a strip. **Needs a decision** is one row per card — a card that is both idle and unplanned arrives once, keeping its strongest reason — laid out as two lines: the id, title and owner chip on the first, the reason on the second — a blocked card's recorded `blockedBy`, else its last note, and `offered 2h ago — nobody took it` for a card whose offer went unanswered — with the whole sentence as its tooltip, and its kind as a left edge (`--danger` blocked, `--warn` idle, `--dim` unplanned or waiting, the same `--dim` dashed for nobody's). The row is a reason to pick the card up in the terminal, and it draws no button: claiming and reclaiming are the tools' work. An unassigned card that waits on unfinished work is a row of its own kind, ranked just under a blocker. Above 1180px the queue stops at one screen's height and scrolls inside its panel, so the roster and the Done strip stay on the same page as its top. **Teammates** is one row per person — a state dot, the label, a `you` chip, a `not listening` chip on a live peer whose inbox watch is off, a mail badge, then `live · 3 held · 1 done · oldest 21m` (a quiet session reads `quiet for 2h`, because a word without an age is no reason to reclaim) — sorted you, live, quiet, no record, and an owner whose label nothing answers to keeps its row. Done is one quiet strip whose ids open their cards. Both panels honour the toolbar's filter, and their headings read `shown/total` the way a lane head does. Below 1180px the queue comes first and the roster follows |
+| Card dialog | the record of one card, in two named sections. The head carries the id, the title, and the lane as a dot and a word. **The card** is a ladder — one fact per row, labels sized to the longest of them so the values line up: owner, priority when it is not `normal`, updated, in lane, last edited, landed, waits on, waited on by, plan, paths. `in lane` is the lane the card is in and how long it has held it, read from the card's transitions rather than from `updatedAt`, which a note or an edit moves; a card whose history does not say omits the row. The plan and each path are one line that elides, with the whole value on the hover title; what it waits for reads `#2 (doing)`, the lanes that make the id a decision. Empty rows take their labels with them. **Notes · N** is the cargo at body size on a 68ch measure, each sentence with its attribution under it and a rule between notes, and `M earlier notes dropped` when the store capped them. The body is the only scroll, so the head and `Close` stay put. Nothing in it writes, every field is a set as `textContent`, and the title underneath every card is the way in. `j`/`k` walk to the next or previous card without closing it, and an `sr-only` live region announces `card 2 of 3: <title>` — a title that changes inside an open modal is not announced on its own |
+(feat(team): an offer leaves a record, so its age can be read)
 
 Colour is a role: `--muted` for `todo`, `--accent` for `doing`, `--danger` for
 `blocked` and destructive choices, `--success` for `done`. The Team tab's decision
 rows sit on the kit's `--raised`, the one step above `--surface` that lets a block read
-as a plane instead of an outline; the Done lane sits on the page itself, so history
-stops competing with the lanes a lead works in. A card takes its colour
+as a plane instead of an outline; every lane, `Done` included, keeps that `--surface`
+tray, so a finished card still sits on something and history recedes through its muted
+title and chip instead of through a hole in the row. A card takes its colour
 from the lane it sits in — the head's dot, and the reason line's tone — rather than
 from a bar of its own, so one card does not shout twice. The page states a lane and
 a card with `data-status`, so a theme change repaints it without a rule of its own.
 
 The board as a posting card — the same rules, drawn to be read at half width:
 
-<img src="../../assets/cards/board.png" alt="One board, every session: the page's seat and live badge; four lane trays, each with a dot, a count pill and a fold; one card carrying an id, a title, its age, a priority chip, a path chip, one reason line and its three actions; and the lead's round with two owner lines and the counts unassigned, unplanned, blocked, idle and done" width="100%">
+<img src="../../assets/cards/board.png" alt="One board, every session: the page's seat and live badge; four lane trays — To do, Doing, Blocked, Done — each with a dot, a count pill and a fold; one card carrying an id, a title, an owner chip, a priority chip, its age, a path chip and one reason line, with no action on it; and the lead's round with two owner lines and the counts unassigned, unplanned, blocked, idle and done" width="100%">
 
 *`board`: the lanes, one card's atoms, and the lead's round — three readings of one board, drawn by `screenshot:cards board`.*
 
-<img src="../../assets/cards/board-team.png" alt="The three team verbs as three bands: assign sends a handoff to a named peer, whose claim takes the card; offer broadcasts an event to every other live session without recording an owner, so the first claim wins; reclaim returns the card to To do with its notes kept and no handoff sent" width="100%">
+<img src="../../assets/cards/board-team.png" alt="The three team verbs as three bands: assign sends a handoff to a named peer and writes the card as doing, owned by that peer, before the peer reads the mail; offer broadcasts an event to every other live session without recording an owner, so the first claim wins; reclaim returns the card to To do with its notes kept and no handoff sent" width="100%">
 
 *`board-team`: `assign`, `offer`, and `reclaim` — the two that reach the bus, and the one that writes the card alone (`screenshot:cards team`).*
 
@@ -165,9 +204,8 @@ The board as a posting card — the same rules, drawn to be read at half width:
 
 | Key | What it does |
 |---|---|
-| `n` | New card: open the dialog and focus the title field |
-| `/` | Filter the cards by title, path, or owner |
-| `j` / `k` | Next or previous card |
+| `/` | Filter the cards by title, holder, path hint, plan, or the text of a note |
+| `j` / `k` | Next or previous card — or, with a card open, the next or previous card in the dialog |
 | `Enter` | Open the focused card |
 | `t` | Switch Board and Team |
 | `Esc` | Close a dialog, or clear the filter |
@@ -175,55 +213,88 @@ The board as a posting card — the same rules, drawn to be read at half width:
 
 A dialog traps `Tab`, closes on `Esc` or a backdrop click, and returns focus to
 whatever opened it — the kit's `dialogScript`, shared with the review and browse
-pages. A field keeps its keys: `n` inside the note input types an `n`.
+pages. A field keeps its keys: `/` inside the filter box types a slash.
 
 ## Security
 
-- The page binds loopback only, answers only its own host names, and refuses a
-  state-changing request another site made.
-- There are two credentials, both 128 random bits minted when the page starts and
-  compared in constant time: the lead's, which can change a card, and a viewer's, which
-  cannot. They are in the URL, never a cookie, and there is no CORS. The note beside the
-  cards (`page.json`, owner-only) carries the viewer's and never the lead's.
-- A write is made **as the page's seat** — a browser is not an identity — so
-  the toolbar names the session and claim/reclaim ask first.
-- The page writes only the board store under the agent directory. It never writes
-  your repository, and it reads the session bus's own records read-only — labels,
-  modes, heartbeats, message counts, and whether each is listening — to draw the Teammates list.
+- The page binds loopback only, answers only its own host names, and has no
+  state-changing request to refuse.
+- One credential, 128 random bits minted when the page starts and compared in constant
+  time, in the URL and never a cookie, with no CORS. The note beside the cards
+  (`page.json`, owner-only) carries it, so a second session can attach — and because the
+  page cannot change a card, pasting that URL hands out nothing but a view.
+- The page reads only: the board store under the agent directory, and the session bus's
+  own records read-only — labels, modes, heartbeats, message counts, and whether each is
+  listening — to draw the Teammates list. It never writes your repository.
 
 ## Limitations
 
 - **Ownership is advisory.** Two sessions can still edit the same file; only
   `session-bus`'s path claims are a lock.
+- **A listing is bounded, the rollup is not.** Nothing prunes a finished card by itself, so
+  the cards accumulate — most of this repository's own board was finished cards — and
+  reading them on every call is a cost that grows with the history rather than with the
+  work. A `list` that names no lane therefore leaves `done` out and prints the count, which
+  is what keeps the omission from reading as a smaller board; `status: "done"` reads them,
+  and `round` counts every card, because a rollup that hid half the board would not be one.
+  The page bounds its own View the same way, folding a long `done` lane. `archive` is how a
+  board stops paying for its history at all: the card leaves the board and its read.
 - **A finished card stays finished.** `done` is terminal for every transition — claim,
   assign, release, move, and plan all refuse it — so a card a dependency was recorded
-  against cannot un-finish and reopen the order after the fact. A card finished by
-  mistake is dropped and added again; its notes do not come with it.
+  against cannot un-finish and reopen the order after the fact, and `archive` does not
+  change that: it moves a `done` card's file, and never its lane. The one exception is
+  `edit`: a title, path hints, priority, or `dependsOn` can still be corrected by whoever
+  holds it, or by anyone while nobody does, because a title is what a reader reads and a
+  finished feature whose title is wrong would stay wrong for as long as the board keeps
+  history. A card finished by
+  mistake is dropped and added again: the new card takes a new number, and the dropped
+  one's title and lane stay in `ended/` under the id nothing will use again. Its notes
+  do not come with it.
+- **A card file this build cannot read is reported, not skipped.** A file written by a
+  newer build, a half-written one, or a record moved under another name is named by
+  `list` with the reason and counted in the page's footer beside the store's size, so a
+  board that is not readable never reads as a board that is empty. `done` stays
+  terminal until a `reopen` is designed.
 - **Links are recorded by the tool.** A link names an id, so the page shows what a
   card waits for but does not edit it; `board edit` records it while the card is being
   planned, and `board drop` refuses to strand one.
-- **The board does not know whether a session is alive.** "Idle" means a `doing`
-  card nobody has touched for 30 minutes, not that its process is gone; and the
-  Teammates list reads the bus's records, where `live` is a heartbeat inside ten
-  minutes, `quiet` is a record whose heartbeat has aged, and `no record` means only
-  that the bus holds no record of that label — never that a session is dead. With
-  `session-bus` unloaded, or before any session has joined here, every state reads
-  `—` and the board works exactly as before.
-- **The seat and your terminal are two actors.** The page writes as `team-lead`, so a
-  card a browser claimed is released from the browser or `reclaim`ed from the tool —
-  `board release` in a session is a different actor and is refused. The Team tab marks
-  your own row from the session you are reading in, not from the seat.
-- **A viewer's page is read-only, and the note is the only credential it carries.** A
-  lead who pastes their own URL hands out write access; `/board status` prints the page,
-  not that URL.
-- **Nothing prunes.** A `done` card stays until someone drops it; the page shows
-  how many bytes the store occupies.
-- **A page claim is the seat's claim.** Two browsers on one page are one owner, and every
-  browser that can reach the lead's URL writes as the same seat.
-- **The page stops a minute after its last tab leaves.** Closing the tab to run a
-  command and coming back is fine, and a teammate's watching tab counts as one, so a
-  page nobody is reading does not answer a port for the rest of the session. `/board`
-  starts it again on the same port.
+- **The board knows when a process is gone, not when work is stuck.** The Teammates
+  list reads the bus's records, where `live` is a heartbeat inside ten minutes,
+  `quiet` is a heartbeat that has aged, `gone` is a record whose process is no longer
+  running, and `no record` means only that the bus holds no record of that label. A
+  `gone` owner's cards join **Needs a decision** with the reason that they are free, and a
+  *hung* session reads `live`, so "idle" still means what a card can know — nobody has
+  touched it for 30 minutes — rather than that its owner is stuck. With `session-bus`
+  unloaded, or before any session has joined here, every state reads `—` and the board
+  works exactly as before.
+- **The page is read-only, deliberately.** A browser is not an identity: every page write
+  was made as the seat, and a page `assign` had to record that no handoff was sent. Rather
+  than duplicate the card rules in the client — which had already drifted from
+  `lib/board/rules.ts` — the write path is gone. What a reader loses is editing from the
+  browser; what the product keeps is every one of those verbs as a tool. The one capability
+  with no tool-side twin is assigning **without** messaging the peer: `team`'s `assign`
+  sends a handoff, and nothing else records an owner silently.
+- **A seat can outlive its writes.** A card claimed from the page before this change still
+  names `board:team-lead` as its owner, and `reclaim` is how a lead takes it back.
+- **A lane history is short, and it starts when the field did.** A card keeps the last
+eight lane transitions, dropping the oldest and counting what it dropped, so the record
+is bounded at write time rather than by a janitor — nothing prunes a board. A card
+written before the log existed has no `in lane` row, and `updatedAt` keeps meaning what
+it always meant: when the card was last touched, which is not when it last changed lane.
+- **Nothing prunes itself.** A `done` card stays until someone sets it aside or drops it,
+  an archived card stays until someone drops it, and a dropped card leaves its record
+  behind for the same reason; the page shows how many bytes the board occupies and how
+  many files it could not read, and neither it nor the round counts the archive. Setting
+  history aside is a `board` call, not a threshold nobody stated, so what a read returns
+  never depends on how much has accumulated.
+- **A page claim is a claim nobody cleans up.** A card a page claimed before this change
+  is the seat's until a tool reclaims it; the page itself can no longer add to that pile.
+- **The page stops a minute after its last tab leaves, or two minutes after it starts
+  with no tab at all.** Closing the tab to run a command and coming back is fine, and a
+  teammate's watching tab counts as one. The second grace covers the page a browser never
+  opened — `openInBrowser` swallows a failure, and a port held by a page nobody saw is a
+  port held for the session. Either way `/board` starts it again, on the same port, and
+  prints the address it reopened.
 - **The port is found, or pinned.** With no setting the page prefers a free port in
   4780–5779, falls back to whatever free port the OS gives it if that one is taken, and
   remembers the answer for the session; `board.port` in `bytefly.json` pins it, so a
@@ -234,7 +305,9 @@ pages. A field keeps its keys: `n` inside the note input types an `n`.
   the port that note names rather than serving a second one.
 - **The note is believed only while it answers.** A page that crashed leaves its note
   behind; the next `/board` probes it, takes it over when nothing replies, and attaches to
-  the page that won when two sessions start in the same instant. A note it cannot read at
+  the page that won when two sessions start in the same instant. A clean exit — `/board
+  stop`, or a session shut down normally — clears its own note, so the one that survives
+  is the one a crash left. A note it cannot read at
   all is named with its path — "another session is serving" is only said of a page that was
   seen answering.
 
@@ -245,13 +318,16 @@ pages. A field keeps its keys: `n` inside the note input types an `n`.
   `lib/session-tool.ts`, because a command context cannot call a tool and the request
   therefore travels on `pi.events` — and reads its records otherwise, which is why the
   page works with the bus disabled. A failed join is a clause on the `/board` line, not
-  a failed page. The seat is a different actor from the session that serves it, which is
-  why `/board status` names both.
+  a failed page. The seat is the name the page is served and reported under, and `/board
+  status` says which session is on the team through it.
 - **`plan`**: `board plan` records a plan file's path; the plan extension owns the
-  file. The plan is recorded **after** approval, because plan mode makes mutating
-  tools unavailable.
+  file. The board stays available while planning, and only `list` works: the same tool
+  writes, so its read-only hint cannot say that, and plan mode reads the action in the
+  call instead — `add`, `claim`, or any other verb is refused with the exit guidance.
+  The plan is recorded **after** approval, when the writing verbs work again.
 - **`todo`**: the approved plan's steps are seeded into `todo`. Steps never become
-  cards.
+  cards. A `list` call is a read for the lag reminder too, so reading the board never
+  forces a todo update, while `add` or `claim` counts as work like any other write.
 - **`worktree`**: the store is keyed by the repository's common git directory, so
   every worktree shares one board.
 - **`bytefly`**: the page's port appears as a `board` status chip, and `doctor`
@@ -260,8 +336,26 @@ pages. A field keeps its keys: `n` inside the note input types an `n`.
 
 ## Design notes
 
-- **One JSON file per card**, in `<agentDir>/board/<repo-key>/cards/`. The listing
-  is the index, so a reader needs no cache and no daemon.
+- **One JSON file per card**, in `<agentDir>/board/<repo-key>/cards/`, one per ended
+  card in `ended/`, and one per archived card in `archive/`. The listing is the index, so
+  a reader needs no cache and no daemon.
+- **An id is never reused.** The next id is the highest in `cards/`, `archive/` *or*
+  `ended/` plus one, so a number cannot be handed to a second feature — which is the only
+  thing that lets a note, a handoff, or a link name a card and still mean it. A record
+  is written before its card is removed: a crash between the two leaves a card that
+  still exists with a record explaining it, never a card that is gone unexplained.
+- **An archive is a second pile, not a second state.** `archive` renames a finished
+  card's file into `archive/` and touches nothing inside it, so there is no new field, no
+  schema version, and no lane transition: the record is exactly what it was, and the
+  directory it lies in is the whole fact. That is why `ended/` keeps its one reason — a
+  drop still leaves a record because the card is gone, while an archived card is not gone
+  at all — and why a read by id looks in both piles: a card is where it lies. The
+  decision is explicit because nothing in this board prunes by itself, and because an
+  automatic sweep would make `status: "done"` return something different past a threshold
+  nobody could see. The board, the rollup, and the page read `cards/` alone — the only
+  look at the archive is the directory listing a lane-less `list` counts, so the omission
+  cannot pass for a deleted history — and an archive therefore lowers the board's size
+  and the cost of every read. The ids stay spent because the file name is the id.
 - **Create is exclusive**, by hard-linking a temporary file onto the target name,
   so two adds cannot share an id. **Update** re-reads, re-checks the operation's
   own preconditions, then renames over the old file: an operation means "apply when
@@ -270,33 +364,100 @@ pages. A field keeps its keys: `n` inside the note input types an `n`.
   only when a card's revision, or a teammate's state, mail, or listening flag, moves: a
   heartbeat every ten seconds is not news, and a frame nobody needs costs the page a
   parse.
+- **A query reads what a card says, not just what it is called.** A card's reasoning lives
+  in its notes and in the plan it is executing, so leaving both out of the search made the
+  two fields that hold the argument the two a reader could not find. The order is the
+  answer's weight — title, holder, path hints, plan, notes — and it is one body spliced
+  into the page from `lib/board/card.ts`, so the filter box and `board list query:` cannot
+  disagree about which card a word names.
+- **The record is a ladder, not a paragraph run.** A card's facts are one per row so each
+  can be read and copied alone: the meta line it replaces merged id, updated, and who into
+  one sentence, and named the last writer as though it were the author. The notes are the
+  cargo — they read at body size on a measure, with their attribution under them — and the
+  dialog's body is the only scroll, because a second scrollbar inside a 70vh panel hid most
+  of what a reader opened it for. A long plan path elides on one line with the whole value
+  on its hover title: the plan is the reason to open a card, and it used to shred across
+  three lines of `--dim`.
+- **The walk is over the board as drawn.** `j`/`k` step through the cards the page has
+  boxes for, so a folded Done lane and a filter are both respected; opening a card does not
+  take the keyboard away, it points it at the next record. The position is announced
+  because a title that changes inside an open modal is not.
+- **A class is a symbol, not a string.** The document and the bundle cannot import from
+  each other, so both read `view/names.ts` — the only place a `board-*` class is spelled.
+  A name assembled from a prefix is what made the old contract untestable: it passed on
+  the prefix and could not see the whole name, so a rule with nothing behind it (or a
+  name with no rule) survived until a capture showed it.
+- **The page is given what it prints.** A card arrives with the priority it acts on and
+  the unfinished dependencies that block it (`waits`, as `#2 (doing)`), so the client
+  holds no copy of a rule `lib/board` owns — the copies it did hold had already drifted
+  from the tool's. The one body that cannot cross as data is `plural`, and it crosses as
+  source (`PLURAL_JS`), because a second wording for `1 card` is the same mistake in a
+  smaller place.
+- **An offer is a record, not a reservation.** `team offer` broadcasts a card and then
+  writes `offeredAt` — the moment, and nothing else — because an event leaves nothing
+  behind and a card three sessions ignored read exactly like one nobody had looked at.
+  Every answer clears it: a claim, an assignment, and a release each delete the field, so
+  its presence means the offer is still open. The page reads it in two places and the
+  tool in a third — `offered 1m ago · nobody took it` under the card, `offered 1m ago —
+  nobody took it` as the Team tab's reason, `offered: 1m ago, and nobody took it` in
+  `list <card>` — and the age is `lib/format.ts`'s one rule, handed to the page's bundle
+  as source so the transcript and the page cannot say one age two ways.
+- **`waits on` answers two questions, on purpose.** The page names the *unfinished*
+  dependencies in one line — "why can I not start" — and `board`'s result names every
+  dependency with its lane, including finished ones — "what is this card tied to". Both
+  read `links.ts`, so neither can invent a blocker; the difference is the question, not
+  a drift.
+- **A link is stored once, and read both ways.** `dependsOn` lives on the waiting card
+  alone, so nothing on disk says what a card is holding up; `openDependentsOf` answers
+  it over the board, `list <card>` prints `waited on by N cards: #2 (todo)`, and the
+  dialog has the rung the card's own row cannot. Both skip a finished card, unlike the
+  drop refusal, which keeps every edge: "what is held up" is about work, and "would this
+  drop strand a link" is about the file.
 - **One page is found, not configured.** A note beside the cards carries the port, the
-  seat, and a read-only token; it is created exclusively, so two sessions starting at
+  seat, and the token; it is created exclusively, so two sessions starting at
   once cannot both serve, and the loser attaches to the winner. The alternative —
   a setting that names the lead — was rejected: the role moves, the seat's name does
   not. The port is the one thing a file may pin: `board.port` states where the page
   listens, never who serves it.
-- **The new card is a dialog, not a fixture.** The page opens on the board, and an
-  empty board leaves its own explanation in place rather than covering it with the
-  dialog — the empty state's **Add the first card** is what opens it. A card
-  is something you ask to write. It is the kit's modal, so `Tab` stays inside it and
-  closing returns focus to the button that opened it; a draft survives `Esc` or a
-  backdrop click, and `Cancel` is the one way to throw it away.
+- **The page is a view because a browser is not an identity.** Every page write was made
+  as the seat, so a page `assign` had to write down that nobody had been told, and the
+  client's copy of the card rules drifted from `lib/board/rules.ts` — it offered a drop
+  the server refused. The write path was deleted rather than hidden behind a flag: a
+  disabled verb is still a verb the page has to decide. Deleting it took the composer's
+  dialog, the confirm dialog, the note field, and 60-odd buttons with it.
 - **One edge, stored once.** A link is one id in the waiting card's file and the
-  reverse edge is computed over the board, because a `blockedBy` copy of the same edge
-  is a copy that drifts; the cycle check and the drop rule are what keep the graph
-  whole instead.
+  reverse edge is computed over the board, because a copy of the same edge on the card
+  being waited for is a copy that drifts; the cycle check and the drop rule are what
+  keep the graph whole instead.
 - **A priority is a field, not a lane.** The four lanes are the board's vocabulary and
   a fifth would double the counts and the heads; inside a lane, priority then age is the
   order, and a card says its priority only when it is not the ordinary one.
 - **`edit` leaves an omitted field alone.** It is the one action whose job is "make it
-  say this", so an absent field must mean "not this field" — otherwise the page, which
-  shows no links, would clear every link it saved.
+  say this", so an absent field must mean "not this field" — a caller that sends only a
+  title must not clear the path hints and links it never mentioned.
+- **A lane change is recorded where every transition ends.** `applyOp` decides each
+  transition, but `write()` in `rules.ts` is the one place all of them pass through, so
+  the log is appended there rather than from six operations that would each have to
+  remember it. A write that leaves the lane alone — a note, a plan, an edit, a claim by
+  the holder — appends nothing, because the question the log answers is "how long has
+  this been blocked", and `updatedAt` cannot answer it: filing a note against a blocked
+  card moves that stamp without moving the card.
 - **Rejected:** steps as cards (they flood the board), a shared database (a file per
   card needs no dependency and no lock), an index file (every write maintains it,
   every read can find it stale), drag-and-drop (a lane change is a named `move`), a
-  priority lane (four lanes are the vocabulary), and a reverse `blockedBy` field (two
-  copies of one edge).
+  priority lane (four lanes are the vocabulary), a reverse link field (two copies of
+  one edge), and an automatic archive past some number of finished cards (a threshold
+  nobody stated would decide what a read returns, and nothing else here prunes).
+- **A block says why, and a finished card says with what.** `blocked` exists to ask a
+  person for a decision, so the move into it records the sentence — `blockedBy`, one
+  line — and the page draws that rather than the last note somebody wrote, which was a
+  guess. The reason survives a `release` (the decision is still pending) and is cleared
+  on the way back into `doing` or `done` (a stale sentence reads as a current one).
+  `landed` is the commit `HEAD` resolved to at the move to `done`, recorded because
+  `done` is terminal and nothing later can say which change closed the card. Both
+  fields are optional and neither is required: a card may be blocked with nothing
+  recorded, and one finished before the field, or outside a repository, has no commit
+  to record — finishing never depends on a git read.
 
 ## Files
 
@@ -305,27 +466,27 @@ pages. A field keeps its keys: `n` inside the note input types an `n`.
 | `index.ts` | The factory: gate on `PI_DISABLED_EXTENSIONS`, build the runtime and the page, register both, close on shutdown |
 | `config.ts` | The board's one setting: the port its page is pinned to, clamped, from the `bytefly.json` `board` section |
 | `schema.ts` | The tool's parameters |
-| `types.ts` | The shapes the tool registers and reports: the card an action produced, the cards a list read, the rollup when it was asked for, and the card a refusal carries |
+| `types.ts` | The shapes the tool registers and reports — the actions and the fields each acts on, the card an action produced, the cards a list read, the rollup when it was asked for, and the card a refusal carries |
 | `tools.ts` | Action dispatch and the refusal shape |
-| `input.ts` | A card body as both surfaces read it: the `add` fields normalized once, so the tool and the page cannot disagree |
+| `input.ts` | A card body as the tool reads it: the `add` fields normalized in one place |
 | `format.ts` | The model-facing text |
 | `rows.ts` | The transcript row grammar |
 | `result.ts` | The transcript block |
-| `page.ts` | The page's lifecycle: the port it remembers or is pinned to, the chip that names it, and the three closes — `/board stop`, the idle grace, and shutdown |
+| `page.ts` | The page's lifecycle: the port it remembers or is pinned to, the chip that names it, the three closes (`/board stop`, the idle grace, and shutdown — each taking the note with it), and the probe behind `/board status` |
 | `snapshot.ts` | The page's snapshot: the cards, the bus's records, and the store's size, handed to `buildView` |
-| `writes.ts` | The page's write path: one request to one store call, 422 for a field and 409 for a card somebody else moved |
-| `commands.ts` | `/board`, its three words, and the one line `/board status` prints |
-| `seat.ts` | The seat the page serves as: one name, and an id derived from it, so the page is one actor across restarts |
+| `commands.ts` | `/board`, its three words and their refusals, and the one line `/board status` prints |
+| `seat.ts` | The seat the page is served as: one name, and an id derived from it. The page cannot write, so it is a label now — but the id is still what a card claimed from an older page names |
 | `join.ts` | The board's side of the team: the one request that joins for the user, the label it lands on, and how the outcome reads on a `/board` line |
-| `transport/router.ts` | The routes, what a credential may do, and the guards in front of them |
+| `transport/router.ts` | The five reads — the document, the client script, the theme script, the snapshot, and the frame stream — with the token gate and the guards in front of them |
 | `transport/server.ts` | The loopback listener, the frame push, and the close |
-| `view/page.ts` | The document: an inert shell the client fills |
+| `view/page.ts` | The document: an inert shell the client fills, with no form on it |
 | `view/styles.ts` | The page's `board-*` layout rules |
 | `view/render.ts` | The client's snapshot → DOM renderer: toolbar, lanes, cards, the dialog's contents |
+| `view/names.ts` | The page's class vocabulary: one table the document and the bundle both read, so what the page wears and what its stylesheet draws can be compared |
 | `view/team.ts` | The client's round: the two tables and the Done line |
-| `view/actions.ts` | The client's writes and its two kit dialogs |
-| `view/keys.ts` | The key table, and the bindings that make it true |
-| `view/live.ts` | The client's tabs, new-card dialog, filter, and frame stream |
+| `view/dialog.ts` | The client's card dialog: open one card, close it, and forget it when the kit closes it |
+| `view/keys.ts` | The key table, and the bindings that make it true — including `j`/`k` walking the open dialog through the drawn cards |
+| `view/live.ts` | The client's tabs, filter, and frame stream |
 | `view/client.ts` | The one script served at `/app.js` |
 
 The store, the rules, the rollup, and the snapshot are `lib/board/` — see
@@ -338,7 +499,9 @@ The store, the rules, the rollup, and the snapshot are `lib/board/` — see
 record, the dependency graph, the note a page leaves, the rollup and its text, the card's
 transitions, the store a call opens and the identity it writes as, the files that store
 keeps, and the snapshot, and
-`extensions/board/{input,seat,tools,page,commands,config,extension,transport/router,view/pages}`
+`extensions/board/{input,seat,tools,page,commands,config,extension,transport/router,view/pages,view/behaviour}`
 for the card body, the seat, every action, the page's lifecycle over a real socket (a page
-served, attached to, taken over, and refused to a viewer), the command, the `board.port`
-setting, the factory, the routes, and the document and client bundle.
+served, attached to, and taken over, and a write refused on the wire), the command, the
+`board.port` setting, the factory, the routes, the document and client bundle, and the
+page driven in a browser — a card opened from its title, the filter, the fold, a live
+frame, and the dialog's ladder.