proctolog 0.1.0

data/config/initializers/grouse.rb

@@ -0,0 +1,113 @@
+return unless Proctolog::Desk.grouse?
+
+require "open3"
+
+# Grouse: the overlay the owner writes notes on the desk with, read in its inbox at /grouse
+# and by coding agents through its export API (AGENTS.md, "Review notes"). Every setting
+# left commented out is at its default.
+#
+# Grouse calls these lambdas from its own controllers, which answer before any callback of
+# the desk's runs, so each finds what it needs from the request itself.
+
+key = ->(name) do
+  next unless Rails.configuration.x.reads_keys
+
+  reference = YAML.load_file(Rails.root.join("config/keys.yml")).fetch(name)
+  read, done = Open3.capture2("op", "read", "--no-newline", reference)
+  read.presence if done.success?
+rescue Errno::ENOENT
+  Rails.logger.warn("[proctolog] 1Password's op is not installed, so Grouse has no #{name} key.")
+  nil
+end
+
+Grouse.configure do |c|
+  # The desk serves one person, on this Mac, and listens on localhost alone: a request from
+  # this machine is the owner. Its tests open Grouse only where they test it.
+  c.enabled_for = ->(request) { request.local? } unless Rails.env.test?
+
+  # The desk has no sign-in. Every note is the owner's, and nobody else is signed in.
+  c.current_author = ->(request) { Proctolog::Owner.current }
+  # c.author_label = ->(person) { person.name }   # default: name, else username, else "User 12"
+  # c.app_user_label = nil                        # nil: author_label labels both
+
+  # Grouse's controllers inherit this. Keep ActionController::Base unless every callback of
+  # the class you name is safe to run on Grouse's endpoints.
+  # c.parent_controller = "ActionController::Base"
+
+  # Where things live, and for how long.
+  # c.base_url = nil                              # e.g. "https://app.example.com": inbox links in PostHog events and hooks, which run with no request
+  # c.queue_name = :default
+  # c.rate_limits.notes = {to: 30, within: 1.minute} # notes per reviewer
+  # c.rate_limits.takes = {to: 120, within: 1.minute} # per reviewer: the updates while a voice note records
+  # c.rate_limits.screenshots = {to: 30, within: 1.minute} # screenshot uploads per reviewer, one a note
+  # c.rate_limits.store = nil                     # nil: Grouse's own memory store
+  # c.inbox.poll_interval = 20.seconds            # how often an open inbox asks whether it changed; nil: never
+  # c.storage_service = nil                       # where recordings and screenshots are kept, a service in config/storage.yml; nil: config.active_storage.service
+  # c.retention.media = 90.days                   # reserved for pruning: nothing prunes yet
+  # c.retention.resolved_notes = 90.days          # reserved for pruning: nothing prunes yet
+
+  # What a page says about itself.
+  # c.release = nil                               # e.g. -> { ENV["GIT_REVISION"] }, or a String
+  # c.context_providers = []                      # each ->(request) { {"native_shell" => true} }, 4 KB in all
+  # c.privacy.mask_selectors = []                 # on top of .ph-mask and [data-grouse-mask]
+  # c.privacy.block_selectors = []                # on top of .ph-no-capture and [data-grouse-block]
+  # c.privacy.redact = %i[tokens emails numbers]  # drop a name to keep that kind of text in the outline
+  # c.capture_network_errors = false              # true wraps fetch and XHR to keep same-origin requests answered >= 400 or not at all:
+  #                                               # method, path, status; never a body, a header, a query, another origin's or Grouse's own
+  c.screenshots = :opt_in                         # :opt_in offers a camera per note, :always starts it on, :off takes none and refuses uploads;
+  #                                               # screenshots are kept by Active Storage, as recordings are
+
+  # The pill.
+  c.widget.position = "bottom-right"              # clear of the route pane at the desk's left
+  # c.widget.z_index = 58
+  # c.widget.shortcut = "Alt+Shift+KeyN"          # a KeyboardEvent.code form; nil turns it off
+  # c.widget.gesture = "toggle"                   # or "hold": the record button is held while speaking
+
+  # Voice notes need Active Storage (bin/rails active_storage:install). Without it they are
+  # simply not offered, and notes are typed-only.
+  # c.voice.enabled = true                        # false: typed-only, even with Active Storage
+  # c.voice.salvage_after = 3.minutes             # a voice draft no page has touched for this long is delivered as it stands
+
+  # PostHog. Grouse reads your posthog-js and never boots its own. With posthog-rails
+  # installed, its PostHog.client is used for server events.
+  # c.posthog.client = nil                        # e.g. PostHog::Client.new(api_key: ENV["POSTHOG_KEY"], host: "https://us.i.posthog.com")
+  # c.posthog.ready_event = nil                   # e.g. "posthog:loaded", if your snippet's `loaded` callback dispatches it
+  # c.posthog.consent_meta = nil                  # e.g. "posthog-consent": a <meta name> whose content says whether analytics were accepted
+  # c.posthog.client_events = false               # true sends grouse_note_started into your PostHog project when a reviewer starts a note
+  # c.posthog.replay_hosts = %w[us.posthog.com eu.posthog.com] # the PostHog UI hosts a replay link may point at
+  # c.posthog.distinct_id_for = nil               # e.g. ->(author) { author.id.to_s }
+  # c.posthog.include_text = false                # true sends the note's words (first 2,000 characters) with grouse_note_created
+  # c.posthog.llm_analytics = false               # true sends one $ai_generation per structuring request (PostHog LLM analytics, billed on its own); the prompt and the answer only with include_text
+
+  # Transcription, structuring and hand-off. Each is optional and ends in a visible state.
+  # c.on_delivered = []                           # each ->(note) { }, run in a job after the request; keep them short
+  # c.on_ready = {}                               # name => sink, each run in a job once a note's words and structure are in; none: nothing is handed on
+  #   c.on_ready[:linear] = ReviewNotes::LinearExport # a callable: gets a Grouse::ReadyNote, answers {id:, url:}, or raises Grouse::Sinks::Unavailable, "linear_503" to be asked again
+  # 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.
+  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
+  #   Grouse::Transcribers::ElevenLabs.new(api_key: ENV["ELEVENLABS_API_KEY"], language: nil, keyterms: %w[YourProduct])
+  #   Grouse::Transcribers::OpenAI.new(api_key: ENV["OPENAI_API_KEY"], model: "gpt-transcribe", language: "he")
+  #   ->(io, filename:, content_type:) { "the words" }   # or your own: a String, or a Grouse::Transcript
+  # c.structurer = nil                            # writes each note up as an issue (title, kind, steps); with none, notes stay as written
+  #   Grouse::Structurers::Anthropic.new(api_key: Rails.application.credentials.dig(:anthropic, :api_key))
+  #   Grouse::Structurers::OpenAI.new(api_key: ENV["OPENAI_API_KEY"], model: "gpt-5-mini")   # base_url: any server that speaks its chat API
+  #   ->(note, prompt) { YourGateway.json(system: prompt.system, user: prompt.user, schema: prompt.schema) } # a Hash in that schema's shape
+
+  # Coding agents read notes with a token each: {label => token}, tokens of 32+ characters.
+  # No token means no API.
+  # The agents' token, made the first time the desk boots and kept beside its secret, out
+  # of Git (AGENTS.md says where). Tests have no API.
+  c.api_tokens = -> { {"agent" => Proctolog::Desk.kept("grouse_token") { SecureRandom.hex(32) }} } unless Rails.env.test?
+
+  # Review sessions (docs/plan/06): a review an outside tool prepares, from a runner with
+  # Grouse::Sessions.open or with an API token over POST /api/sessions, shows the widget to whoever
+  # carries its cookie and collects their notes. They open only in these environments:
+  # c.sessions.environments = %w[development]
+  # The hosts a session's notes may be pushed back to, at its return_url; [] turns pushing off.
+  # c.sessions.return_hosts = %w[localhost 127.0.0.1 ::1]
+end

