proctolog 0.1.0

data/docs/manual/bursts.md

@@ -0,0 +1,129 @@
+# Bursts, the route and where things live
+
+## Bursts and pull requests
+
+The desk opens on the burst written last, so one an agent has just made is
+the one waiting for you; `proctolog route` and `proctolog handover` take it too
+when no burst is named. With no burst yet, it opens on the repository's open
+pull requests, at `/pull_requests`. "bursts & PRs" in the pane of every page
+goes there: every burst at its top, the newest first, then the pull requests.
+Its own pane says no burst is open, and lists your bursts with how far each
+one's decisions are. A burst put away says so beside its name in its pane.
+GitHub's stacks come first, each whole from the bottom up, then the pull requests in no
+stack: yours first, then those written for PRoctolog (they have decisions),
+then the newest. Each line says whose it is, what it sits on when that is not
+`main`, and how many decisions it asks.
+
+- "Review alone" opens one pull request in a burst of its own, `pr-1131`.
+- "Review the stack" opens a stack whole, `stack-1055`.
+- Ticking several and "Review the ticked together" makes one burst of them,
+  named as you type or after the first one's branch. A ticked one is a top:
+  it brings the chain of pull requests under it, followed down by base branches.
+
+Each writes its burst among yours, as `proctolog burst new` would. Pressing
+"Review alone" or "Review the stack" again opens the burst it made the first time.
+
+Under "Not opened" come the branches with a description written for them that
+nobody has opened yet, each with "Review alone", and "Review the chain" for one
+that sits on another's branch ([how](unopened.md)).
+
+## When a burst is done
+
+A pull request that merges leaves the route, and goes under "Merged" at its
+foot, the latest first, each with the day it went in and how far your review
+of it got. While the rest of the burst is still at work they are put away
+under that heading: "Show them" lists them, "Put them away" folds them again.
+One closed without merging is still said to have left the burst, as before.
+
+A burst is finished once nothing of it is open or waiting unopened and some of
+it was merged. The desk then puts it away: it no longer opens on it, and the
+open pull requests page counts the finished under its own bursts, "Show it"
+listing them again. A finished burst's page still opens at its address, saying
+so, with everything it merged.
+
+Done with a burst before all of it went in? "Put it away", under its tally,
+puts it away the same way, open pull requests and all, and "Take it out"
+brings it back. The mark is kept beside your marks, not in the burst's file,
+so a burst the repository shares is put away for you alone.
+
+The desk knows a pull request merged once it has read GitHub since: "read
+again", or `r`, when the pane says GitHub moved on.
+
+## Where bursts live
+
+A burst and its scenarios are yours: `proctolog burst new` writes the burst to
+`~/.local/share/proctolog/<owner>/<repo>/bursts/`, beside your marks, and its
+scenarios go in `scenarios/` there under the same name. They hold what is
+yours alone (a sitting's checkout, a handover's paths and rules), so they stay
+out of Git, and every checkout of the repository on this Mac sees them.
+`proctolog burst list` says where each burst the desk opens is kept.
+
+What the repository shares lives in its `.proctolog/`: `app.yml`, how its app
+is run ([how](app.md)); `project.yml`, where its decision records are kept and
+the themes its decisions name ([settings](app.md#settings)); and any burst a
+whole team reviews, in `bursts/` and `scenarios/`. A burst of yours wins over a
+shared one of the same name. `.proctolog/local.yml`, kept out of Git, holds
+what is this machine's alone.
+
+A burst is the body of work the desk opens: the pull requests one effort made,
+taken together. Its file names them, and its name is what `route` and the desk's
+addresses use. A burst file still kept under `.proctolog/reviews/`, where they
+were kept before bursts had their name, opens as well; one in `bursts/` wins over
+one of the same name there. Addresses under `/reviews/` lead to `/bursts/`.
+
+```yaml
+name: The first-run burst
+repository: sartoria-llc/sartoria
+stacks: [1055]                  # GitHub's native stacks, by the number GitHub shows
+tops: [1086, 1083]              # chains the desk follows down by base branches
+pull_requests: [1100]           # pull requests that stand alone
+```
+
+A pull request nobody has opened yet is named by its branch, under `tops` or
+`pull_requests`: `tops: [1086, recovery/emails]`. Once its branch is opened the
+same line names the open pull request.
+
+The route takes a burst in parts: each native stack from the bottom up, by
+GitHub's own order; then each chain followed down from a top; then the pull
+requests that stand alone. A top with nothing under it stands alone too. A
+chain that reaches a stack's member stops there and sits on it, so a change
+lower down is still carried up through it, and its layers wait on that member
+being settled. A pull request shows once: in its stack before a chain, in a
+chain before standing alone. GitHub's stacks are read with a small question of
+their own after the reading; when GitHub cannot answer it, the descriptions
+are still read, and each stack is placed as it was last read.
+
+The head of the route says how the burst moved and where its file and GitHub
+disagree, a line each. A pull request that joined or left since you last
+looked is a line of the route: `x` dismisses it. The desk keeps what you have
+seen in `membership.yml` beside the marks; a reading alone never moves it, a
+dismissal or a handover does. A pull request that left with your choices on it
+stays listed, from those choices, until a handover. A pull request on a
+member's branch that the burst does not hold, a listed stack with nothing
+open, a burst file under both `bursts/` and `reviews/`, and a pull request
+another burst file also holds are each named, with the fix, while they are
+true. The pane at the left counts them.
+
+Marks and films live under `~/.local/share/proctolog/<owner>/<repo>`; cached
+pictures and browser profiles under `~/.cache/proctolog/<owner>/<repo>`.
+Worktrees of the same GitHub repository share that store.
+
+
+The desk reads GitHub once and keeps that reading, also across restarts, under
+the cache's `readings/`. Pages open from it without asking GitHub. The pane at
+the left says when it was read; once a page is shown it asks GitHub one small
+question in the background and names the pull requests that changed since.
+“Read again” there (or `r`) reads everything anew, which takes a few seconds.
+After a reading the desk fetches the burst's pictures in the background, so a
+page that shows forty of them does not wait for them.
+
+For a trial with separate marks and GitHub writes disabled:
+
+```sh
+PROCTOLOG_MARKS=$(mktemp -d) PROCTOLOG_READ_ONLY=1 proctolog serve --port 4041
+```
+
+`PROCTOLOG_READ_ONLY=1` blocks GitHub writes. Scenario buttons can still start
+the project's app and run its recipes; use those only when you want to enter
+that scenario.
+

data/docs/manual/deciding.md

@@ -0,0 +1,89 @@
+# Deciding
+
+On the Decisions page, `j` / `k` (or arrow keys) move between items and `[` /
+`]` between pull requests; Enter opens the decision on its PR's page. `a` leaves
+the implementation as is and moves on. `q` asks a question, `c` suggests a change,
+and `l` leaves it for later with a backlog-task request. Type your text and press
+Ctrl/⌘ + Enter to save and move on. Escape closes the editor while keeping its
+draft; one with nothing typed leaves no draft. `u` undoes the last choice; To
+review, Reviewed and All let you revisit items.
+
+When no decisions match the view, “Show all decisions” brings them back with
+your choices intact. When To review is empty because every decision shown is
+reviewed, the desk says so; the route is available beside that button.
+
+A question can also be asked at once, rather than in the handover. Under the
+question's text, “Ask Claude now” opens a new Claude Code session in the
+Claude app, in the checkout under review, with a prompt typed in: the decision
+quoted with its pull request, branch and head, the pictures it rests on where
+the desk keeps them on this Mac, and your question last, where you can go on
+typing. It asks the session to answer and change nothing. Nothing is sent
+until you send it there. “Copy prompt” copies the same prompt, for a session
+already open or another agent. With decisions selected, the prompt quotes each
+of them. Asking leaves the question here a draft and the decision open: once
+the answer is in, choose on it as on any other, or save the question for the
+handover as well.
+
+The desk keeps these choices and unfinished drafts in `choices.json` beside the
+burst's marks, so the Route, every PR page and any browser on this Mac show the
+same progress. They change no GitHub checkboxes. The browser holds a copy as
+well: it carries a choice across tabs at once and through a moment when the desk
+is not running, then sends it on. When another page saved first (a rule
+withdrawn on the Route, a choice in another browser), the page you are on takes
+in what it saved and makes your step again on top of it, and says so. Choices made before the desk kept them are
+taken in from the browser the first time one of its pages opens, merged like a
+backup. An unrecognized rewritten decision needs review again; unrelated head or
+description changes don't reopen every decision. A choice also records the
+pictures its decision rests on (those it links, a pair as both halves, and any
+in its own line) by their pixels: a retake with other pixels, or a picture
+added or taken away, opens the decision again as “Pictures changed”, with each
+picture as it was beside as it is now. A retake with the same pixels changes
+nothing, and a picture the desk cannot read is “unverified” rather than changed.
+The desk works pixels out as it fetches a picture, and in the background for
+those it already holds, never while a page waits; a picture it has not reached
+yet is “unverified” for that moment. Verification remains bound to
+its recorded head. “data” in the bar holds Back up choices and Restore choices,
+which merges a backup into this burst, with the agent-response import.
+
+“By theme” in the bar lays the same decisions out by the theme each one names
+(`<!-- proctolog:theme errors -->`), in the order of the project's themes, with
+those of no listed theme under “other”; “By pull request” goes back. A theme's
+heading is a stop for `j` / `k`, and `]` jumps between themes. `x` selects the
+decision at hand, or on a heading every decision under it; Escape clears the
+selection. A choice made with decisions selected answers each of them with the
+same words, and `u` takes them all back at once. `b` waits while more than one
+is selected, since an alternative belongs to one decision. Each answer stays its
+own choice: a rewrite that reopens one leaves the others standing. The handover
+carries one line per part, at its lowest pull request, listing the decisions it
+answers and where else the same answer was given.
+
+`R` on a decision you chose on makes that answer a rule, in one line, to keep
+beyond this burst; on one that has a rule already, it edits it. A choice given
+to several decisions at once makes one rule. The rule is a request of its own:
+the handover asks the agent to write it into the project's
+`CLAUDE.md`, or a decision record in a folder `decision_records` in
+`.proctolog/project.yml` names, and to answer under the rule's id with that file
+as evidence. Confirming that answer closes the rule alone, never the choice it
+was made from. The Route lists “Rules made in this burst” at its foot, each a
+line `j` / `k` rest on, with its state: written, sent, answered, confirmed. `c`
+edits the one the cursor is on and `x` withdraws it. Before a handover carries
+a rule, either changes it where it stands; after, the next handover carries a
+replacement, naming the line it replaces, or a request to take the rule out.
+
+Press `e` or “hand over” and the desk writes the handover as a folder beside the
+burst's marks, under `handovers/`: a short brief, `handover.md`, with the rules,
+how to work and how to answer; a file for each pull request with anything handed
+over, under `prs/`, quoting its notes, your choices and its code comments in
+full; `worklist.json`, the same requests as data; and each description as you
+reviewed it, under `descriptions/`. The bar then offers “Open a new session with
+it”: a new Claude Code session in the Claude app, in the checkout under review,
+with one line typed in that asks it to read the brief and carry it out. The same
+line goes to the clipboard, for a session you start yourself. Nothing is sent
+until you send it there. When the desk does not answer, nothing is written, and
+the page says so; your choices stay. The Prompt page shows what `e` would write,
+file by file. “Leave as is”
+adds no change request and approves no merge; existing notes still apply. “Leave
+for later” asks for a task using the project's backlog convention, or a proposed
+task in the report when none exists. Unfinished drafts are included as context,
+never as submitted instructions.
+

data/docs/manual/films.md

@@ -0,0 +1,20 @@
+# Films
+
+Films come from the capture kit, which is owner-only for now.
+
+A film's page reads as its steps: beside it, each step's name over the picture
+it opens on, and a press on one takes the film there. The pictures are taken
+from the film once and kept in the cache by the film's digest; while they are
+made, and on a Mac without `ffmpeg`, the names stand alone. “Fill the window”
+keeps the names only, and a film without chapters has no strip.
+
+Filmed again, a film is a new round. The capture kit's `film.rb` keeps the frame
+each step opened on, as the browser gave it, in a `NAME.steps` folder beside
+the film; the desk records the digest each film had beside the burst's marks
+(`films.yml`) and compares a round's steps with the round before by name. A
+line over the strip says what holds: “No earlier round to compare”, “Not
+compared: ImageMagick missing”, “Not compared: a round without the capture
+script's own frames” (frames decoded from two encodes of the same screens
+differ), or how many steps changed. A changed step's name is lit and says
+“Changed”; one the earlier round had not says “New step”.
+

data/docs/manual/handover.md

@@ -0,0 +1,93 @@
+# Handover and the next pass
+
+Press `d` on a PR page to open its code in the installed Diffle: this layer only,
+what GitHub's Files changed shows, so a PR high in a stack does not bring every
+layer below it. The Code comments page also offers “Whole PR against main”,
+cumulative for a stack.
+PRoctolog uses a private checkout under the burst's store, with a pinned base
+and head. Sartoria's checkout stays untouched. When GitHub has moved the PR's
+head since the desk read it, `d` reads GitHub again first, a few seconds, so
+Diffle opens the code the page then shows. Diffle's `c` comments, `v` marks
+a file viewed, and `?` lists the keys. The PR's Code comments page shows the
+threads and lets you stop its server. The outline of the PR's page counts the
+comments nobody resolved and the files viewed, and counts again whenever you
+come back to its tab, so closing Diffle leaves the count true.
+
+Handing over collects current code comments and responses. Diffle
+threads join the same worklist as description notes and browser choices,
+including their path, line range, quoted code and reviewed head.
+
+## Your agent can take it itself
+
+Tell your agent to check your PRoctolog comments. The `proctolog-handover`
+skill has it run `proctolog handover` in the repository's checkout, which
+writes the same folder `e` would, from what the desk keeps, with no page open,
+and tells the agent where the brief is. `--part` takes one part of the burst.
+
+A handover need not wait for the end of a review. What you decided so far
+goes; what you haven't reviewed yet stays out, and the brief asks the agent to
+leave it exactly as it is, since you may be reading it while it works. Choose
+on, and the next handover, `e` or the agent checking again, carries only what
+you decided since, with your replies to what came back.
+
+What a handover took stays with its agent until an answer comes back: a later
+handover leaves it out, so two agents never do the same work, and Returned work
+lists it under "With an agent". If that agent is gone, "Hand them over again"
+there, or `proctolog handover --again`, puts it in the next handover.
+
+## Answers
+
+Each handover records a batch. Its brief tells the agent to return one
+`proctolog-response/v1` JSON file under the burst's `responses/` folder, or to
+give you that file to import. The [schema](../../public/schemas/proctolog-response-v1.json)
+defines answers, completed changes, researched explanations with evidence,
+verification, backlog references, blockers and questions with recommendations.
+Refresh loads matching files; unrelated batches or invented request ids are
+refused. An agent that writes its answer again, after a restack or a fix, gives
+it a new time: the desk shows the new version and keeps the one before under
+“Earlier replies and responses”, and a reply of yours stays with the version
+you read. Backups include the batch history needed to match responses.
+
+On the PR page, press `v` for Returned work. Confirm a result to close its request. Ask a follow-up, request a
+correction or leave it for later to continue that same request. Returned work
+is read like the rest of the page ([reading](reading.md)): `↑` / `↓` go down it
+block by block, `→` / `←` open and close its folds, `[` / `]` go from response
+to response, and Esc goes back to where `v` was pressed. Wherever you are in a
+response, `a` confirms it, `q` replies or asks, `c` requests a correction, and
+`l` defers. Ctrl/⌘ + Enter saves the reply; `e` exports the next pass.
+
+What the agent wrote is drawn as GitHub draws markdown. Under Evidence, the
+pictures it names are shown, read from where they are on this Mac: two named
+alike but for `before` and `after` stand side by side as one, and Space looks
+at one closely, a pair compared each way as the description's are. The desk
+shows only pictures a response names. The files and pages it names follow, and
+Verification says how many of the agent's checks passed, a failed one reversed.
+You can also ask a new question outside the PR items explicitly.
+“Review changes” (`d` while focused on a response) compares the exact head you
+reviewed with the returned committed head, even before publication. “Whole PR
+against main” is available alongside it. A correction's next pass starts from
+the previously returned head. No code changes means no extra diff to review.
+Returned work opens with one line of what is waiting, then what asks something
+of you: questions, results to confirm or push back on, requests reopened for the
+next pass. Everything else is folded under “Background”: requests an agent still
+holds, closed ones, drafts kept from earlier wording, and “Description changes
+since this handover”, which draws the paragraphs added or rewritten in the
+current GitHub description, pictures included, against the copy the desk kept
+when it wrote the handover. “Ask or request something else” sits at the foot.
+“What you reviewed” recalls the original decision.
+Prompt remains available for the combined review across all PRs.
+
+The next handover includes only unresolved requests that need the agent. Items
+waiting for your answer stay out until you reply, and items still with an
+agent until it answers. Confirmed work stays closed;
+reimporting a response does not reopen it. Optional follow-ups are shown
+separately and add no work unless you choose to ask for it. Closing review
+requests doesn't waive current-head verification, scenarios, dependency or
+rollout checks, or your final merge and release approval.
+Choices follow their stable reference, or exact words for older descriptions,
+when decisions move. Earlier wording and
+unfinished drafts are retained for recovery; a reply never jumps to a different
+decision just because its position changed. Requests from PRs that leave the
+open burst, and choices replaced by new ones, stay in history instead of
+creating another pass.
+

data/docs/manual/pr-format.md

@@ -0,0 +1,75 @@
+# Writing a PR the desk reads
+
+## Check a description
+
+```sh
+proctolog check 1062               # an open pull request, as GitHub holds it now
+proctolog check --file body.md     # a description before it is published
+proctolog themes                   # the themes a decision may name, and what each means
+```
+
+`check` reads a description with the desk's own parser and its own picture
+names, and says on which line what would keep the desk from reading it well
+(a fault): no decisions section, a decision with no bold lead, running onto a
+second line, with no `Alternative:` or no theme the project lists, a picture
+link that names no uploaded picture or several, half a before/after pair, a
+reference kept twice. More than five blocking decisions is a warning. It
+exits 0 with no faults, 1 with faults, and 2 when `gh` could not be asked.
+`--file` has GitHub render the file first, through its Markdown endpoint,
+which only renders and keeps nothing.
+
+## PR format
+
+The skill in `skills/proctolog-pr-writing/` teaches an agent this format, with a
+whole example in its `references/example-description.md`. `proctolog install`
+links it into `~/.claude/skills/` and `~/.agents/skills/`. Keep the project's
+template (Summary, Changes, Verification) and add:
+
+```markdown
+## How to test locally
+
+**A named scenario.**
+1. Do this. Expect that.
+
+## Decisions for the owner
+
+- [ ] **The implementation does this.** Why it was chosen and who it affects. See [phone wrapping](#screenshot-card-phone). Alternative: another behavior, with its cost. <!-- proctolog:theme fit -->
+
+### Non-blocking
+
+- [ ] **A choice a default settles.** Why. Alternative: the other default. <!-- proctolog:theme copy -->
+```
+
+The parser needs these exact second-level headings, top-level one-line task
+items, and `Alternative:` for the alternative. Give each item a distinct bold
+lead. Blocking decisions come first, five at most; those a default can settle
+go under `### Non-blocking`. A description with no such heading has every
+decision blocking. Each decision ends with its theme,
+`<!-- proctolog:theme NAME -->`, one of those `proctolog themes` prints; the
+marker is hidden on GitHub and is no part of the decision's words. When
+rewriting an existing decision, retain its handover's `source.decision.key`
+after the lead: `<!-- proctolog:decision KEY -->`. These invisible references
+keep a settled choice settled when its prose changes. Omit resolved decisions
+from the active list if appropriate; their review history is retained. Never
+reuse a reference for a new choice. Scenario registries
+refer to the bold scenario headings above numbered steps.
+
+For a decision about display or rendering, the PR writer chooses which images
+show the point and links to them in that decision: `[a useful label](#screenshot-image-name)`.
+`image-name` must match the screenshot's exact, unique `alt` text in this PR,
+for example `<img ... alt="card-phone">` above. Put the link beside the claim
+it illustrates, before `Alternative:`, and use several links when useful.
+PRoctolog resolves these references to its cached images and previews them
+inline with their captions. Missing or ambiguous names are reported in the
+preview. Keep names stable when retaking an image; update references when
+renaming it. References are optional for decisions that need no visual proof.
+
+List real choices here. Put test gaps in Verification under “Not verified”, and
+implementation facts in Changes. Keep the description about the final change
+against `main`, not a review-iteration diary. A GitHub checkbox is legacy review data; the
+browser's “Leave as is” choice means no new implementation change. It is not
+proof of verification or permission to merge. Descriptions written before the
+grades need no rewrite to use the queue: all their decisions count as blocking.
+`proctolog check --file body.md` says whether a description reads well before
+it is published.
+

data/docs/manual/reading.md

@@ -0,0 +1,233 @@
+# Reading a PR by keyboard
+
+Every page with keys has a bar at its foot that names the few that matter where
+you are (Reading, Deciding 3 of 21, Writing, Returned work). `?` docks the list
+of them all above that bar, where it stays while you work, from page to page,
+until `?` puts it away. A key that can do nothing says why in a line above
+the bar.
+
+Below a PR's title, “review decisions” starts with the first blocking decision
+still to review; “returned work” appears when an answer waits for you. The same
+row offers the route, the previous and next PR, and the next one to review.
+Their keys stay the same: `f`, `v`, `h`, `K`, `J` and `N`. This row gives way
+while you decide; Escape brings the reading back.
+
+Each of those lines, and each line a page opens with after a form, is kept.
+`m`, or “messages” at the right of the bar, lists them newest first, each with
+its time and the page it was said on, a link back to that page when it was
+another; `m` or Escape puts the list away. The list is this browser's and
+keeps the last eighty.
+
+A pull request's page has a cursor: a `>` in the gutter at the block the reading
+rests on. Only that block carries keys, in the margin beside it, and they lead
+the docked list as “This block”. An outline at the right names the page's
+sections, marks the one the cursor is in, and counts only what waits for you;
+a press there goes to that section. Below them, Code comments counts the
+Diffle comments nobody resolved, and Files viewed how far you got in the code
+last opened; both lead to the Code comments page. In a window under about
+1,300 pixels wide the outline gives way to the reading.
+
+Under the outline, Try it runs the app for a pull request that has scenarios.
+It first says what a scenario needs before it tries this pull request, a bead
+to each as Standing has them: a checkout that can run the app, with this pull
+request's latest commit in it, and the server up on it. What is still open is
+white. When the checkout falls short, "How to fix it" opens a popup that says
+what is wrong in plain words and gives the commands that make a checkout of
+this pull request which can run, and the lines that point the burst's sitting
+at it, each with a button that copies it. Under the beads is a button for each
+scenario, named for it, which wakes once the server is up: it makes the
+scenario's state, signs its member in and opens a browser on the page where its
+steps begin. A press on start or stop leaves the page where it is, and the
+server goes on in the background until it is stopped. When it has stopped
+without the desk, the end of its log shows while the pointer is on that line.
+`t` goes to Try it. In a narrower window it waits at the foot of the page.
+
+On the Route, `j` / `k` select a PR and Enter opens it. Each line shows how many
+of its decisions you have reviewed, and whose it is when it is not yours; the
+line the cursor is on opens out with the rest: its layer, what is open, its
+pictures and words, and when it last changed. `N` opens the next PR with
+decisions left. Clicking a title opens that PR. Clicking elsewhere on a row,
+or tabbing to one of its links, selects it and shows its actions. In a narrow
+window those actions wrap under the selected row. On
+a PR's page, `j` / `k` or the up/down arrows move through headings, description
+blocks, pictures, decisions and returned work, as below. `[` / `]` jump between
+sections; Enter or Right opens a section, Left closes it. Home / End reach the
+first / last item. Tab / Shift+Tab reach links, buttons and fields. `J` / `K` open the
+next / previous PR, `N` the next one with decisions to review, and `h` returns
+to the Route. `G`, on the Route or a PR's page, opens the PR on GitHub in a tab
+of its own.
+
+How the keys move is the same everywhere on a PR's page:
+
+- `↓` and `j` are one key, `↑` and `k` the other. They go to the next block
+  the page shows, or the one before, in the order it is read from the top,
+  returned work included. Nothing shown is passed over: a fold that is shut is
+  one block, its heading, and a block taller than the window is read a
+  screenful at a time before the next. They stop at the first and the last
+  block, and never jump elsewhere.
+- `>` in the margin marks the block, with a line under it as far down as the
+  block goes; the keys of that block stand beside it, and the bar at the foot
+  names where you are: Reading, Returned work 2 of 4, Deciding 3 of 21.
+- `←` and `→` go sideways. On a fold they close and open it. While deciding,
+  the decisions stand in a row of beads, and they go along it.
+- `[` and `]` go from heading to heading: the sections, Returned work, and each
+  response in it.
+- Where one thing fills the page, a decision being decided, `↑` `↓` and `j`
+  `k` scroll it. In a picture looked at closely the arrows move the picture.
+- Esc goes back one step: out of a picture to the block it was opened from,
+  out of a decision to the page, out of returned work to where `v` was pressed.
+
+The page opens on the description. After it come the sections of its review,
+reached by the same keys: Standing (what must be met, and Good to go),
+Scenarios (each one's steps, and what you saw of it), Connections, Notes and
+Handover. A picture a step names opens at a press, as Space opens one. With the cursor on the title, what
+can be done with the whole pull request stands beside it.
+
+A burst can be taken a part at a time. On the Route, `p` shows the part the
+cursor is in alone; every page you go to from there keeps that focus, the
+pane says which part it is, and `P` brings the whole burst back from any page.
+Focused, the route, the decisions, the scenarios and the handover hold that
+part alone, `J`, `K` and `N` stay within it, and the pane counts the decisions
+left in the part against the burst. A pull request opened from outside the
+part stands apart in the pane. A handover of one part says the rest of the
+burst is outside it, and names the chains that sit on it, so a change to it is
+carried up through them.
+
+A pane at the left of every page lists the route, each PR with its count
+(`x` all reviewed, `~` some, no mark for none yet, `-` when it has none), and
+marks the one you are on. A `*` before a title means GitHub moved on since the
+desk read it. Hold the pointer on a row and a card beside the pane gives its
+title in full, says each of its marks in words, and links to it on GitHub
+(and to “read again” when it moved).
+
+The desk has no colour. What you are on and what waits for you is white and
+bold; what is settled is grey. A bead says the same of anything that is
+counted: hollow while it waits, solid once it is settled, ringed where you are.
+
+Reading passes over the decisions like any other block: `j` / `k` and the arrows
+never open one. Enter on a decision, a click on it, or one of its choice keys
+opens it to decide.
+
+Space on a picture, or on a decision that links pictures, opens it over the
+whole window. The wheel, a pinch, `+` and `-` zoom; a drag or the arrows move
+it; `0` fits it and `1` shows its own size; `[` / `]` go through the other
+pictures. A click there marks a point and Shift with a drag marks a region: the
+place stays on the picture, everything around it dimmed, and the note's form
+opens beside it, with the viewer as it was, zoom and all. ⌘ Enter saves the
+note and leaves it drawn there for the next; Escape puts the form away while it
+is empty. The picture's notes are drawn on it, and a click on one opens it
+beside its box with its words: ⌘ Enter saves it written over, in the same
+place, and Withdraw takes it back off the picture. Escape puts it away while
+nothing in it is changed. Escape, or the ✕ at the top
+right, closes the viewer and nothing else: you are back on the block, or the
+decision, you opened it from. Once it closes, the page comes back at the last
+note written; while deciding, it stays on the decision, and the note shows the
+next time the page loads.
+
+Two pictures named `NAME-before` and `NAME-after` are one picture of a change:
+the description shows them side by side under one name, and a decision links
+them as `#screenshot-NAME`. In the viewer, `s` shows them side by side, `w`
+swipes (the after picture over the before, up to a divider that a drag or the
+arrows move), `b` blinks from one to the other at each press, `o` lays the
+after picture half seen through over the before, and `d` lights only what
+differs. `n` goes from one changed region to the next, each outlined on the
+pictures. The caption says “Comparing…” until the regions are found, then how
+many there are, “Identical”, “Different sizes: compared from the top left”, or
+“Regions need ImageMagick” on a Mac without it. A mark goes on the half it is
+made on side by side, and on the one showing in blink; swipe, onion skin and
+difference take none. Comparisons are kept in the cache, by the pictures'
+pixels.
+
+A run of pictures that no decision or other line of the description links
+folds where it stood, with its captions, into one “More pictures (N)”, opened
+like a section with Enter. For Sartoria's capture kit,
+`integrations/sartoria/compare.rb` (required after `kit.rb`) shoots a screen
+`before "NAME"` and `after "NAME"` and `Capture.compare` compares the pairs
+before anything is uploaded: it drops a pair whose pixels match, groups pairs
+of one size that show the same change, and writes `compare.json` listing what
+to upload.
+
+Press `f` to jump straight to the first unreviewed decision; on Standing's
+"Its decisions are reviewed", Enter does the same. Deciding shows the
+decisions alone, a line each, and the one at hand opened out: its words, its
+choices as a menu, each beside its key, and its linked screenshots under them.
+A row of beads above shows which of the PR's decisions are done and which one
+this is; `←` / `→` move along them, `↑` / `↓` and `j` / `k` scroll the one
+shown, and Escape brings the whole page back.
+Focusing a decision
+activates its actions: `a` leaves it as is, `q` asks a question, `c` suggests a
+change, and `l` leaves it for later. Saving advances to the next unreviewed
+decision on this PR. Ctrl/⌘ + Enter saves text; Escape closes a draft without
+discarding it, then Escape returns to the section heading. `u` undoes the last
+choice, wherever you are on the page. Once every blocking decision is
+reviewed, the page shows where the decisions end: what is reviewed and how many
+non-blocking still wait; what to do next, where `g` marks the PR good to go,
+`N` opens the next PR with decisions to review, `e` hands over and
+`h` goes back to the Route; and every decision on a line under its grade, with
+what you chose on it or what holds it. Each grade says what it asks of you: a
+blocking decision needs your answer before the work goes on, and a non-blocking
+one has a sensible default, so that left as is, what the agent built stands.
+`j` / `k` (or the arrows) go down the lines. `→` unfolds a line to its
+decision's own words and your choice in full, `←` folds it again, and a click
+does either; a screenshot its words name opens the decision, where its
+pictures are. Enter or a choice's key opens the decision of the line it rests
+on; Escape from that decision comes back to
+its line, and Escape from the lines brings the whole page back. Under the whole
+page the panel keeps only what to do next. `g` and `e` work from anywhere on
+the page outside an editor. No separate decisions page is needed.
+“To review” shows only decisions still needing a choice: one you chose on, or
+one already ticked on GitHub, is not asked again. “All decisions” lets you
+revisit them; their original wording stays in review history.
+
+A description may grade its decisions: those under a `### Non-blocking`
+heading are non-blocking, the rest blocking. The non-blocking fold away under
+that heading, which the reading rests on like any other; Enter or Right opens
+it. Deciding goes through the blocking decisions alone: `f`, `N` and "Deciding
+3 of 8" pass over the non-blocking, which still count toward "its decisions
+are reviewed". `A` (on that heading, on the panel after the last blocking
+decision, or anywhere on the page) leaves every non-blocking decision that
+waits for nothing as it is, in one gesture: it passes over one you starred,
+one the burst file names, one with a draft, a question or an answer, and says
+which and why. The panel says it before you press: “leave 10 as is · 2 wait
+for you: 1 starred, 1 drafted”, and each of those two lines says what holds it. `u` takes the whole gesture back. A decision left that way opens
+again, saying why, if a rewrite promotes it to blocking or changes its words;
+one you left by itself keeps the usual rules. The handover gives each pull
+request's gesture one line. The Route and the Decisions page count the grades
+apart, "3 blocking · 12 non-blocking", and say "over five" where there are
+more than five blocking.
+
+`b` (Use alternative) records the decision's exact suggested alternative as a
+change request. It opens one line under the decision for a note, where an
+alternative names more than one route and you say which you mean; Enter saves
+and moves on, with the line empty or not, and the note follows the alternative
+as “My note: …”. `b` again on that decision shows the note to change. It uses
+the same saved choices, undo, backups and handover as a change you type. It requests an
+implementation change; it does not approve a merge or mark verification done.
+The button appears only when the writer supplied an alternative other than
+“none”.
+
+`s` opens or closes a decision's referenced screenshots beside it. Clicking a
+screenshot reference also opens that preview. Your decision keeps focus;
+Escape closes the preview, and moving to another decision closes it too.
+
+`n` opens a note on the focused block or whole picture (on a decision too), and
+`w` opens a note on the whole PR. `c` always means “suggest a change” on a
+decision. Drawing a particular picture region still uses the pointer. Shortcuts
+leave typing and browser modifier keys alone.
+
+
+A `#` and a number, typed into any box of the desk (a note, an answer to a
+decision, a rule), looks among every pull request of the repository, open,
+merged or closed, and lists those it may be just under the `#`: the one with
+that very number first, then those whose number begins so, newest first. `↑`
+/ `↓` (or Ctrl+N / Ctrl+P) choose, and Tab or Enter puts the one chosen in place
+of what you typed. You may not mean a pull request at all: Esc puts the list
+away and leaves the `#` as typed, and so does writing on past it or leaving it
+behind. That Esc is the list's alone, so the draft, form or dialog around the
+box stays open; with no list showing, Esc does what it always did. The first `#`
+on a repository the desk has never read takes some seconds while it reads the
+whole history, which it then keeps.
+
+Wherever the desk shows what you or the agent wrote, a `#` that names a pull
+request is a link to it with its title beside, and its state when it is no
+longer open. One of the burst's own goes to its page here; any other to GitHub.