proctolog 0.1.1 → 0.3.0

data/bin/proctolog

@@ -17,6 +17,7 @@ end
 require_relative "../config/application"
 require_relative "../app/models/proctolog/project"
 require "rbconfig"
+require "socket"
 require "thor"
 
 module Proctolog
@@ -26,9 +27,15 @@ module Proctolog
 
     # A command prints what it was asked for and nothing else, and asks
     # 1Password for no keys. The desk's log, with what Grouse says at boot it
-    # is missing, and the keys are for `serve`, which says so in the block.
-    def boot!
+    # is missing, and the keys are for the owner's `serve`, which says so in
+    # the block. A trial desk serves without them.
+    def boot!(&)
       Project.current = Project.discover(options[:project] || Dir.pwd)
+      boot_desk!(&)
+    end
+
+    # The desk alone, for a command of this Mac's rather than a checkout's.
+    def boot_desk!
       Desk.config.log_level = :error
       Desk.config.x.reads_keys = false
       yield Desk.config if block_given?
@@ -128,6 +135,62 @@ module Proctolog
     def tree = super
   end
 
+  class ShareCommands < Thor
+    include Booting
+
+    def self.exit_on_failure? = true
+
+    class_option :port, type: :numeric, default: 4040, aliases: "-p", desc: "The port of the desk"
+    default_command :start
+
+    desc "start", "Share the desk through Tailscale or ngrok, and print its address"
+    long_desc <<~TEXT
+      Lets you reach the desk on this Mac from your phone, or a computer elsewhere. Through Tailscale, only
+      the devices signed in to your tailnet reach it, at this Mac's name there, and nothing goes on the
+      internet. Through ngrok, it is on the internet behind ngrok's sign-in with Google, which lets in only
+      the addresses --allow names, your Git email when none is named. Without --via, it shares the way named
+      last, or the first one ready, Tailscale first. The share stays open until `proctolog share stop`, the
+      desk running or not; one already open is only printed. `proctolog share status` says what each way
+      needs first.
+    TEXT
+    option :via, type: :string, enum: %w[tailscale ngrok], desc: "The way to share it, remembered for the next time"
+    option :allow, type: :string, repeatable: true, desc: "An email that may sign in through ngrok, in place of your Git email"
+    def start
+      boot_desk!
+      abort "No desk answers on :#{port}. Start one with the share: proctolog serve --share#{port_option}" unless Localhost.answers?(port, within: 1)
+      puts Share.open(port, via: options[:via], allow: options[:allow])
+      puts "Stop it with: proctolog share stop#{port_option}"
+    rescue Share::Refused => e
+      abort e.message
+    end
+
+    desc "stop", "Stop sharing the desk: it is only on this Mac again"
+    def stop
+      boot_desk!
+      share = Share.at(port)
+      share&.close
+      puts share ? "The desk on :#{port} is only on this Mac again." : "The desk on :#{port} was not shared."
+    rescue Share::Refused => e
+      abort e.message
+    end
+
+    desc "status", "Say whether the desk is shared, and what Tailscale and ngrok each need to share it"
+    def status
+      boot_desk!
+      puts Share.at(port) || "The desk on :#{port} is only on this Mac, at #{Desk.address(port)}."
+      Share.ways.each { puts it.ready? ? "ok  #{it.name}: ready, and #{it.who}" : "--  #{it.unready}" }
+    end
+
+    desc "tree", "Print a tree of all available commands", hide: true
+    def tree = super
+
+    no_commands do
+      def port = options[:port]
+
+      def port_option = (" --port #{port}" unless port == 4040)
+    end
+  end
+
   class CLI < Thor
     include Booting
 
@@ -135,28 +198,43 @@ module Proctolog
 
     class_option :project, type: :string, aliases: "-C", desc: "The Git checkout whose bursts to open"
 
+    no_commands do
+      # Bare, proctolog shows its commands under the one to start with.
+      def help(command = nil, subcommand = false)
+        puts "New here? proctolog setup takes you to the desk, a step at a time.", "" unless command
+        super
+      end
+    end
+
     desc "burst SUBCOMMAND", "Start a burst of your own, or list the bursts there are"
     subcommand "burst", BurstCommands
 
     desc "unopened SUBCOMMAND", "List the pull requests nobody has opened yet, or say where one is written"
     subcommand "unopened", UnopenedCommands
 
