wherdr 1.3.2 → 1.3.4

package/README.md

@@ -7,7 +7,7 @@
 <p align="center"><b>A complete workspace for the coding agents running in <a href="https://herdr.dev">Herdr</a>, on your
 computer and on your phone.</b></p>
 
-<p align="center"><a href="https://wherdr.dev"><b>wherdr.dev</b></a> · <code>curl -fsSL https://wherdr.dev/install | sh</code> · <code>herdr plugin install afloury/wherdr</code></p>
+<p align="center"><a href="https://wherdr.dev"><b>wherdr.dev</b></a> · <a href="#ask-your-ai-agent">Ask your AI agent</a></p>
 
 <p align="center"><a href="https://wherdr.dev/demo/"><b>Try it in your browser — no install</b></a>: the real app on scripted agents, nothing runs.</p>
 
@@ -15,7 +15,20 @@ computer and on your phone.</b></p>
 
 ## Quick start
 
-On the computer that runs [Herdr](https://herdr.dev) (≥ 0.9.1), macOS or Linux, one command:
+### Ask your AI agent
+
+**Recommended.** Paste this into Claude Code, Codex or any coding agent: it installs and sets up wherdr for you.
+
+```text
+Read https://wherdr.dev/agent.md and help me set up wherdr. Check what is already installed first, and ask me before installing anything.
+```
+
+It follows [our setup guide for agents](https://wherdr.dev/agent.md): checks what you already have,
+asks before installing anything, sets up your phone over Tailscale, never exposes wherdr to the Internet.
+
+### Or run the installer yourself
+
+On the computer that runs [Herdr](https://herdr.dev) (≥ 0.9.1), macOS or Linux:
 
 ```sh
 curl -fsSL https://wherdr.dev/install | sh
@@ -102,7 +115,8 @@ Details in [Features](#features) and [Security](#security).
 - [Features](#features)
 - [How it works](#how-it-works)
 - [Requirements](#requirements)
-- [Installation](#installation): [the one command](#the-one-command) ·
+- [Installation](#installation): [ask your AI agent](#ask-your-ai-agent-1) ·
+  [or run the installer yourself](#the-one-command) ·
   [which setup?](#which-setup) ·
   [always-on server + Tailscale](#recommended-always-on-server--tailscale) ·
   [other private networks](#other-private-networks) ·
@@ -126,9 +140,12 @@ Details in [Features](#features) and [Security](#security).
 
 ### Everywhere
 
-- **Live agent list**, one line per Herdr space, grouped by state (your turn, working, ready),
-  with a preview of each agent's last answer. When an agent asks for permission or asks a
-  question, the options show on its card: **answer in one tap** without opening it.
+- **Live agent list**, one line per Herdr space, grouped by state (your turn, working, ready).
+  The list is compact by default: agent, title, project badge and state. When an agent asks for
+  permission or asks a question, its card opens on the question and its options: **answer in one
+  tap** without opening it; the card is one line again once answered. Turn off Settings ›
+  Appearance › Home screen › **Compact list** for detailed cards, with the folder, the model and
+  a preview of each agent's last answer.
 - **Conversation view**: the agent's real transcript (Claude Code, Codex and omp), rendered as
   Markdown, with grouped tool calls, images (full-screen viewer with pinch / wheel zoom and pan), timestamps, search and infinite scroll back to the
   first message. Reading a conversation never touches the terminal, so it never resizes a pane.
@@ -136,7 +153,7 @@ Details in [Features](#features) and [Security](#security).
   its prompt, or run in the agent's shell mode (`!`, Claude Code, Codex and omp) after you
   confirm the full command.
 - **Terminal view**: the real terminal (xterm.js, WebGL or DOM renderer) with take-over. Opening
-  it resizes the real pane to your screen; closing it gives the pane the size it had before
+  it resizes the real pane to your screen (or its cell in a split); closing it gives the pane the size it had before
   (after 30 seconds when the connection just dropped, e.g. a locked phone), unless a Herdr
   client attached meanwhile laid it out its own way. On a
   computer, drag over the text on screen to select it: releasing the button copies it, as do
@@ -146,6 +163,22 @@ Details in [Features](#features) and [Security](#security).
   line wrapped by the width is copied in one piece, without the breaks between its rows. An image
   pasted with `⌘V` (Mac), here or in a side-by-side terminal, goes to the agent's machine and its
   path is pasted, which omp and Claude Code attach as an image, as in the conversation.
+- **Interactive agent screens**: in a conversation, an uncertain menu or panel opens the
+  pane's real terminal in a modal window, with arrows, Enter, Escape, Tab, digits and y/n.
+  The rest of the app waits behind a scrim (the window fills the screen on a phone); in a
+  split, only the cell in use opens it. It closes after the agent's message field returns.
+  Close it yourself at any time with its button or a click on the scrim: that releases the
+  terminal without pressing Escape, which goes to the agent, and the same interaction stays
+  closed until you reopen it. Existing native questions, approvals, menus, waiting screens and
+  Claude settings cards keep their controls. The window is a fallback after those
+  recognizers, with two explicit exceptions: Codex's two-column `/usage` menu and
+  its Agent Command Center. The slash menu still lists and sends commands. On a phone, the window
+  temporarily fits the real pane to its width and restores its size on release, using
+  the same lease as Terminal view; it does not shrink 120 columns into unreadable text.
+  A pane already shown in Terminal keeps its existing live view. Try `/usage` on the
+  Codex agent in the browser demo (scripted, no account data).
+  In the compact list, native questions keep their preview and one-tap answers.
+  Unrecognized blocking screens offer an **Open interactive terminal** button.
 - **Composer**: send messages while the agent works (queued, cancellable), attach or paste
   photos and the files the agent can read (Claude Code: PDFs, notebooks, text and code of any
   extension; Codex: notebooks, text and code), run slash commands (`/compact`, `/clear`, `/context`, `/usage`…) and see the output
@@ -159,6 +192,20 @@ Details in [Features](#features) and [Security](#security).
   resumes the same conversation (only while Codex is idle). Codex's own weekly-limit warning
   (its footer gauge, or its startup heads-up) is repeated above the field, with its values, while
   Codex shows it.
+- **After Codex updates itself and exits**: a **Your turn** card offers **Restart Codex**
+  for a new conversation, with the original launch arguments. For an existing conversation,
+  choose **Resume conversation** (its exact session, with the original options) or **Start
+  fresh**. If wherdr cannot identify the session, Resume opens Codex's picker rather than
+  choosing another pane's latest conversation. The usual attention notification applies.
+  Nothing restarts automatically: the pane must still show the same empty shell prompt,
+  with the shell in the foreground. Unrecognized shell prompts require a manual restart
+  in the terminal. wherdr must have observed Codex before it exited.
+  **Dismiss** puts the card away for good: the pane is a plain shell again, to use as you like.
+  Project panel messages wait in the queue until the agent returns; if it does not (Dismiss, or
+  a Codex that simply left), their text goes back into the pane's message field. Continuation
+  prompts (unfinished quotes or heredocs) refuse a restart too. If the final
+  transcript read fails, both conversation choices remain available; a session
+  contradicted by a guessed match is resumed through Codex's picker.
 - **Model and effort pickers** for Claude Code, Codex and omp (omp: its
   "Switch Model" selector, `/switch` or `/model`, and its thinking level, changed with its own
   ⇧⇥ cycle). Changes apply **to the current session only**; wherdr never changes your default
@@ -166,6 +213,30 @@ Details in [Features](#features) and [Security](#security).
 - **New agent**: pick an installed agent (or a plain terminal), a folder, optionally a separate
   Git **worktree** and branch, resume the last conversation, and queue a first message.
 - **Changes view**: Git status and diff of an agent's working folder; worktree management.
+  Review the diff like a pull request: comment on one line or on a **block of lines**. The code
+  itself is plain text — a click on it does nothing, so it can be selected and copied.
+  - **Mouse**: a **+** appears in the gutter of the hovered line; click it to comment that line,
+    or press it and drag over other lines to comment the block. With an editor open, Shift+click
+    another line to change its block.
+  - **Touch**: tap a line number to choose the line, tap another line to extend the block, then
+    **Comment** in the bar pinned at the bottom. Nothing is written by the first tap.
+  - **Keyboard**: one tab stop per file; arrow keys move between lines, Shift+arrows choose a
+    block, Enter opens the editor. In the editor, ⌘/Ctrl+Enter saves and Escape cancels (a second
+    Escape if text would be lost); the window stays open.
+
+  A block stays within one hunk (the other hunks dim while it is chosen) and may mix deleted and
+  new lines. Each comment is a thread under the last line of its block, headed by its lines
+  ("Lines 12–18"), with **Edit** and a two-step **Delete**; the lines it covers are marked in
+  the gutter. Comments, including the text of an editor left open, are saved on this device for
+  that agent, across refreshes and reloads. A block that leaves the diff, or whose code changed
+  between its first and last lines, is flagged above the diff and keeps the excerpt that was
+  commented.
+  **Send review** stays pinned with the number of comments; it groups them by file as
+  `file:12-18 — remark` (`file:12` for one line) followed by a short excerpt of the block, and
+  appends them to the conversation's message draft, preserving existing text; it never sends a
+  message. Deleted lines use the old file's numbers, explicitly labelled. **Discard** clears the
+  local review. Works on remote agents and in the demo too, with no writes to the agent's
+  machine. Browser storage must be available to retain comments after closing the view.
 - **Several machines**: agents of the SSH machines registered in Herdr (`herdr machine add`)
   appear in their own section; everything works the same on a remote agent.
 - **Named Herdr sessions**, **quotas** (remaining Claude and Codex usage limits), **Herdr plugin
@@ -176,7 +247,10 @@ Details in [Features](#features) and [Security](#security).
 ### On a computer
 
 - **Split panes, live**: a tab with several panes is drawn with Herdr's real layout; every pane
-  shows its conversation or terminal live, and the one you click becomes interactive.
+  shows its conversation or terminal live. Every visible terminal fills its cell and follows
+  window and divider resizing, keeping its instance and connection when focus changes.
+  Click a cell to give it the keyboard. Leaving the tab restores each terminal's original size,
+  unless a Herdr client has resized it meanwhile.
 - **Rearrange the layout**: drag a pane onto another to move it, drag a divider to resize
   (arrow keys work on a focused divider); changes go to Herdr itself.
 - **Spaces and tabs**: sidebar with every space, tabs at the top, active tab remembered per space.
@@ -185,7 +259,8 @@ Details in [Features](#features) and [Security](#security).
 - **Keyboard shortcuts** (`Mod` is ⌘ on macOS, Ctrl elsewhere; `Mod+/` or `?` lists them all,
   also in Settings › Computer):
   - `Ctrl/⌘+K` global search across agents and conversations, `Alt+↑/↓` previous / next agent
-    in the list, `Mod+,` settings.
+    in the list, `Mod+,` settings, `H` the [Board](#works-great-with-herdr-projects) (outside a
+    text field and the terminal).
   - `Mod+Alt+N` new agent in a new space, `Mod+Alt+T` new tab in the current space,
     `Mod+Alt+W` close the current pane (after confirmation). They work from the terminal too.
   - With [herdr-projects](#works-great-with-herdr-projects) on the agent's machine: `Mod+Alt+P`
@@ -198,10 +273,16 @@ Details in [Features](#features) and [Security](#security).
     and `Shift+Enter` adds a new line. On a "Your turn" card, `1`–`9` pick an option (on AZERTY
     without Shift too, outside the message field); on the `/resume` card, `Ctrl+A` switches
     between every project and the current one (`⌘A` still selects all on macOS).
+- In the message field, `↑` on the first line recalls previous messages and slash commands;
+  `↓` on the last line returns to newer entries, then restores your draft. History keeps the
+  last 100 texts sent from this device per agent, without attachments or quoted references.
 - **Project board** for [herdr-projects](#works-great-with-herdr-projects): coordinator and threads grouped
   under their project, and a side panel with the project's task lists (to test, to decide,
   to review, in progress, in queue, blocked, to do, backlog — each optional) and one-click
   replies to the coordinator.
+- **Board**: every agent, and with herdr-projects every project, thread and task, in four columns
+  (Blocked, Todo, Ongoing, Finished). Drag a task card to another column, or use its **Move
+  to…** menu, to ask the coordinator to move it.
 - **Settings** in a sidebar, with desktop-only options such as the content width.
 
 ### On a phone
@@ -231,7 +312,10 @@ phone / laptop ──private network──> HTTPS (tailscale serve, private prox
 
 wherdr runs on the same machine as the Herdr server (the "server" below). It uses Herdr's local
 socket API and CLI, reads the agents' transcript files, and serves a client-only Nuxt app. Data
-it keeps (VAPID keys, push subscriptions, passkeys, recent folders) lives in `data/`.
+it keeps (VAPID keys, push subscriptions, passkeys, recent folders) lives in `data/`. So do the
+long texts pasted into the message field, which the server keeps to show them as cards on every
+device: `data/pastes.json`, in clear, readable by the server's user only (mode 600), at most the
+last 100 texts and 2 MB, each one deleted 30 days after it was last sent.
 
 Built with Nuxt 4, Nuxt UI 4, Tailwind 4 and TypeScript; the Herdr gateway (API, WebSockets,
 Web Push, lock) runs in Nitro.
@@ -252,7 +336,20 @@ Web Push, lock) runs in Nitro.
 
 ## Installation
 
-### The one command
+### Ask your AI agent
+
+**Recommended.** Paste this into Claude Code, Codex or any coding agent: it installs and sets up wherdr for you.
+
+```text
+Read https://wherdr.dev/agent.md and help me set up wherdr. Check what is already installed first, and ask me before installing anything.
+```
+
+It follows [our setup guide for agents](https://wherdr.dev/agent.md): checks what you already have,
+asks before installing anything, sets up your phone over Tailscale, never exposes wherdr to the Internet.
+
+<a id="the-one-command"></a>
+
+### Or run the installer yourself
 
 On the computer that runs Herdr, as your user, on macOS or Linux:
 
@@ -289,7 +386,7 @@ Settings, as environment variables (`curl -fsSL https://wherdr.dev/install | WHE
 | `WHERDR_MODE` | — | `native`: Node.js even when Docker is there. `docker`: no plugin, Docker Compose by hand in `WHERDR_DIR` (Linux; see below). |
 | `WHERDR_YES` | — | `1` answers yes to every question (non-interactive use). |
 | `WHERDR_NO_BROWSER` | — | `1` never opens a browser. |
-| `WHERDR_REF` | latest | Git tag or branch of the plugin (or of `docker-compose.yml` with `WHERDR_MODE=docker`). |
+| `WHERDR_REF` | main | Git tag or branch of the plugin (or of `docker-compose.yml` with `WHERDR_MODE=docker`). |
 | `WHERDR_PLUGIN` | `afloury/wherdr` | A local checkout to link and build instead (development, tests). |
 
 **Docker by hand, with the script:** `curl -fsSL https://wherdr.dev/install | WHERDR_MODE=docker sh`
@@ -615,8 +712,8 @@ setup by itself:
   `~/wherdr` (`docker-compose.yml`, `.env`), the same files as `WHERDR_MODE=docker` of
   [the one command](#the-one-command).
 - **Node.js 22** everywhere else, and always on macOS (Docker Desktop cannot reach Herdr's
-  socket): the plugin downloads the prebuilt npm package of its version (or builds wherdr in its
-  own folder when that fails), copies it to `~/wherdr/app` and runs it detached from there, with
+  socket): the plugin downloads the prebuilt package of its version from GitHub Releases and
+  verifies its SHA-256 checksum, copies it to `~/wherdr/app` and runs it detached from there, with
   its pid and log (`wherdr.log`) in `~/wherdr`. Herdr builds plugins in a temporary folder and
   then moves them, so the server never runs from the plugin folder. Bun works too when Node.js 22
   is missing. Without either, the install stops and says so.
@@ -738,6 +835,27 @@ home screen and in Settings › About, with the release notes and the exact comm
 Hide it until the next version with ×. Set `WHERDR_UPDATE_CHECK=off` to disable the check. The
 installed version is shown in Settings › About.
 
+GitHub release packages (including the bundled agent skill), Docker images, and Homebrew
+updates are published without waiting for npm moderation. Native plugin installs and updates
+use the GitHub `.tgz` and verify its SHA-256 checksum before extraction. A failed one-tap
+download or checksum check leaves the running version in place. Plugin installation tries
+GitHub first, then the prebuilt npm package of the exact same version (with its registry integrity hash), and only builds from source when neither works.
+This also keeps older 1.3.x releases without GitHub archives installable with Node.js or Bun.
+Packages predating the bundled skill retain the plugin checkout's commands and skill, so
+skill refresh, installation and uninstallation remain available.
+The installer fetches `main` explicitly unless you set `WHERDR_REF`.
+
+The SHA-256 checksum detects damaged downloads. It is served beside the archive, so someone
+who can replace both files can make them match; it does not prove the publisher’s identity
+or protect against replacement of the archive and checksum together.
+
+`npm install -g`, `npx`, `bunx` and `pnpm dlx` still need npm to serve the wherdr package.
+Their banner waits for registry availability; Homebrew's banner waits for its formula.
+Versions through 1.3.2 use GitHub's `latest` marker and an npm-based updater. That marker only
+advances once npm **and** Homebrew are ready, so their existing Update button continues to work.
+To update an older native plugin earlier, rerun the installer or press **U** in its Herdr panel.
+See [Releasing](docs/RELEASING.md) for the publication order and recovery steps.
+
 **Update in one tap.** When wherdr runs from the Herdr plugin (Node.js mode), a global npm install
 or Homebrew, the banner has an **Update** button instead of the command, for a session opened on
 this computer (`localhost`) or unlocked with a passkey. wherdr installs the new version in a
@@ -749,7 +867,7 @@ and the app says so. Every step is logged in `~/wherdr/update.log`.
 
 | Setup | What Update does |
 | --- | --- |
-| Herdr plugin, Node.js | Unpacks the npm package of the new version into `~/wherdr/app`, keeps the old copy, restarts |
+| Herdr plugin, Node.js | Verifies and unpacks the GitHub release package of the new version into `~/wherdr/app`, keeps the old copy, restarts |
 | `npm install -g wherdr` | `npm install -g wherdr@X.Y.Z`, then restarts (login service included) |
 | Homebrew | `brew upgrade wherdr`, then `brew services restart wherdr` |
 
@@ -837,6 +955,92 @@ All settings are environment variables (`.env` with Docker).
 In the app, **Settings** holds per-device preferences: language, theme, notifications, terminal
 text size and renderer, typing effect, what the home screen shows, and the passkey lock.
 
+**Settings › Conversation › Reply style** chooses how an agent's reply offers to be quoted in
+the field, question by question and point by point (a list item or a paragraph that asks
+nothing), so that one message answers them all:
+
+| Style | A question | A point |
+| --- | --- | --- |
+| **Icon** (default) | A small `↳` after it, in the middle or at the end of the message. | A grey `↳` at its end: on hover on a computer, always there and pale on a phone. |
+| **Tap the text** | No button: the question is underlined, tap or click it. | Click it on a computer. On a phone, tap it, then **↳ Discuss**: a single tap never quotes, so reading, scrolling and selecting text stay as they are. |
+| **List under the message** | A number after it, and the questions listed under the message. | **+ Quote a point** under the message, then the point. Offered when the reply has a list item to quote, or two points or more: not under one paragraph of prose. |
+
+Every one of these is a button reachable with the keyboard (`Tab`, then `Enter`), and selecting a
+passage still offers **Reply** on it. A quoted question or point shows `✓`.
+
+**One syntax for every reference.** Whatever you reply to, the field gets one line that names it,
+and your answer goes on the lines below:
+
+```
+↳ Quote message 11:37 ~k3f : I can merge the PR —
+Go ahead.
+↳ Quote point 11:37 ~k3f : Shall I tag the release today? —
+Yes
+↳ Quote decision 11:37 #3 ~k3f : Publish the release notes on the site? —
+No
+```
+
+| Line | Written by |
+| --- | --- |
+| `↳ Quote message <time> ~<code> : <start of the message> —` | **Reply** under an agent message. |
+| `↳ Quote point <time> ~<code> : <excerpt> —` | `↳` on a question or a point, **Reply** on a selected passage. |
+| `↳ Quote decision <time> #<n> ~<code> : <question> —` | **Yes**, **No** or `↳` on a row of a decision table. |
+| `↳ Quote decisions <time> #<rows> ~<code> : <questions> —` | **OK to all** on a decision table. |
+| `↳ Decision: <task> —`, `↳ Problem: <task> —`, `↳ Question: <task> —`, `↳ Detail on <task> —`, `↳ Feedback on <task> —` (and their French labels) | **Answer**, **Problem**, **Question**, **Clarify** and **Comment** in the Project panel. |
+
+- The time is the one shown on the agent's message, so an answer to an earlier message is never
+  read as an answer to the last one. The types are the same words in every language.
+- The code after `~` is three characters wherdr derives from the message (and the rank of the
+  table, from the second table of a message on). It tells apart two messages of the same minute
+  and two tables of one message, whatever the excerpt shows. The field draws it dimmed, like
+  the words before the excerpt; the quote of a sent message leaves it out. The rows of **OK to
+  all** are the numbers the table really has: `#1-4`, or `#1,4` when rows 2 and 3 do not exist.
+- A reference is a whole line: it starts with `↳` in the first column and ends with ` —` at the
+  end of the line, and only there, so an excerpt may hold dashes of its own. The excerpt is plain
+  text on one line; a long one is cut with `…` (a message keeps its start, a passage its start
+  and its end).
+- Several references fit in one message, each followed by its answer.
+- Anything else is your own text: a `>` at the start of a line, a `↳` line of an unknown type or
+  with words after its dash. Text you paste never becomes a reference either: a pasted line that
+  reads like one gets a `\` before its `↳`. A long paste, shown as a **Pasted text** card, is
+  sent exactly as it was pasted.
+- In the conversation, each reference of a sent message shows as a quote; tap it to see the
+  message it names. Messages sent earlier with `> ` lines still show as quotes.
+
+**Settings › Conversation › Quoted replies** chooses how the field shows these lines: **Tokens,
+native field** (default) draws each one as a token in the usual field, **Plain text** shows the
+same lines as text, a fallback if the tokens misbehave. The message sent is the same.
+
+A **closed question**, one that yes or no answers in full, also gets **Yes** and **No** next to
+its `↳` (at the end of its row in the list style). A tap refers to the question and writes the
+answer under it, in the language of the interface, exactly as Reply and typing would; nothing is sent, so several questions can be
+answered in a row before sending. The keyboard stays down on a phone. Tapping the other answer
+replaces the first; words you typed under a quote are never replaced. The rule is cautious, and
+in doubt only Reply is offered: a single sentence that opens like a yes/no question (`Shall I…`,
+`Do you…`, `Is it…`, `Want me to…`, `Est-ce que…`, `Je lance… ?`, `On…`, `Dois-je…`) or ends
+with `, OK?` / `, d'accord ?`, with no alternative (`or`, `ou`), no interrogative word (`which`,
+`how`, `quel`, `comment`…) and no negation.
+
+A **decision table**, a Markdown table whose rows are numbered questions as a coordinator writes
+them, gets a panel right under it: **OK to all** refers to the whole table and writes `OK to all`
+under it (a second tap takes it back), and each row has **Yes**, **No** and `↳`, which refer to
+the row by its number and write `Yes` or `No` under it, or nothing for an answer in words; a row
+that asks an open question has `↳` alone. Every answer names the message and the row, even for
+the last message: the agent may write another one before you send. In French: `OK tout`, `Oui`,
+`Non`. Here too everything is composed in the field and you send. A table qualifies when it has a
+number column (a header `#`, `N°`, `No`, `Num`, `ID` or `Q` over short numbers, each once) and a
+question column, known by its header (`Question`, `Decision`, `Choix`…), by cells that all end
+with `?`, or by an advice column next to it (`Avis`, `Recommendation`, `Suggestion`…). Any other
+table is left as it is.
+
+Above the field, **N questions unanswered** counts the questions of the agent's last message
+(and the rows of its decision tables) that your draft does not answer yet; tap it to scroll to
+the first one. A question counts once it is quoted, a row once it is answered, quoted or covered
+by **OK to all**; when the message asks one thing only, any words you type answer it. The line
+goes when everything is answered and when you send, and it never shows for earlier messages,
+while the agent is working, or while it waits on a prompt. It hangs from the top edge of the
+field, so nothing moves when it comes or goes.
+
 ## Several machines (SSH)
 
 wherdr also shows the agents of the **SSH machines registered in Herdr** — the ones the Herdr
@@ -911,15 +1115,33 @@ gets a default workspace, as with any attached client.
 
 ## Works great with herdr-projects
 
-[herdr-projects](https://github.com/eliasstravik/herdr-projects) is a Herdr plugin that runs a
+[herdr-projects](https://github.com/afloury/herdr-projects) is a Herdr plugin that runs a
 project as one **coordinator** conversation and parallel **threads**, each in its own Git
-worktree. It is optional; with it installed, wherdr adds:
+worktree. It is optional. wherdr works with its **0.2** line, installed from the fork (or with
+**Install herdr-projects** in **Settings → Plugins → herdr-projects**):
+
+```sh
+herdr plugin install afloury/herdr-projects --ref v0.2.36 --yes
+```
+
+> **herdr-projects 1.x is not supported yet.** Upstream
+> ([eliasstravik/herdr-projects](https://github.com/eliasstravik/herdr-projects)) moved to a 1.x
+> that is a different product (a task board, with no projects, `TASKS.md` or threads), and its
+> first run moves `~/.herdr-projects` to `~/.herdr-projects-legacy`. Settings says when a machine
+> has 1.x and gives the command to go back to 0.2. A 0.2 installed from upstream must not run
+> `herdr-projects update`, which would install 1.x: reinstall it from the fork
+> (`herdr plugin uninstall herdr-projects && herdr plugin install afloury/herdr-projects --ref v0.2.36 --yes`;
+> projects stay in `~/.herdr-projects`). The pinned v0.2.36 release downloads a prebuilt binary
+> for macOS or Linux, on ARM64 or x86_64.
+
+With it installed, wherdr adds:
 
 - **Project groups** in the agent list: the coordinator first, its threads indented under it,
   grouped by repository (`Repo web-shop · 2 worktrees`), with their thread number and state.
 - **Project panel** next to the coordinator (a side panel on a computer, a tab on a phone). It
   reads the project's `TASKS.md` and shows the lists it has, always in this order, with the open
-  threads live (state, progress, report) and resolved threads under Done:
+  threads live (state, progress, report) and threads marked done under Done (**Tasks** tab; the
+  **Threads**, **Inbox**, **Routines**, **Settings** and **Memory** tabs are described below):
 
   | List | Meaning | Buttons |
   | --- | --- | --- |
@@ -931,7 +1153,7 @@ worktree. It is optional; with it installed, wherdr adds:
   | **Blocked** | Waiting for someone or something external | Unblock, Clarify |
   | **To do** | To do soon, in your priority order; never launched on its own | Move up / down, Queue it, Launch now, Clarify, Back to backlog |
   | **Backlog** | Everything else | Launch, Clarify |
-  | **Done** | Resolved threads | |
+  | **Done** | Threads marked done | |
 
   Every list is **optional**: you and your coordinator pick the ones a project uses (a small
   project may only need Backlog, In progress and Done); any other `##` list shows in a neutral
@@ -942,6 +1164,73 @@ worktree. It is optional; with it installed, wherdr adds:
   header shows the thread slots in use (`max_parallel_threads` in `PROJECT.md`) and the next
   task, plus the machine's global limit when one is set
   (`2 of 2 thread slots in use on <machine> (all projects)`).
+- **Threads tab** of the Project panel: every thread of the project, including those marked done.
+  Open threads are grouped as herdr-projects groups them (Your turn, Ready for review, Working…),
+  each with its machine and agent profile; threads marked done stay in their own folded section,
+  shown by pages of 30. One filter covers both (ID, title, machine, profile). A tap opens the
+  thread's record: state, its **Next** list, branch, dates, and these actions:
+
+  | Action | Command | Asks first |
+  | --- | --- | --- |
+  | **Acknowledge** | `thread ack`: you have seen its report | |
+  | **Restart** | `thread restart`: bring back a thread whose pane is gone or whose start failed | |
+  | **Stop** | `thread stop`: Escape in its agent's pane | Yes |
+  | **Mark done** | `thread resolve`: final copy, then its worktree, merged branch and tab are cleaned up (report and library kept) | Yes |
+
+  Open agent, View report and Pull request are there too when they apply. wherdr only runs
+  these `herdr-projects` commands on the coordinator's machine (and reads `thread show --json`);
+  it writes no thread file itself, and herdr-projects has the last word (it refuses to restart a
+  running thread, for instance): its answer is shown as is. With Docker, **Mark done** runs in
+  the container, where the home folder is read-only: a thread of this machine is marked done and
+  its open workspace removed through Herdr, but its merged branch, or a worktree whose workspace
+  was already closed, may stay. herdr-projects lists what it kept, and
+  `herdr-projects sweep <project>` on the host removes it.
+- **Inbox tab**: the project's unhandled inbox items, what herdr-projects tells the coordinator
+  (a thread's new report, a routine due, a machine out of reach…), oldest first, up to 100. An
+  item about a thread shows the thread's title and opens it. **Done** (✓) marks one item as
+  handled with `herdr-projects inbox done`; a coordinator that has not read it yet will not see
+  it any more. Summaries are shown as plain text.
+- **Routines tab**: each routine's schedule, whether it is enabled, its kind (prompt only, or a
+  command and its approval) and its last and next run. Read-only: wherdr never approves,
+  switches or runs a routine, and does not expose the plugin's safety settings.
+- **Settings tab**, read-only: what the project's `PROJECT.md` sets, the keys
+  `herdr-projects set` changes (name, goal, coordinator and thread profiles,
+  `max_parallel_threads`, `auto_resolve_days`, `nudge`, `mute`, repositories). A key the file
+  leaves out shows the plugin's default, marked as such. Safety settings are not shown.
+- **Memory tab**, read-only: `MEMORY.md` (the index) and the `.md` files of `memory/`, with the
+  title and hook the index gives them; a file the index does not mention is listed by name. A
+  tap opens one, rendered as Markdown. The coordinator writes memory, wherdr never does.
+
+  With six tabs, the bar scrolls sideways on a phone and in a narrow side panel; a fade on its
+  edge says there are more.
+
+  herdr-projects (0.2.34) has no JSON output for the inbox or the routines: wherdr reads the
+  front matter of the project's `inbox/*.md` files, and the tab-separated lines of
+  `herdr-projects routine list`, showing the run texts (`last … · next …`) as printed. No command
+  prints a project's settings or memory either: those two tabs read the files named above.
+- **Board** (`H`, or the board button above the agent list): every project, thread, task and
+  agent at a glance, in four columns. Agents outside projects show too. Each card opens what it
+  stands for: a project or task opens its Project panel, a thread opens its agent (or its report
+  once closed), an agent opens its conversation. A project card takes the most urgent column of
+  its cards and counts them; Finished shows the 5 most recent threads and done tasks of each
+  project, **Show all** the rest. The filter button in the header hides chosen projects, or the
+  agents outside projects (**Other agents**); the choice is kept on the device, and a new project
+  shows until you hide it.
+
+  | Card | Blocked | Todo | Ongoing | Finished |
+  | --- | --- | --- | --- | --- |
+  | **Task** (its `TASKS.md` list) | Blocked | To test, To decide, To review, In queue, To do, Backlog, other lists | In progress without an open thread | Done, or a checked line |
+  | **Thread** | Its agent is your turn, or *waiting on you* | *Ready for review* | Working, landing, idle | Done |
+  | **Agent** | Your turn | | Working, starting, restarting | Done, ready |
+
+  Moving a **task** card (drag and drop on a computer, **Move to…** everywhere) sends the
+  coordinator the Project panel's message when one says it (**Launch now** from To do or In
+  queue, **Launch** from Backlog, **Unblock** from Blocked, **Tested** from To test, **Reviewed**
+  from To review), otherwise `↳ Mark blocked: …`, `↳ Move to To do: …` or `↳ Mark done: …`. The
+  card shows *Sent* until the coordinator has moved the line; only the allowed columns are
+  offered, and To decide tasks wait for your answer. Thread, agent and project cards follow
+  what they do and do not move. The server reads every project at once
+  (`GET /api/board`); a project on an offline machine keeps its last read, marked as such.
 - **Max threads per machine**, across all projects: herdr-projects only limits threads per
   project, so three coordinators could still start a dozen threads on one small machine. Set a
   limit per machine in **Settings → Plugins → herdr-projects** (empty `—` = no global limit;
@@ -973,7 +1262,8 @@ worktree. It is optional; with it installed, wherdr adds:
   ```markdown
   - [ ] Stop button on iPhone [b:red(bug)] [b:gray(t-0140)](t-0140) [b:blue(PR #12)](https://github.com/owner/repo/pull/12) (me)
   ```
-- **Settings → Plugins → herdr-projects**: install status per machine, the `TASKS.md` convention,
+- **Settings → Plugins → herdr-projects**: install status per machine (with a warning for an
+  unsupported 1.x, or a 0.2 from upstream whose update would install 1.x), the `TASKS.md` convention,
   a template, the max threads per machine and the coordinator rules to copy.
 - **Projects entries** in the menus when the plugin is on the agent's machine: an agent's menu
   (`…`) and its card's (right click, long press on the phone) offer the Project panel, **New
@@ -996,17 +1286,57 @@ worktree. It is optional; with it installed, wherdr adds:
 
 The Project panel only works well when the coordinator follows its conventions: which lists
 mean what, the badges, `(agent → t-NNNN)`, and what to do with each message the buttons send
-(`✓ Tested: …`, `✗ Problem: … — …`, `↳ Queue: …`…). They are written once, as an agent skill:
+(`✓ Tested: …`, `↳ Queue: …`, `↳ Problem: … —` or `↳ Decision: … —` with the answer below it…). They are written once, as an agent skill:
 [`skills/wherdr/SKILL.md`](skills/wherdr/SKILL.md).
 
-- **Herdr plugin**: the install links the skill for every coordinator, whatever its agent:
-  `~/.claude/skills/wherdr` (Claude Code, or `$CLAUDE_CONFIG_DIR/skills`) and
-  `~/.agents/skills/wherdr` (Codex, omp), each only when that agent is installed. Both point to a
-  copy in `~/wherdr/skills/wherdr`, refreshed on each update. An existing `wherdr` skill that is
-  not this link is left alone. Remove the links with `sh scripts/herdr-plugin.sh skill uninstall`
-  in the plugin folder.
-- **Other installs**: link or copy `skills/wherdr` into your agent's skills folder yourself, or
-  paste **Settings → Plugins → herdr-projects → Copy rules for the coordinator** to it.
+The npm package (also used by Homebrew) and Docker image include the skill from that
+release. Installation is best effort: a missing agent or an unwritable home never blocks
+wherdr. It links `~/.claude/skills/wherdr` (or `$CLAUDE_CONFIG_DIR/skills/wherdr`) only
+when the Claude configuration folder exists, and `~/.agents/skills/wherdr` only when
+`.agents`, `.codex` or `.omp` exists. Links point to a stable copy in
+`${WHERDR_DIR:-$HOME/wherdr}/skills/wherdr`. Existing skills from elsewhere are left alone.
+Relative `WHERDR_DIR` resolves from the working directory; relative `CLAUDE_CONFIG_DIR`
+resolves from HOME, including when saved in a login service. Unchanged content is not rewritten.
+A broken link is repaired only when local metadata proves wherdr created it.
+
+| Install mode | Skill installation and refresh |
+| --- | --- |
+| npm / npx / Bun / pnpm | On `wherdr`, `wherdr run`, `wherdr start` or `wherdr service install`; after updating the package, the next start refreshes it. |
+| Homebrew | On `wherdr` startup, including the Homebrew service; restart the service after `brew upgrade`. |
+| One-tap update (npm, Homebrew, native plugin) | Restarting wherdr refreshes the skill from the newly installed package; rollback restores the previous copy when that package also bundles the skill. |
+| Herdr plugin, Node.js | On plugin installation / reinstallation, and on startup from its installed package. |
+| Herdr plugin, Docker | On plugin installation and Update, extracted from the pulled image on the host. |
+| One-command installer, Docker | After each pull, including reruns and `WHERDR_MODE=docker`; saves host helpers in `$WHERDR_DIR/skill-installer`. |
+| Docker by hand | Run the host-side command below after the initial pull and after each image update. |
+| From source | Use `node bin/wherdr.mjs` after building, or run `sh bin/lib/install-skill.sh` yourself after updating; `npm start` alone does not install the skill. |
+
+Docker cannot write the host's agent folders through its read-only home mount. From the
+repository checkout on the **host**, after pulling your image, run:
+
+```sh
+sh bin/install-docker-skill.sh ghcr.io/afloury/wherdr:latest
+```
+
+Pass your image tag if different. The helper creates a stopped temporary container, copies
+only `/app/skills/wherdr/SKILL.md` out of it, uses the local host installer, then removes
+the container. No host home is mounted into it. Repeat this command after each manual Docker update; Docker has no one-tap
+update in the app. Manual failures (including older images without the skill) return a
+nonzero status with diagnostics; plugin and one-command installation warn and continue. Without a checkout, use
+`sh "${WHERDR_DIR:-$HOME/wherdr}/skill-installer/bin/install-docker-skill.sh" <image>` after the one-command install.
+
+Remove managed links with `sh bin/lib/install-skill.sh uninstall` (or
+`sh scripts/herdr-plugin.sh skill uninstall` in the plugin folder). Uninstall leaves
+`~/.local/state/wherdr/skill-disabled`: subsequent starts and updates respect it, even if
+`WHERDR_DIR` changes. To re-enable, explicitly run `sh bin/lib/install-skill.sh install`
+or the plugin's `skill install` (or the Docker host helper above). `WHERDR_SKILL=off`
+disables all installation and refresh, including explicit install; export it for interactive
+starts or set it when installing the login service to preserve it there.
+
+Two limitations remain: rollback to an older package without the helper (such as 1.3.2)
+leaves the failed release's skill in place. With multiple wherdr versions sharing an account,
+the last one started supplies the skill; there is no version comparison.
+
+You can also paste **Settings → Plugins → herdr-projects → Copy rules for the coordinator** to your agent.
 
 ## Herdr plugins
 
@@ -1060,16 +1390,13 @@ container talks to the Herdr server running on the host.
   allowed"); add it to `HERDR_WEB_ALLOWED_HOSTS`, then restart wherdr. This host check also
   applies to WebSockets.
 - **Passkey lock** (Settings → Security, recommended): once a passkey is registered, the API,
-  images, photos and WebSockets require an unlocked session (signed HttpOnly cookie). Two limits
-  apply:
-  - **12 hours without use**: the session slides, so the app only locks again after 12 hours
-    without any request (or when you lock it from Settings).
-  - **Maximum duration** since the last passkey unlock, set in Settings → Security for every
-    device: 1 day, 7 days (default), 30 days, 90 days or 1 year. The unlock time is signed in the
-    cookie and the slide never moves it. Past it, the device asks for the passkey again at the
-    next opening of the app (launch, reload, or back in the foreground), never in the middle of
-    use; the app warns in the last hours. A client that never reopens is cut 12 hours after the
-    deadline. A shorter duration applies to the sessions already open.
+  images, photos and WebSockets require an unlocked session (signed HttpOnly cookie). One rule
+  applies: the duration set in Settings → Security for every device, counted from the last
+  passkey unlock, used or not in between: 1 day, 7 days (default), 30 days, 90 days or 1 year.
+  There is no idle lock. Past it, the device asks for the passkey again at the next opening of
+  the app (launch, reload, or back in the foreground), never in the middle of use; the app warns
+  in the last hours. A client that never reopens is cut 12 hours after the deadline. A changed
+  duration applies to the sessions already open.
 
   A network error or a server restart never locks the app. **Lock all devices** (Settings →
   Security, for a lost or stolen device) ends every session, this one included, and keeps the
@@ -1099,7 +1426,8 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
   `herdr server`). With Docker, check that `HOST_HOME` and `PUID` match your user.
 - **No conversation, only the terminal**: the agent was started before the Herdr integration
   was installed, or it is not Claude Code / Codex / omp. Install the integration
-  (`herdr integration install claude|codex|omp`) and start a new agent.
+  (`herdr integration install claude|codex|omp`) and start a new agent. When the integration
+  is missing on the agent's machine, the conversation says so with the exact command.
 - **Passkeys or notifications unavailable**: the page must be served over HTTPS (or
   `localhost`). On iPhone, notifications need the app installed on the home screen.
 - **HTTP 403 "This address isn't enabled yet"**: for a tailnet address, run the command the

package/bin/install-docker-skill.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# Run on the HOST after pulling an image; no container is started, no home mounted.
+# Usage: sh bin/install-docker-skill.sh <image> [refresh|install]
+extract_skill() (
+  set -eu
+  [ -n "${1:-}" ] || { echo 'usage: install-docker-skill.sh <image> [refresh|install]' >&2; exit 1; }
+  [ "${WHERDR_SKILL:-}" != off ] || { echo 'wherdr skill: disabled by WHERDR_SKILL=off'; exit 0; }
+  if [ "${2:-install}" != install ] && [ -e "${HOME:-}/.local/state/wherdr/skill-disabled" ]; then exit 0; fi
+  helper=$(CDPATH= cd -- "$(dirname "$0")" && pwd -P)/lib/install-skill.sh
+  tmp=$(mktemp -d)
+  container=
+  trap '[ -z "$container" ] || docker rm "$container" >/dev/null 2>&1; rm -rf "$tmp"' EXIT HUP INT TERM
+  container=$(docker create -- "$1")
+  mkdir -p "$tmp/skills/wherdr"
+  # Only data crosses the image boundary. The executed helper is local.
+  docker cp "$container:/app/skills/wherdr/SKILL.md" "$tmp/skills/wherdr/SKILL.md"
+  sh "$helper" "${2:-install}" "$tmp"
+)
+# Unlike startup, manual and plugin callers see failures and useful diagnostics.
+extract_skill "$@"