data/config/initializers/grouse_notes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The desk makes its database, and brings it up to the latest migration,
+# whenever it boots: nobody runs db:migrate on a tool they only start, and a
+# pull that brings a migration then needs no step of the owner's.
+Rails.application.config.after_initialize do
+  ActiveRecord::Migration.verbose = false
+  ActiveRecord::Base.connection_pool.migration_context.migrate
+end

data/config/keys.yml

@@ -0,0 +1,6 @@
+# The owner's vendor keys for Grouse, as 1Password references, never the keys
+# themselves: the desk reads each with `op read` when it serves
+# (config/initializers/grouse.rb). A key 1Password cannot give leaves voice
+# notes audio only, or notes unwritten up.
+elevenlabs: "op://Private/eqn4mdg3vkzv5gkgrxuuqchiqa/credential"
+anthropic: "op://Private/Anthropic API Key/credential"

data/config/routes.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+Proctolog::Desk.routes.draw do
+  # The owner's notes on the desk itself: the overlay's endpoints, its inbox and the export API.
+  mount Grouse::Engine, at: "/grouse" if Proctolog::Desk.grouse?
+
+  scope module: :proctolog do
+    root "bursts#index"
+
+    # The repository's open pull requests, to pick a burst from.
+    resources :open_pull_requests, only: :index, path: "pull_requests" do
+      post :alone, on: :member
+      post :chain, on: :member
+    end
+    post "stacks/:id", to: "open_pull_requests#stack", as: :review_stack, constraints: {id: /\d+/}
+
+    # The pull requests, of every state, that a # typed in any box may mean.
+    resources :mentions, only: :index
+
+    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
+        resources :notes, only: %i[create update]
+        resource :good_to_go, only: %i[create destroy], controller: :good_to_go
+        resource :waiting, only: :update, controller: :waiting
+        resource :code_review, only: %i[show create destroy]
+        resources :decisions, only: :update, param: :position
+        resource :acceptance, only: %i[new create]
+      end
+
+      resources :decisions, only: :index
+      resource :prompt, only: %i[show create] do
+        post :preview
+      end
+      resource :review_data, only: :show, controller: :review_data
+      resource :rendered_pieces, only: :create
+      resource :evidence, only: :show, controller: :evidence do
+        get :compare
+      end
+      resource :choices, only: %i[show update]
+      resources :rules, only: %i[update destroy], id: /[^\/]+/
+      resource :freshness, only: :show, controller: :freshness
+      resource :membership, only: :update do
+        post :handed_over
+      end
+      resources :scenarios, only: :index do
+        post :open, on: :member
+        post :saw, on: :member
+        post :pull, on: :member
+        resources :notes, only: %i[create update], controller: :scenario_notes
+      end
+      resource :sitting_server, only: %i[show create destroy]
+      resources :recordings, only: :index
+      get "recordings/*path", to: "recordings#show", as: :recording, format: false
+      get "stills/:index/*path", to: "recordings#still", as: :recording_still, format: false, constraints: {index: /\d+/}
+      resources :moments, only: %i[create update]
+    end
+
+    # Bursts were called reviews: a tab opened then still reads and saves.
+    # 307 keeps a PUT a PUT, with its body, and is not remembered by the browser.
+    match "reviews(/*rest)", via: :all, format: false, to: redirect(status: 307) { |_, request| request.fullpath.sub(%r{\A/reviews}, "/bursts") }
+
+    # Rack::Files answers Range requests, which a browser needs to seek in a video.
+    mount Rack::Files.new(Proctolog::Recording.directory.to_s, {"cache-control" => "no-cache"}), at: "films"
+
+    resources :entries, only: :show, param: :token
+    get "pictures/:asset", to: "pictures#show", as: :picture, constraints: {asset: Proctolog::Picture::ASSET}
+    get "pictures/:before/against/:after", to: "pictures#compare", as: :difference, format: false,
+      constraints: {before: Proctolog::Picture::FILE, after: Proctolog::Picture::FILE}
+  end
+end