-    desc "serve", "Open the desk on http://localhost:4040"
+    desc "share SUBCOMMAND", "Share the desk with your phone or another computer, through Tailscale or ngrok"
+    subcommand "share", ShareCommands
+
+    desc "serve", "Open the desk on http://proctolog.localhost:4040"
     option :port, type: :numeric, default: 4040, aliases: "-p", desc: "The port to listen on"
+    option :share, type: :boolean, default: false, desc: "Share it too, as `proctolog share` does"
     def serve
       boot! do |config|
         config.log_level = :warn
-        config.x.reads_keys = true
+        config.x.reads_keys = !Desk.trial?
+        config.x.port = options[:port]
       end
       require "rackup"
       Release.newer&.then { puts it.news }
       Housekeeping.start
-      Rackup::Handler.get("puma").run(Desk, Host: "localhost", Port: options[:port])
+      Rackup::Handler.get("puma").run(Desk, Host: "localhost", Port: options[:port]) do |launcher|
+        launcher.events.after_booted { opened }
+      end
     rescue Errno::EADDRINUSE
-      abort "Port #{options[:port]} is taken. If that is the desk, it is open at http://localhost:#{options[:port]}; " \
+      abort "Port #{options[:port]} is taken. If that is the desk, it is open at #{Desk.address(options[:port])}; " \
             "for a second one: proctolog serve --port #{options[:port] + 1}"
     rescue Project::Missing => e
-      abort e.message
+      abort "#{e.message} New here? proctolog setup takes you to the desk, a step at a time."
     end
 
     desc "route [BURST]", "Print the order to take a burst in"
@@ -241,25 +319,20 @@ module Proctolog
     map %w[-v --version] => :version
     def version = puts("PRoctolog #{VERSION}")
 
-    desc "install", "Link zsh's completion and the agent skills to this PRoctolog"
+    desc "install", "Another name for setup: link this PRoctolog, then set it up a step at a time"
     long_desc <<~TEXT
-      Links zsh's completion into ~/.zsh/completions and the agent skills into ~/.claude/skills and
-      ~/.agents/skills, from wherever this PRoctolog lives: the gem, or the checkout, which also gets its
-      launcher in ~/.local/bin. Leaves anything of the same name that is not PRoctolog's as it is.
-      `update` runs it for the version it installs.
+      Does what `proctolog setup` does, whichever of the two you remember: links the proctolog command, zsh's
+      completion and the agent skills to this PRoctolog, then takes you through the rest a step at a time.
+      `proctolog help setup` says how.
     TEXT
-    def install
-      puts Installation.here.install
-    rescue Installation::Refused => e
-      abort e.message
-    end
+    def install = setup
 
     desc "update", "Install the latest PRoctolog, and link to it"
     long_desc <<~TEXT
       Asks RubyGems for the latest PRoctolog and, when it is newer than this one, installs it the way this one
       was: with `rv tool install` for one rvx runs, with `gem install` otherwise. A checkout is pulled
       forward instead, when it is clean and on origin's own branch, and its bundle installed. Then runs the
-      new one's `install`. A desk open now runs on as it was: restart it to run the new one.
+      new one's `setup`, which links it. A desk open now runs on as it was: restart it to run the new one.
     TEXT
     def update
       installation = Installation.here
@@ -275,13 +348,22 @@ module Proctolog
     end
 
     no_commands do
+      # Once the desk listens: where it is, and where else, when it is shared.
+      # A share that cannot open leaves the desk open on this Mac.
+      def opened
+        puts "The desk is open at #{Desk.address}."
+        puts(options[:share] ? Share.open(Desk.port) : Share.at(Desk.port) || return)
+      rescue Share::Refused => e
+        warn "The desk is not shared. #{e.message}"
+      end
+
       # rv runs as the shell would, not on the Ruby and gems it gave this one.
       def take_with_rv(latest)
         Outside.run do |environment|
           system(environment, "rv", "tool", "install", "proctolog@#{latest}", "--gem-server", "#{Release.server}/", exception: true)
           puts taken(latest)
           # rvx runs the newest it holds, which is now this one; rv 0.7 runs no proctolog@VERSION.
-          exec(environment, "rvx", "--no-install", "proctolog", "install")
+          exec(environment.merge(Installation.updating_from(VERSION)), "rvx", "--no-install", "proctolog", "setup")
         end
       end
 
