From 19cdd504a6daad1d43ce2f97e1b169881e3a5e3e Mon Sep 17 00:00:00 2001 From: Graeme Foster <80714+GraemeF@users.noreply.github.com> Date: Fri, 25 Sep 2026 14:35:47 +0100 Subject: [PATCH 1/3] docs: lead the README with the everyday view and give arkham's beads the ark prefix The opening made the dangling claim the reason to run bdi, so every description written from it led with the rare case. It now leads with the tree and the live agent on each bead, and the claim with no pane behind it is what else falls out of reading both. The invented arkham project's beads are ark-, so a reader can tell the project from the prefix in arkham:ark-5, and the frame is regenerated from the renamed ground. --- README.md | 18 +++++++++++------- docs/bdi-frame.svg | 42 ++++++++++++++++++++--------------------- docs/configuration.md | 2 +- tools/capture/ground.sh | 38 ++++++++++++++++++------------------- 4 files changed, 52 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 438659e..0458056 100644 --- a/README.md +++ b/README.md @@ -5,17 +5,21 @@ `bdi` is one unblinking eye over every [beads](https://github.com/gastownhall/beads) tracker you point it at. It draws each tracker's work as a tree, and beside every bead an agent has claimed, the live [herdr](https://herdr.dev) pane that -agent is sitting in. +agent is sitting in. Select a bead and the tail of its pane is drawn under the +forest, so what the agent is doing is read off the same screen as the work it +is doing it to. -beads knows the work. herdr knows the agents. Neither has heard of the other, -so neither can tell you that `arkham-5` was claimed by a pane that died on -Tuesday. Something old has opened an eye over both, and it can. +Run a few agents through one backlog and this is the view you wanted. beads +knows the work. herdr knows the agents. Neither has heard of the other. +Something old has opened an eye over both. ![A bdi screen: the arkham project over twelve beads in two trees, each bead drawn with its status glyph and its id in that status's colour, three of them with a green agent marker and pane id beside them, one warning that a bead is claimed with no pane behind it, three panes below that no bead claims, and a band at the foot showing what is on the selected bead's pane.](docs/bdi-frame.svg) -The arkham project is made up. `arkham-5` is the Tuesday case: beads says an -agent claimed it, herdr has no pane for that agent, and only something looking -at both can tell you. +The arkham project is made up. Three of its beads have a live agent beside +them, and the band at the foot is what the selected one's pane is saying. +`ark-5` is what else falls out of watching both at once: beads says an agent +claimed it, herdr has no pane for that agent, and the eye says so. It has seen +a pane die on a Tuesday before. The eye only looks. It never writes to a tracker. Changing the work is still `bd`'s job, and the eye finds this arrangement acceptable. diff --git a/docs/bdi-frame.svg b/docs/bdi-frame.svg index bb00b57..e608b3a 100644 --- a/docs/bdi-frame.svg +++ b/docs/bdi-frame.svg @@ -4,51 +4,51 @@ - - + + ▾ arkham ✓ 4s ago 3/12 3 agents ⚠ 1 -├── ○ arkham-1 Payments move to the new gateway 2/9 +├── ○ ark-1 Payments move to the new gateway 2/9 │ ├── ◐ -arkham-3 -The refund path calls the gateway 0/3 +ark-3 +The refund path calls the gateway 0/3 ◍ wG:p2 · working │ │ ├── ◐ -arkham-5 -Retire the old refund worker +ark-5 +Retire the old refund worker ⚠ claimed · no pane -│ │ └── ○ arkham-4 Backfill the refund ledger +│ │ └── ○ ark-4 Backfill the refund ledger │ ├── ◐ -arkham-7 -Webhook retries are not idempotent +ark-7 +Webhook retries are not idempotent ◍ wG:p4 · working -│ ├── ○ arkham-2 Pin the gateway client version -│ ├─▸ ○ arkham-6 Cut the live keys over 0/2 +│ ├── ○ ark-2 Pin the gateway client version +│ ├─▸ ○ ark-6 Cut the live keys over 0/2 │ ├── ✓ -arkham-8 -Reconcile the settlement report +ark-8 +Reconcile the settlement report │ └── ✓ -arkham-9 -Drop the gateway shim -├── ○ arkham-10 Search returns stale results after an edit 1/3 +ark-9 +Drop the gateway shim +├── ○ ark-10 Search returns stale results after an edit 1/3 │ ├── ◐ -arkham-11 -Invalidate the index on write +ark-11 +Invalidate the index on write ◍ wG:p6 · working │ └── ✓ -arkham-12 -Measure the reindex cost +ark-12 +Measure the reindex cost └── ⚠ 3 unattributed panes ├── ◍ wG:p1 idle diff --git a/docs/configuration.md b/docs/configuration.md index b715b8d..5869061 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -38,7 +38,7 @@ key = "metadata.delivery_pr" render = "⇢ kadath/{}" [roots.explicit] -arkham = ["arkham-1", "arkham-10"] +arkham = ["ark-1", "ark-10"] [[badges]] key = "metadata.delivery_pr" diff --git a/tools/capture/ground.sh b/tools/capture/ground.sh index c56303b..a813a32 100755 --- a/tools/capture/ground.sh +++ b/tools/capture/ground.sh @@ -44,7 +44,7 @@ TOML # The tracker. Twelve beads over two roots: a payments epic whose refund # strand is being worked, and a search bug. Three are closed, three name a -# pane, and arkham-5 names one that no session reports — the drift the caption +# pane, and ark-5 names one that no session reports — the drift the caption # points at. python3 - "$answers" "$arkham" <<'PY' import json, sys @@ -70,23 +70,23 @@ def bead(id, title, status, kind, parent=None, blocked_by=None, pane=None): return row rows = [ - bead("arkham-1", "Payments move to the new gateway", "open", "epic"), - bead("arkham-2", "Pin the gateway client version", "open", "task", "arkham-1"), - bead("arkham-3", "The refund path calls the gateway", "in_progress", "task", - "arkham-1", pane="wG:p2"), - bead("arkham-4", "Backfill the refund ledger", "open", "task", "arkham-3"), - bead("arkham-5", "Retire the old refund worker", "in_progress", "task", - "arkham-3", pane="wG:p9"), - bead("arkham-6", "Cut the live keys over", "open", "task", "arkham-1", - blocked_by="arkham-2"), - bead("arkham-7", "Webhook retries are not idempotent", "in_progress", "bug", - "arkham-1", pane="wG:p4"), - bead("arkham-8", "Reconcile the settlement report", "closed", "task", "arkham-1"), - bead("arkham-9", "Drop the gateway shim", "closed", "task", "arkham-1"), - bead("arkham-10", "Search returns stale results after an edit", "open", "bug"), - bead("arkham-11", "Invalidate the index on write", "in_progress", "task", - "arkham-10", pane="wG:p6"), - bead("arkham-12", "Measure the reindex cost", "closed", "task", "arkham-10"), + bead("ark-1", "Payments move to the new gateway", "open", "epic"), + bead("ark-2", "Pin the gateway client version", "open", "task", "ark-1"), + bead("ark-3", "The refund path calls the gateway", "in_progress", "task", + "ark-1", pane="wG:p2"), + bead("ark-4", "Backfill the refund ledger", "open", "task", "ark-3"), + bead("ark-5", "Retire the old refund worker", "in_progress", "task", + "ark-3", pane="wG:p9"), + bead("ark-6", "Cut the live keys over", "open", "task", "ark-1", + blocked_by="ark-2"), + bead("ark-7", "Webhook retries are not idempotent", "in_progress", "bug", + "ark-1", pane="wG:p4"), + bead("ark-8", "Reconcile the settlement report", "closed", "task", "ark-1"), + bead("ark-9", "Drop the gateway shim", "closed", "task", "ark-1"), + bead("ark-10", "Search returns stale results after an edit", "open", "bug"), + bead("ark-11", "Invalidate the index on write", "in_progress", "task", + "ark-10", pane="wG:p6"), + bead("ark-12", "Measure the reindex cost", "closed", "task", "ark-10"), ] UNFINISHED = "open,in_progress,blocked,deferred" @@ -111,7 +111,7 @@ with open(f"{answers}/where --json", "w") as f: PY # The session. Six panes in the project's directory: the three the beads name, -# and three more working there that no bead claims. arkham-5's pane is not +# and three more working there that no bead claims. ark-5's pane is not # among them, so the claim it carries has nothing behind it. cat >"$ground/herdr-sessions.json" < Date: Fri, 25 Sep 2026 14:37:41 +0100 Subject: [PATCH 2/3] docs: stop saying the arkham project is made up --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0458056..5a0ebc7 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ Something old has opened an eye over both. ![A bdi screen: the arkham project over twelve beads in two trees, each bead drawn with its status glyph and its id in that status's colour, three of them with a green agent marker and pane id beside them, one warning that a bead is claimed with no pane behind it, three panes below that no bead claims, and a band at the foot showing what is on the selected bead's pane.](docs/bdi-frame.svg) -The arkham project is made up. Three of its beads have a live agent beside -them, and the band at the foot is what the selected one's pane is saying. +Three of arkham's beads have a live agent beside them, and the band at the +foot is what the selected one's pane is saying. `ark-5` is what else falls out of watching both at once: beads says an agent claimed it, herdr has no pane for that agent, and the eye says so. It has seen a pane die on a Tuesday before. From ac066bb77029739bdbd1baeac0d79b58795eebe6 Mon Sep 17 00:00:00 2001 From: Graeme Foster <80714+GraemeF@users.noreply.github.com> Date: Fri, 25 Sep 2026 14:40:16 +0100 Subject: [PATCH 3/3] docs: let the README eye have two more dry lines --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5a0ebc7..3dc4a05 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,10 @@ agent is sitting in. Select a bead and the tail of its pane is drawn under the forest, so what the agent is doing is read off the same screen as the work it is doing it to. -Run a few agents through one backlog and this is the view you wanted. beads -knows the work. herdr knows the agents. Neither has heard of the other. -Something old has opened an eye over both. +Run a few agents through one backlog and this is the view you wanted, and +not one the agents were going to volunteer. beads knows the work. herdr knows +the agents. Neither has heard of the other. Something old has opened an eye +over both. ![A bdi screen: the arkham project over twelve beads in two trees, each bead drawn with its status glyph and its id in that status's colour, three of them with a green agent marker and pane id beside them, one warning that a bead is claimed with no pane behind it, three panes below that no bead claims, and a band at the foot showing what is on the selected bead's pane.](docs/bdi-frame.svg) @@ -167,8 +168,8 @@ Hand it over, and let it fold the lines into whatever it already obeys. ## Status -Released, and gazed into daily by the people who wrote it. The design is in -[docs/design.md](docs/design.md). +Released, and gazed into daily by the people who wrote it. It has not yet +gazed back. The design is in [docs/design.md](docs/design.md). Versions are `0.x`, and a breaking change bumps the minor. Pin a tag. `1.0.0` arrives when the shape has settled, not when something breaks.