data/config/storage.yml

@@ -0,0 +1,4 @@
+# Voice notes and screenshots, beside the database that holds their notes.
+local:
+  service: Disk
+  root: <%= Proctolog::Desk.grouse_notes.join("files") %>

data/db/migrate/20261019213542_create_grouse_tables.grouse.rb

@@ -0,0 +1,128 @@
+# This migration comes from grouse (originally 20261014000000)
+# Portions adapted from rails-markup (https://github.com/nauman/rails-markup) at ad756b8, Copyright (c) 2026 InventList, MIT licence. See NOTICE.
+
+# Grouse's two tables in one migration, so a host never needs a second one to turn on
+# voice (M2) or review sessions (M6a) (D11, D16). It is copied into the host's db/migrate,
+# so it decides two things when it runs there, not when the gem was built: jsonb on
+# PostgreSQL (json on SQLite), and the host's primary-key type, the way Active Storage's
+# own first migration does. Written against 8.0 because the gemspec admits 8.0 hosts.
+class CreateGrouseTables < ActiveRecord::Migration[8.0]
+  def change
+    refuse_unsupported_adapter!
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :grouse_sessions, id: primary_key_type do |t|
+      t.string :public_id, null: false
+      t.string :source, null: false # who opened it, e.g. "proctolog"
+      t.string :label, null: false # what the overlay shows
+      t.string :reviewer_label, null: false # the author of the session's notes
+      t.string :external_ref # the opener's own key for it
+      t.column :metadata, json_type, null: false, default: {}
+      t.text :return_url # allow-listed again before any push (M6a)
+      t.string :entry_token_digest # the one-time enter link (M6a), stored as a digest only
+      t.datetime :entered_at # set when that link is spent
+      t.datetime :expires_at, null: false
+      t.datetime :closed_at
+      t.timestamps
+
+      t.index :public_id, unique: true, name: "index_grouse_sessions_on_public_id"
+      t.index :entry_token_digest, unique: true, name: "index_grouse_sessions_on_entry_token"
+      t.index %i[source external_ref], name: "index_grouse_sessions_on_source_ref"
+    end
+
+    create_table :grouse_notes, id: primary_key_type do |t|
+      t.string :public_id, null: false
+      t.string :client_uuid, null: false
+
+      # Who. No foreign key to the host's users: they are not ours (03 §7).
+      t.references :author, polymorphic: true, type: foreign_key_type, index: false
+      t.string :author_label
+      t.string :app_user_gid
+      t.string :app_user_label
+      # Named: a host may have its own `sessions` table (sartoria does).
+      t.references :session, type: foreign_key_type, index: {name: "index_grouse_notes_on_session_id"},
+        foreign_key: {to_table: :grouse_sessions, on_delete: :nullify, name: "fk_grouse_notes_session"}
+
+      # Capture: a draft until exactly one ending claims it (invariant 2).
+      t.string :capture, null: false, default: "draft"
+      t.string :delivered_via # sent | closed | salvaged (D29)
+      t.datetime :delivered_at
+      t.string :channel, null: false, default: "typed"
+      t.datetime :started_at # when the reviewer began; the context froze then
+      t.integer :take_seq, null: false, default: 0 # M2: a PATCH carrying an older take changes nothing
+
+      # Words, and the reviewer's own labels for them (D22).
+      t.text :body
+      t.string :intent
+      t.string :severity
+
+      # Annotations (M2, M4). Each ends in a state the inbox shows (invariant 1).
+      t.text :transcript
+      t.string :transcript_provider
+      t.string :transcript_language
+      t.string :transcription_state, null: false, default: "none"
+      t.string :transcription_error
+      t.integer :audio_ms
+      t.column :structured, json_type, null: false, default: {}
+      t.string :structure_state, null: false, default: "none"
+      t.string :structure_error
+
+      # Where: copies lifted from the frozen context by Contextual, for filtering and lists.
+      t.text :page_url
+      t.string :route # the URI pattern, e.g. /orders/:id(.:format)
+      t.string :controller_action # orders#show (CC-14)
+      t.string :request_id
+      t.string :release
+      t.string :environment
+      t.column :context, json_type, null: false, default: {}
+      t.column :anchor, json_type, null: false, default: {} # M3; {} means unanchored
+
+      # PostHog: why a replay link exists, or why it does not (D29).
+      t.string :posthog_distinct_id
+      t.string :posthog_session_id
+      t.string :replay_status, null: false, default: "error"
+      t.string :replay_detail
+      t.text :replay_url
+
+      # Triage (D14).
+      t.string :status, null: false, default: "pending"
+      t.integer :revision, null: false, default: 0
+      t.column :thread, json_type, null: false, default: []
+      t.datetime :resolved_at
+      t.string :resolved_by_label
+      t.string :resolution_commit
+
+      # What happened after delivery: the PostHog event and the hooks (M1), sinks (M4).
+      t.column :external_refs, json_type, null: false, default: {}
+
+      t.timestamps
+
+      t.index :public_id, unique: true, name: "index_grouse_notes_on_public_id"
+      t.index :client_uuid, unique: true, name: "index_grouse_notes_on_client_uuid"
+      t.index %i[status created_at], name: "index_grouse_notes_for_inbox"
+      t.index %i[capture updated_at], name: "index_grouse_notes_for_sweep"
+      t.index :posthog_session_id, name: "index_grouse_notes_on_posthog_session"
+    end
+  end
+
+  private
+
+  # Active Storage's own idiom (activestorage-8.1.4 create_active_storage_tables.rb:49-55). A
+  # UUID-keyed host gets UUID keys here too, which M2 needs: active_storage_attachments.record_id
+  # follows the same setting.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    [setting || :primary_key, setting || :bigint]
+  end
+
+  def json_type = postgresql? ? :jsonb : :json
+  def postgresql? = connection.adapter_name.match?(/postg/i)
+
+  # MySQL refuses literal defaults on JSON columns, and nothing here is tested on it. A plain
+  # refusal beats a cryptic failure halfway through a host's deploy.
+  def refuse_unsupported_adapter!
+    return if postgresql? || connection.adapter_name.match?(/sqlite/i)
+    raise NotImplementedError, "Grouse's tables need PostgreSQL or SQLite: their JSON columns carry defaults"
+  end
+end

