proctolog 0.1.0 → 0.2.0

data/app/views/proctolog/shares/show.html.erb

@@ -0,0 +1,48 @@
+<% content_for :title, "Sharing the desk" %>
+<% content_for :head do %>
+  <link rel="stylesheet" href="/share.css">
+<% end %>
+
+<header class="burst">
+  <h1>Sharing the desk</h1>
+  <p class="lede">
+    Review from your phone, or a computer elsewhere, while this Mac keeps the desk. Only you get in.
+    <%= link_to "Back", @back %>
+  </p>
+</header>
+
+<main class="route share">
+  <% if @share %>
+    <p class="now">Shared at <%= link_to @share.address, @share.address %> through <%= @share.way.name %>: <%= @share.who %>.</p>
+    <p class="hint">It stays shared until you stop it, the desk running or not.<% if Proctolog::Share.carries?(request) %> This page came through it: stopping it closes this page too.<% end %></p>
+    <%= button_to "Stop sharing", share_path, method: :delete, params: {back: @back}, class: "quiet" %>
+  <% else %>
+    <p class="now">Only on this Mac, at <%= link_to Proctolog::Desk.address, Proctolog::Desk.address %>.</p>
+
+    <h2>Share it through</h2>
+    <div class="ways">
+      <% @ways.each do |way| %>
+        <section class="way" aria-label="<%= way.name %>">
+          <h3><%= way.name %></h3>
+          <% if way.ready? %>
+            <%= form_with url: share_path, method: :post do |form| %>
+              <%= form.hidden_field :via, value: way.to_param %>
+              <%= form.hidden_field :back, value: @back %>
+              <%= render "proctolog/shares/ways/#{way.to_param}", way:, form: %>
+              <%= form.button "Share through #{way.name}", class: "quiet" %>
+            <% end %>
+          <% else %>
+            <p class="facts"><%= linked_sentence(way.unready) %>.</p>
+          <% end %>
+        </section>
+      <% end %>
+    </div>
+  <% end %>
+
+  <h2>From a terminal</h2>
+  <p class="hint">
+    <code>proctolog share</code> shares it the way you named last, or the first one ready, and prints the address;
+    <code>proctolog share stop</code> stops it, and <code>proctolog share status</code> says what each way needs.
+    An agent can run them too, on a Mac you left working.
+  </p>
+</main>

data/app/views/proctolog/shares/ways/_ngrok.html.erb

@@ -0,0 +1,6 @@
+<%# locals: (way:, form:) %>
+<p class="facts">At your ngrok account's address, on the internet, behind ngrok's sign-in with Google and a warning page of its own. Its free plan carries 1 GB a month, and every picture and film you open passes through it.</p>
+<p class="allow">
+  <%= form.label :allow, "Who may sign in" %>
+  <%= form.text_field :allow, value: way.allowed.join(", "), spellcheck: false, autocomplete: "off" %>
+</p>

data/app/views/proctolog/shares/ways/_tailscale.html.erb

@@ -0,0 +1,2 @@
+<%# locals: (way:, form:) %>
+<p class="facts">At this Mac's name on your tailnet, and nowhere on the internet. Your phone needs the Tailscale app, signed in to <%= way.tailnet ? "the tailnet #{way.tailnet}" : "the same tailnet" %>: one account can be in more than one.</p>

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,69 @@ 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 answers?
+      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)
+
+      def answers?
+        Socket.tcp("localhost", port, connect_timeout: 1, &:close)
+        true
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+
   class CLI < Thor
     include Booting
 
@@ -141,19 +211,26 @@ module Proctolog
     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
@@ -275,6 +352,15 @@ 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|

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'
@@ -73,7 +74,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 +93,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]}

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/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

data/docs/manual/sharing.md