@@ -290,17 +372,20 @@ module Proctolog
         system(RbConfig.ruby, File.join(RbConfig::CONFIG["bindir"], "gem"), "install", "proctolog", "--version", latest.version, "--clear-sources", "--source", Release.server, exception: true)
         puts taken(latest)
         # RubyGems' launcher takes the version to run as its first word.
-        exec(RbConfig.ruby, File.join(Gem.bindir, "proctolog"), "_#{latest}_", "install")
+        exec(Installation.updating_from(VERSION), RbConfig.ruby, File.join(Gem.bindir, "proctolog"), "_#{latest}_", "setup")
       end
 
       # The checkout's own bundle, on this Ruby, as bin/proctolog runs it.
+      # Nothing to take when origin has nothing newer, as for a gem.
       def take_with_git(installation)
-        puts installation.pull
+        pull = installation.pull
+        return puts("PRoctolog #{VERSION} in #{installation.root} is the latest: origin has nothing newer.") unless pull.moved?
+
         Bundler.with_unbundled_env do
           system(RbConfig.ruby, Gem.bin_path("bundler", "bundle"), "install", "--quiet", chdir: installation.root.to_s, exception: true)
         end
         puts "Pulled #{installation.root} forward. Restart the desk to run it."
-        exec(RbConfig.ruby, installation.root.join("bin/install").to_s)
+        exec(Installation.updating_from(VERSION), RbConfig.ruby, installation.root.join("bin/install").to_s)
       end
 
       def taken(latest) = "Installed PRoctolog #{latest}. Restart the desk to run it: one open now still runs #{Release.running}."
@@ -316,13 +401,55 @@ module Proctolog
       Exits 0 when every need is met, 1 when one is not.
     TEXT
     def doctor
-      project = begin
-        Project.current = Project.discover(options[:project] || Dir.pwd)
+      project = discovered
+      boot_desk!
+      Doctor.new(project).tap { puts it }.then { exit(it.fine? ? 0 : 1) }
+    end
+
+    desc "setup", "Set PRoctolog up, a step at a time, from wherever you are to an open desk"
+    long_desc <<~TEXT
+      First links the proctolog command, zsh's completion and the agent skills to this PRoctolog: from the gem,
+      or the checkout, which also gets its launcher in ~/.local/bin. Anything of the same name that is not
+      PRoctolog's stays as it is. Then takes doctor's checks in the order you meet them: gh signed in, the
+      checkout you review and its GitHub repository, a first burst, what turns features on, sharing the desk
+      with your phone, and the desk itself. Each step says why it matters and what to do; Enter checks it again
+      once you have, and it is stamped DONE when it is met, or LATER when you leave it. Outside a checkout, its
+      step asks for the folder of one. Of anyone else's, nothing is installed for you. The last step opens the
+      desk with `proctolog serve`. `install` is another name for it, and `update` runs it for the version it
+      installs, which then only links and says what is new.
+
+      Outside a terminal it asks nothing: it prints each step as it stands, and exits 0 when the desk can
+      open, 1 when a step still waits on something the desk needs.
+    TEXT
+    def setup
+      installation = Installation.here
+      # An update hands over to the version it installed, to link it and say
+      # what is new: the owner asked for an update, not for a setup.
+      return puts(installation.install, "", installation.news) if installation.news
+
+      discovered
+      boot_desk!
+      setup = Setup.new(installation:, directory: options[:project] || Dir.pwd) { Doctor.new(discovered(it)) }
+      exit(setup.show ? 0 : 1) unless $stdin.tty?
+
+      case setup.walk
+      # The command that runs now, as a new terminal may not find proctolog yet.
+      in :serve then exec(RbConfig.ruby, $PROGRAM_NAME, "serve", *(["--project", Project.current.root.to_s] if Project.current))
+      in :finished then exit 0
+      in :stopped then exit 1
+      end
+    rescue Installation::Refused => e
+      abort e.message
+    end
+
+    no_commands do
+      # The checkout --project names, or the one this runs in, found again
+      # each time: one a setup step made is there the next time it checks.
+      def discovered(directory = options[:project] || Dir.pwd)
+        Project.current = Project.discover(directory)
       rescue Project::Missing
-        nil
+        Project.current = nil
       end
-      Desk.initialize! unless Desk.initialized?
-      Doctor.new(project).tap { puts it }.then { exit(it.fine? ? 0 : 1) }
     end
   end
 end

data/completions/_proctolog