data/db/migrate/20261019213550_create_active_storage_tables.active_storage.rb

@@ -0,0 +1,58 @@
+# This migration comes from active_storage (originally 20170806125915)
+class CreateActiveStorageTables < ActiveRecord::Migration[7.0]
+  def change
+    # Use Active Record's configured type for primary and foreign keys
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :active_storage_blobs, id: primary_key_type do |t|
+      t.string :key, null: false
+      t.string :filename, null: false
+      t.string :content_type
+      t.text :metadata
+      t.string :service_name, null: false
+      t.bigint :byte_size, null: false
+      t.string :checksum
+
+      if connection.supports_datetime_with_precision?
+        t.datetime :created_at, precision: 6, null: false
+      else
+        t.datetime :created_at, null: false
+      end
+
+      t.index [:key], unique: true
+    end
+
+    create_table :active_storage_attachments, id: primary_key_type do |t|
+      t.string :name, null: false
+      t.references :record, null: false, polymorphic: true, index: false, type: foreign_key_type
+      t.references :blob, null: false, type: foreign_key_type
+
+      if connection.supports_datetime_with_precision?
+        t.datetime :created_at, precision: 6, null: false
+      else
+        t.datetime :created_at, null: false
+      end
+
+      t.index [:record_type, :record_id, :name, :blob_id], name: :index_active_storage_attachments_uniqueness, unique: true
+      t.foreign_key :active_storage_blobs, column: :blob_id
+    end
+
+    create_table :active_storage_variant_records, id: primary_key_type do |t|
+      t.belongs_to :blob, null: false, index: false, type: foreign_key_type
+      t.string :variation_digest, null: false
+
+      t.index [:blob_id, :variation_digest], name: :index_active_storage_variant_records_uniqueness, unique: true
+      t.foreign_key :active_storage_blobs, column: :blob_id
+    end
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+end