@@ -0,0 +1,77 @@
+# The desk's address, and sharing it
+
+## On this Mac
+
+The desk is at <http://proctolog.localhost:4040>. Arc, Chrome and the other
+Chromium browsers send any name under `localhost` to this Mac without asking
+anyone, so there is nothing to set up; after the first visit, typing `procto`
+in the address bar finds it. `http://localhost:4040` still works too. Safari asks macOS, which
+doesn't know these names, so use `localhost` there.
+
+A bare `proctolog`, with no port, would need the desk on port 80, which macOS
+gives a user only on every network at once, Wi-Fi included. The desk listens
+on this Mac alone, so it stays on its port.
+
+## From your phone, or a computer elsewhere
+
+Sharing the desk lets you reach it from your other devices while this Mac
+keeps it: a review on your phone, say, while an agent works on. Only you get
+in. It goes through whichever of these this Mac has:
+
+- **Tailscale.** The desk is at this Mac's name on your tailnet,
+  `https://your-mac.your-tailnet.ts.net`. Only the devices signed in to your
+  tailnet reach it, so your phone needs the Tailscale app, signed in to the
+  same tailnet as this Mac. One account can be in more than one tailnet, one
+  of its own and others it was invited to, so check the tailnet's name, not
+  only the account: `proctolog share status` and the sharing page say it.
+  Nothing goes on the internet, and nothing limits how much you open. Install it from <https://tailscale.com/download/mac>; the desk asks
+  for HTTPS certificates to be on for your tailnet, which they are unless you
+  turned them off, at <https://login.tailscale.com/admin/dns>.
+- **ngrok.** The desk is on the internet, at the address ngrok gives your
+  account, behind ngrok's sign-in with Google, which lets in only your Git
+  email unless you name others. Install it (`brew install ngrok`), then copy
+  your authtoken from <https://dashboard.ngrok.com/get-started/your-authtoken>
+  and run `ngrok config add-authtoken TOKEN`. On the free plan, ngrok shows a
+  warning page of its own before the desk, and carries 1 GB a month.
+
+Neither is installed for you. `proctolog doctor` and `proctolog share status`
+say what each one still needs.
+
+### Turning it on
+
+On any page with the pane at the left, its foot says whether the desk is
+shared; **share it** opens the page that shares it, through either way,
+and stops it again. From a terminal:
+
+```sh
+proctolog share                # the way you named last, or the first one ready
+proctolog share --via ngrok --allow you@gmail.com
+proctolog share status         # shared or not, and what each way needs
+proctolog share stop
+proctolog serve --share        # open the desk, shared
+```
+
+An agent can run them too, on a Mac you left working, and send you the
+address it prints. A share stays open until it is stopped, whether the desk
+is running or not, and a share already open is only printed again. A trial
+desk, on marks of its own, is never shared.
+
+### What passes through it
+
+Everything a page shows comes from this Mac, so everything you open travels
+through the share. That counts for ngrok's 1 GB: a pull request's pictures
+are on GitHub, but GitHub gives them only to someone signed in, so the desk
+fetches each one once, with your `gh`, keeps it, and serves it itself. Its
+films are the same. Keeping them saves asking GitHub again, not the trip to
+your phone.
+
+### What stays on this Mac
+
+- **The app under review.** A scenario's button and the Try it rail open the
+  app at `localhost`, which on a phone is the phone. They work on this Mac
+  only for now.
+- **Grouse's overlay.** The desk shows it to a request from this Mac, and one
+  through the share isn't one.
+
+The desk is drawn for a keyboard. On a phone it reads, and its buttons and
+links work, but the keys have no touch of their own yet.

data/lib/proctolog/changelog.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # CHANGELOG.md as a release reads it: a section to each version, newest
+  # first, under ## Unreleased what main has that no gem has yet. Plain Ruby,
+  # as bin/release and the Release workflow read it before any bundle.
+  class Changelog
+    PATH = File.expand_path("../../CHANGELOG.md", __dir__)
+
+    # One ## section, its lines under ### Added, Changed and Fixed.
+    Section = Data.define(:name, :text) do
+      def adds? = text.match?(/^### Added$/)
+      def lines? = text.match?(/^- /)
+      def notes = text.strip
+    end
+
+    # It writes ⌘ and ↩, so it is read as UTF-8 whatever the locale.
+    def self.read(path = PATH) = new(File.read(path, encoding: "UTF-8"))
+
+    def initialize(text)
+      @sections = text.split(/^## /).drop(1).map do
+        name, body = it.split("\n", 2)
+        Section.new(name: name.strip, text: body.to_s)
+      end
+    end
+
+    def [](name) = @sections.find { it.name == name }
+
+    def unreleased = self["Unreleased"]
+
+    # Adding something makes a minor (docs/manual/updates.md): the minor this
+    # version owes when it adds something but is only a patch on the one
+    # before it.
+    def minor_owed(version)
+      owed = released_before(version)&.then { Gem::Version.new("#{it.bump}.0") }
+      owed if owed && adds?(version) && Gem::Version.new(version) < owed
+    end
+
+    private
+
+    # Under its own heading, or still under Unreleased, since main has that
+    # too.
+    def adds?(version) = [self[version], unreleased].compact.any?(&:adds?)
+
+    def released_before(version)
+      older = @sections.drop_while { it.name != version }.drop(1)
+      older.map(&:name).find { Gem::Version.correct?(it) }&.then { Gem::Version.new(it) }
+    end
+  end
+end

data/lib/proctolog/version.rb

@@ -3,5 +3,5 @@
 module Proctolog
   # Semantic: a patch fixes, a minor adds, a major asks something new of the
   # owner (a command gone, a file moved). docs/manual/updates.md says more.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end