@@ -5,7 +5,7 @@
 # where burst files were kept before; for check and burst new, the open pull
 # requests of the desk's last reading, with their titles, and the branches
 # whose pull requests nobody has opened yet; for unopened folder, every
-# branch of the checkout.
+# branch of the checkout; for share, its commands and the ways to share.
 
 # "owner/name" of the checkout's GitHub origin.
 _proctolog_repository() {
@@ -47,9 +47,10 @@ _proctolog_parts() {
 
 _proctolog() {
   local root own named
-  local -a commands burst_commands unopened_commands bursts pull_requests unopened branches parts project files
+  local -a commands burst_commands unopened_commands share_commands bursts pull_requests unopened branches parts project port files
   commands=(
-    'serve:Open the desk on http://localhost:4040'
+    'serve:Open the desk on http://proctolog.localhost:4040'
+    'share:Share the desk with your phone or another computer, through Tailscale or ngrok'
     'route:Print the order to take a burst in'
     'handover:Hand what the owner decided so far to the agent that runs it'
     'burst:Start a burst of your own, or list the bursts there are'
@@ -57,8 +58,9 @@ _proctolog() {
     'check:Check a description as the desk reads it, of a pull request or a file'
     'themes:Print the themes a decision may name, with what each means'
     'doctor:Say what this Mac and this checkout lack, a line each with the fix'
+    'setup:Set PRoctolog up, a step at a time, from wherever you are to an open desk'
     'version:Print which PRoctolog this is'
-    'install:Link zsh'"'"'s completion and the agent skills to this PRoctolog'
+    'install:Another name for setup: link this PRoctolog, then set it up a step at a time'
     'update:Install the latest PRoctolog, and link to it'
     'tree:Print a tree of all available commands'
     'help:Describe the commands, or one of them'
@@ -73,7 +75,14 @@ _proctolog() {
     'folder:Print the folder a pull request nobody has opened yet is written in'
     'help:Describe the unopened commands, or one of them'
   )
+  share_commands=(
+    'start:Share the desk through Tailscale or ngrok, and print its address'
+    'stop:Stop sharing the desk: it is only on this Mac again'
+    'status:Say whether the desk is shared, and what Tailscale and ngrok each need'
+    'help:Describe the share commands, or one of them'
+  )
   project=('(-C --project)'{-C,--project}'[Git checkout]:directory:_directories')
+  port=('(-p --port)'{-p,--port}'[The port of the desk]:port:')
   root=$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null)
   own=${PROCTOLOG_DATA:-$HOME/.local/share/proctolog}/$(_proctolog_repository "$root")/bursts
   bursts=($own/*.yml(N:t:r) $root/.proctolog/{bursts,reviews}/*.yml(N:t:r))
@@ -85,7 +94,23 @@ _proctolog() {
     command) _describe -t commands 'command' commands ;;
     argument)
       case $words[1] in
-        serve) _arguments '(-p --port)'{-p,--port}'[The port to listen on]:port:' $project ;;
+        serve) _arguments $port '--share[Share it too, as proctolog share does]' $project ;;
+        share)
+          # Without a subcommand, share is start: its options come at once.
+          if (( CURRENT == 2 )) && [[ $words[2] != -* ]]; then
+            _describe -t commands 'share command' share_commands
+          else
+            case $words[2] in
+              start|-*)
+                _arguments $port \
+                  '--via[The way to share it, remembered for the next time]:way:(tailscale ngrok)' \
+                  '*--allow[An email that may sign in through ngrok]:email:' \
+                  '1:: :' ;;
+              stop|status) _arguments $port '1:: :' ;;
+              help) _describe -t commands 'share command' share_commands ;;
+            esac
+          fi
+          ;;
         route) _arguments $project "1:burst:(${bursts})" ;;
         handover)
           named=${${words[2,-1]:#-*}[1]}
@@ -133,7 +158,7 @@ _proctolog() {
           unopened=(${(f)"$(_proctolog_unopened "$root")"})
           _arguments $project '(-f --file)'{-f,--file}'[A local Markdown file to check before it is published]:file:_files' \
             "1:pull request:{_describe -t pull-requests 'open pull request' pull_requests; _describe -t unopened 'not opened yet' unopened}" ;;
-        themes|doctor|version|install|update) _arguments $project ;;
+        themes|doctor|setup|version|install|update) _arguments $project ;;
         help) _describe -t commands 'command' commands ;;
       esac
       ;;

data/config/application.rb

@@ -53,6 +53,18 @@ module Proctolog
 
     def self.scratch = @scratch ||= Pathname(Dir.mktmpdir("proctolog")).tap { |made| at_exit { made.rmtree } }
 
+    def self.port = config.x.port
+
+    # Where the desk is on this Mac: a name of its own, which a browser's
+    # history completes from "procto" where localhost:4040 is one of many.
+    def self.address(port = self.port) = "http://proctolog.localhost:#{port}"
+
+    # A desk on marks of its own (PROCTOLOG_MARKS): a test's, or one an agent
+    # starts to try a change, often while the owner is away. It writes nothing
+    # to GitHub, and asks 1Password for no keys, which would wait on the owner
+    # to unlock it.
+    def self.trial? = ENV.key?("PROCTOLOG_MARKS")
+
     config.root = File.expand_path("..", __dir__)
     config.load_defaults 8.1
     config.eager_load = false
@@ -61,8 +73,14 @@ module Proctolog
     # Kept outside the installed app so an update does not sign out an open desk.
     config.secret_key_base = kept("secret_key_base") { SecureRandom.hex(64) }
     # Whatever the environment: a page of another site that points a name of
-    # its own at this Mac is turned away.
-    config.hosts = ["localhost", IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")]
+    # its own at this Mac is turned away. Names under localhost are this
+    # Mac's alone, as browsers send them nowhere else: proctolog.localhost is
+    # the desk's own. While the desk is shared, it answers to the share's
+    # name too (Share).
+    config.hosts = [".localhost", IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")]
+    config.host_authorization = {exclude: ->(request) { Proctolog::Share.carries?(request) }}
+    # The port the desk serves on, which `serve` names.
+    config.x.port = 4040
     config.logger = ActiveSupport::Logger.new($stdout)
     # Grouse says at boot what is not set up yet, which its tests need not hear.
     config.log_level = Rails.env.test? ? :error : :warn
@@ -80,8 +98,9 @@ module Proctolog
     config.active_job.queue_adapter = Rails.env.test? ? :test : :async
     # Whether Grouse is given the owner's keys from 1Password (config/keys.yml):
     # when the desk serves, and for Rails' own commands such as grouse:doctor.
-    # A `proctolog` command that only prints asks 1Password for nothing.
-    config.x.reads_keys = Rails.env.development?
+    # A `proctolog` command that only prints asks 1Password for nothing, and
+    # nor does a trial desk.
+    config.x.reads_keys = Rails.env.development? && !trial?
     config.active_storage.service = :local
     config.active_storage.variant_processor = :disabled
     # The migrations are the record; the desk brings its database up to them

data/config/initializers/grouse.rb

@@ -86,7 +86,7 @@ Grouse.configure do |c|
   # The owner's keys, read from 1Password by config/keys.yml's references where the desk
   # reads keys at all (config.x.reads_keys). Without one, a voice note arrives as audio only
   # and a note is not written up; `op` says on the terminal why it could not read it. Tests
-  # read none, and send nothing to a vendor.
+  # and trial desks (PROCTOLOG_MARKS) read none, and send nothing to a vendor.
   c.transcriber = Grouse::Transcribers::ElevenLabs.new(api_key: key.call("elevenlabs"))
   c.structurer = Grouse::Structurers::Anthropic.new(api_key: key.call("anthropic"))
   # c.transcriber = nil                           # turns a recording into words; with none, voice notes arrive as audio only

data/config/routes.rb

@@ -17,6 +17,9 @@ Proctolog::Desk.routes.draw do
     # The pull requests, of every state, that a # typed in any box may mean.
     resources :mentions, only: :index
 
+    # The desk shared with the owner's other devices, through Tailscale or ngrok.
+    resource :share, only: %i[show create destroy]
+
     resources :bursts, only: %i[show create] do
       resource :put_away, only: %i[create destroy], controller: :put_away
       resources :pull_requests, only: :show, param: :number do

data/docs/manual/bursts.md

@@ -7,8 +7,8 @@ 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.
+Its own pane says no burst is open, and lists your bursts with how many of
+each one's decisions wait: a bead of each grade, and how many of it. 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
@@ -27,6 +27,11 @@ 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)).
 
+"Start here" heads the page until you have a burst of your own, and whenever
+there is nothing to decide: it says how many pull requests are written for
+PRoctolog and how to open one, that none is yet and how to have them
+rewritten, or that nothing is open and how to have some written.
+
 ## When a burst is done
 
 A pull request that merges leaves the route, and goes under "Merged" at its

data/docs/manual/deciding.md

@@ -17,7 +17,10 @@ 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
+typing. It asks the session to answer and change nothing. A pull request
+nobody has opened yet is named by its branch, its base and the file its
+description is kept in, and the session is told to read it with git, since
+GitHub has nothing of it. 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

data/docs/manual/handover.md

@@ -56,6 +56,12 @@ 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.
 
+A note of yours that an agent answers follows its answer in the marks, where
+the page's Notes and an agent reading the files both see it: addressed once
+the answer is in, confirmed once you confirm it here, open again once you
+answer back. Its card says to judge it under Returned work and offers only
+Withdraw. The pane's `↩` follows as you go, without the page loading again.
+
 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

data/docs/manual/pr-format.md

@@ -21,7 +21,7 @@ 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`
+whole example in its `references/example-description.md`. `proctolog setup`
 links it into `~/.claude/skills/` and `~/.agents/skills/`. Keep the project's
 template (Summary, Changes, Verification) and add:
 

data/docs/manual/reading.md

@@ -42,18 +42,23 @@ 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,
+On the Route, `j` / `k` select a PR and Enter opens it. Each line ends with its
+decisions as beads, a bead to each, as deciding draws them: a full-size bead
+for a blocking decision, a small one for a non-blocking, solid once reviewed,
+hollow while it waits. Before them it says **back to you** once the agent's
+answers have come back for you to confirm, or answer, or once it addressed one
+of your notes; otherwise whose it is when it is not yours: with the agent,
+settled or waiting. The line the cursor is on opens out with the rest: its
+layer, what is open (“4 returned, to confirm”), its pictures and words, and
+when it last changed. `N` opens the next PR that asks for you: one with a
+blocking decision left, or something back from the agent. 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
+next / previous PR, `N` the next one that asks for you, 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.
 
@@ -93,12 +98,14 @@ 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).
+A pane at the left of every page lists the route, and marks the one you are
+on. Each PR ends with the same beads as its line on the Route, smaller, and
+they follow your choices as you make them. A `↩` before it means the agent's
+answers came back on it for you. 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 (“back to you: 4
+returned, to confirm”, “1 of 4 blocking decisions reviewed”), 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
@@ -120,23 +127,43 @@ 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.
+decision, you opened it from, and the page draws the notes written there
+where it stands. Once the viewer shows only part of the picture, a map in its
+corner shows the whole, with the part on the stage framed; a press on the map
+goes there.
+
+A note on a picture of the page itself, a click or a drag on it, is written
+under the picture and saved where it stands too: the page does not load
+again or move, zoomed in or not, and draws the note's box and its card.
 
 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.
+them as `#screenshot-NAME`. In the viewer a quiet panel beside them lists the
+five ways to look at them, each a button with its key; the one you are in
+says what it shows. `s` side by side, `w` swipe (the after picture over the
+before, up to a divider that a drag or the arrows move), `b` blink (one, then
+the other), `o` onion skin (the after picture half seen through over the
+before) and `d` difference (only what differs is lit). A view's key again, or
+a press on its button, goes back to side by side. Blink is the exception: `b`
+again shows the other half, when you want it, and Shift B sets it blinking by
+itself, or stops it.
+
+Under the views the panel counts the changed regions. They are outlined on
+the pictures in black dashed with white, at the same place on each half; a
+note's box is a heavier solid frame, so the two are told apart at a glance.
+`n` and `p` focus on the next region and the one before, as does a press on
+its number: it is tagged with its number and its half. Focusing keeps your
+zoom: seen whole, the region is only outlined; zoomed in, the stage goes near
+enough to see each region whole. `z` goes near to the one in focus, and `0`
+back to the whole. The panel shows the region focused on as the before has it
+and as the after does; Enter writes a note on it in the after, and a press on
+either writes one there, in any view. Until the regions are found the panel
+says “Comparing…”, then how many there are, “Nothing: the same pixels.”,
+“Sizes differ: laid from the top left.”, or that finding them needs
+ImageMagick. A click or a drag marks the half it is made on side by side, and
+the one showing in blink, which holds still while you write; swipe, onion skin
+and difference take a note only on a region the panel shows. 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
@@ -162,7 +189,7 @@ 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
+`N` opens the next PR that asks for you, `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