data/docs/manual/app.md

@@ -0,0 +1,157 @@
+# How the desk runs your app
+
+A scenario button starts the app, puts it in a state, signs the right member in
+and opens a browser on the right page. The desk knows nothing about your app to
+do that. It reads `.proctolog/app.yml` in the checkout under review, a handful
+of commands and paths in your app's own words. With no `app.yml`, scenarios
+still list their steps, and you mark what you saw by hand.
+
+A pull request's scenarios come from its description: each bold heading of its
+"How to test locally" with numbered steps under it is one, opening the home
+page as whoever is signed in. A burst's `scenarios/<burst>.yml` names the state
+and the page a pull request's scenarios start from, as `recipe:` and `opens:`;
+a pull request it names takes its scenarios from the file alone.
+
+```yaml
+# Makes the app ready to serve, run before `serve` on every Start: so a
+# database that is not there yet is made, and one that is costs a moment.
+prepare: bin/scratch_dev %{slug} bin/rails db:prepare
+
+# Runs until stopped, in the sitting's checkout. The desk calls the app up once
+# every port in `listens` answers, counted up from %{port}.
+serve: bin/scratch_dev %{slug} env PORT=%{port} bin/dev
+listens: [0, 36]
+
+# Makes a named state. %{args} becomes one key=value word per argument.
+state: bin/scratch_dev %{slug} bin/dev-state %{name} %{args}
+
+# Paths the browser goes through to be signed in or out, then on to %{to}.
+sign_in: /dev/sessions/as?email=%{email}&to=%{to}
+sign_out: /dev/sessions/out?to=%{to}
+
+# Cookies a clean browser starts with, as name=value.
+cookies: ["cookie_consent=1:declined"]
+
+# Grouse's overlay, labelled with the scenario (below): `overlay` opens a review
+# session from %{brief}, one JSON word, and `notes` prints one's notes.
+overlay: env GROUSE_SESSION=%{brief} bin/rails grouse:sessions:open
+notes: env GROUSE_SESSION_ID=%{session} bin/rails grouse:sessions:notes
+
+# Window sizes beyond the desk's own desktop (1440×900) and phone (390×844).
+sizes:
+  app: {width: 390, height: 844, user_agent: "… Hotwire Native iOS; Turbo Native iOS; …"}
+```
+
+Every key is optional; a scenario that needs a missing one says which.
+
+## Where it runs
+
+With nothing more said, a burst's scenarios run the checkout you review, as
+it is, on port 3100 and a database named after the burst. A burst file can say
+otherwise with a `sitting:`, for a checkout kept for reviewing:
+
+```yaml
+sitting:
+  checkout: ~/code/review-checkout   # moved onto the branch when it has no changes of its own
+  branch: review/everything-together
+  port: 3300
+  slug: sitting
+```
+
+The desk starts the app and makes its states only in a checkout that keeps a
+`.proctolog/app.yml` of its own. A checkout older than that file is older than
+the commands in it, which may not do there what they say: a `prepare` that
+counts on the app reading `%{slug}` would make and fill the app's own
+development database instead. Try it says so beside the pull request, and
+Start refuses.
+
+## What the desk expects back
+
+`state`'s last line of output is one JSON object. `email`, when present, is the
+member the desk signs in through `sign_in`. Every other key whose value is a
+path is a place a scenario can open by name (`opens: lands_on`). Anything
+earlier in the output is ignored, and a command that fails shows its last lines.
+
+```json
+{"email": "clara.vogel@example.com", "lands_on": "/onboarding/pact"}
+```
+
+`sign_in` and `sign_out` are paths on the app, opened by GET in a browser with
+nothing else to go on. They answer by redirecting to `to`, a path. They only
+need to exist where the app runs in development.
+
+## Grouse's overlay
+
+An app with [Grouse](https://github.com/LemuelCushing/grouse-rails) mounted
+can name `overlay` and `notes`. Then a scenario's button opens Grouse's overlay
+in the app too, labelled with the scenario. The panel opens by itself on the
+first page, with a strip at its top: `proctolog · ` and the label, until when
+the session lasts, what to expect, the steps, End session, and Back to the desk,
+which opens the scenario's page on the desk in a new tab. Whatever you say or
+type there is a note on the scenario once you press **Pull notes** beside it.
+
+`overlay` runs after the state is made, and is given `%{brief}`, one JSON word:
+
+| | |
+|---|---|
+| `source` | `proctolog` |
+| `label` | `grouse-rails #7 · Send a note`, or `sartoria · Step 2 · Sign in` for a step of the sitting |
+| `reviewer_label` | who narrates, and each note's author: `Gill (PRoctolog)` |
+| `external_ref` | `proctolog:<burst>/<scenario>@<head>` |
+| `metadata` | `expect`, `steps` (one line each), `desk_url`, and the burst, pull request, scenario, recipe and head |
+
+The member's email is never in the label, what to expect or the steps. Its
+last line of output is `{"public_id": …, "cookie": "grouse_session=…; path=/; …"}`.
+The cookie goes to the browser as it was printed, after the app's own, whichever
+browser the scenario opens in: cookies on `localhost` are shared by every
+port. A refusal, `{"problem": …}`, or a command that fails, never stops the
+entering: the member is signed in all the same, and the desk says why the
+overlay is missing.
+
+Each press opens a session of its own, kept beside its scenario in the marks
+file (`overlays:`, by scenario), with the notes pinned from it. **Pull notes**
+runs `notes` for each with `%{session}`, its `public_id`, and expects
+`{"session": {…}, "notes": […]}` last. Every note it has not pinned yet becomes
+a note on the scenario, once: a fix or a change as a change, a question as a
+question, anything else as a remark, in the owner's words (typed, then spoken),
+then a line with Grouse's link to it, its route and the first templates that
+drew it. A voice note still being written out waits for the next pull. Pinned,
+they go with the next handover like any other note. `notes` boots the app, so
+it runs only when you press.
+
+An app without `overlay` opens as it always did.
+
+## Placeholders
+
+| | |
+|---|---|
+| `%{slug}`, `%{port}` | the sitting's (above) |
+| `%{name}`, `%{args}` | the scenario's `recipe:` and its arguments |
+| `%{email}`, `%{to}` | filled in URL-encoded |
+| `%{brief}`, `%{session}` | the overlay's brief, as one JSON word, and a session's `public_id` |
+
+Commands are split into words before they are filled in, so a value with a
+space stays one word. They run in the sitting's checkout, outside the desk's
+bundle.
+
+## Settings
+
+Beside `app.yml`, `.proctolog/project.yml` says what is true of the repository
+in every checkout of it, so it is kept in Git too:
+
+```yaml
+# Folders of decision records, from the root. A handover asks for a rule you
+# made to be written in CLAUDE.md or a record in one of them.
+decision_records: [docs/adr, docs/solutions/architecture-decisions]
+
+# The themes a decision may name, each with what it means, in the order the
+# desk groups them. Without them, the desk's own stand: proctolog themes.
+themes:
+  copy: What the words on a screen say, and how
+  money: What anything costs
+```
+
+`.proctolog/local.yml`, kept out of Git, says what is true of one machine:
+`capture_kit`, the folder of the capture kit films come from. A key it names
+wins over the same key in `project.yml`, whole: its `themes` replace the
+project's rather than add to them.